.. _source-release:

=============================
Obtaining and running mdtmFTP
=============================

There are different ways to obtain and run mdtmFTP:

* to build, and install MDTM library and mdtmFTP programs from
  sources, or

* to use Docker container images, or

* to use Singularity container images.

**This document discusses the source release**.  If you are looking
for information on using Docker or Singuarity images, please find the
manuals at http://mdtm.fnal.gov.


Requirements
============

mdtmFTP has been tested on Linux systems. The system must have a Linux
kernel later than 3.12.23.


Building mdtm and mdtmFTP
=========================

To build mdtm library and mdtmFTP, the following tools are required:

* C++ and C compilers.
* GNU Autotools
* Development packages for OpenSSL, numactl, hwloc, lvm2 mosquitto,
  json-c, krb5, ncurses.


Install dependencies
--------------------

To install build tools and dependencies on RHEL and derivatives:

.. code-block:: console

  $ sudo yum install \
      gcc gcc-c++ make autoconf automake libtool m4 \
      numactl-devel hwloc-devel lvm2-devel libblkid-devel \
      openssl-devel mosquitto-devel json-c-devel \
      krb5-devel libtool-ltdl-devel ncurses-devel \
      libuuid-devel rrdtool-devel

On Debian and Ubuntu:

.. code-block:: console

  $ sudo apt install \
      gcc g++ make autoconf automake libtool m4 \
      libnuma-dev libhwloc-dev liblvm2-dev libblkid-dev \
      libssl-dev libmosquitto-dev libjson-c-dev \
      libkrb5-dev libltdl-dev libncurses5-dev \
      uuid-dev librrd-dev


Install mdtm library
--------------------

1. Create a building directory:

.. code-block:: console

  $ mkdir ~/build
  $ cd ~/build

2. Download ``mdtm-1.0.5.tar.gz`` software package from the `project website <http://mdtm.fnal.gov/Releases.html>`_, and extract it in ``~/build``.

3. Build and install mdtm library:

.. code-block:: console

  $ tar –xvz mdtm-1.0.5.tar.gz
  $ cd mdtm-1.0.3
  $ ./autogen.sh
  $ ./configure --prefix=$prefix
  $ make
  $ sudo make install


Install mdtmFTP
---------------

4. Download mdtmFTP software package from `the website <http://mdtm.fnal.gov/Releases.html>`_.

5. Extract the downloaded ``mdtmftp-1.1.1.tar.gz`` archive to ``~/build``.

6. Build and install mdtmFTP:

.. code-block:: console

  $ tar xvfz mdtmftp-1.1.1.tar.gz
  $ cd ~/build/mdtm
  $ ./autogen.sh
  $ ./configure --prefix=$prefix \
       PKG_CONFIG_PATH=/usr/local/lib/pkgconfig/:$PKG_CONFIG_PATH
  $ make && make install

Two major mdtmFTP binary programs will be generated: ``$prefix/bin/mdtm-ftp-client`` - the mdtmFTP client executable, and ``$prefix/sbin/mdtm-ftp-server`` - the mdtmFTP server exectuable.


Configuring and running mdtmFTP server
======================================

Decide whether to run mdtmFTP server as root or non-root
--------------------------------------------------------

You can run mdtmFTP server either as root, or as non-root.
If you choose to run the server as non-root, please add the needed
capabilities to the server so that it can function correctly.

Please see :ref:`server-capabilities` for details on how to run
mdtmFTP server as a non-root user.


Create configuration files
--------------------------

* For versions >= 1.1.1, mdtmFTP is configured by using a JSON configuration file ``mdtmconfig.json``. Please
  refer to :ref:`configuring-server-json` for details.

* For versions < 1.1.1, mdtmFTP is configured by using two configuration files:

        - ``mdtmconfig.xml``. Please refer to :ref:`configuring-server-xml` for details.
        - ``server.conf``. Please refer to :ref:`configuring-server-conf` for details.

Choose an authentication method
-------------------------------

mdtmFTP supports two types of authentication:

* Username/password authentication, 
* GSI certificate-based authentication

Please choose an authentication method that suits your needs. See :ref:`configure-security` for details.


Create local account(s) and grant user access to mdtmFTP server
---------------------------------------------------------------

First, create local user accounts in the host where mdtmFTP server will run. 

Then, grant user access to mdtmFTP server:

* For username/password authentication, you need create and configure a 
  password file for mdtmFTP server. See :ref:`credentials-username-password` for details.

* For GSI certificate-based authentication, you need create the mapping 
  between user certificates and local user accounts 
  by editing ``/etc/grid-security/grid-mapfile`` on the server side. 
  See :ref:`credentials-gsi` for details.


Running mdtmFTP server
----------------------

mdtmFTP server command syntax:

.. code-block:: console

   $ mdtm-ftp-server \
      -control-interface <ip_address> \
      -data-interface <ip_address> \
      -password-file <passwd_file> \
      -p <port_num> \
      -c <server.conf>

See section on :ref:`server-command-line` for details.


Configuring and running mdtmFTP client
======================================

mdtmFTP client can be launched either as root or as non-root.


mdtmFTP client configuration file
---------------------------------

* For versions >= 1.1.1, mdtmFTP is configured by using a JSON configuration file ``mdtmconfig.json``. Please
  refer to :ref:`configuring-client-json` for details.

* For versions < 1.1.1, mdtmFTP is configured by using a XML configuration file ``mdtmconfig.xml``. Please 
  refer to :ref:`configuring-client-xml` for details.


Running mdtmFTP client
----------------------

mdtmFTP client command syntax:

.. code-block:: console

   $ mdtm-ftp-client [-ipv6] -p <parallelism> [-splice] source_url destination_url

See section on :ref:`client-command-line` for details.