.. _server-command-line:

======================
Running mdtmFTP server
======================

mdtmFTP server command syntax:

.. code-block:: shell

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

Among those options,

* ``-control-interface <ip_address>`` specifies a control interface
  for the server.

* ``-data-interface <ip_address>`` specifies a data interface 
  for the server.

* ``-password-file <passwd_file>`` specifies a password file 
  for username/password authentication.

* ``-p <port_num>`` specifies a port that mdtmFTP server listens on.

* ``-c <server.conf>`` specifies a configuration file to set data
  transfer parameters.


.. _server-capabilities:

Running mdtmFTP server with or without root privilege
=====================================================

For the purpose of performing permission checks, traditional UNIX
implementations distinguish two categories of processes: `privileged`
processes (whose effective user ID is 0, referred to as superuser or
root), and `unprivileged` processes (whose effective UID is
nonzero). Privileged processes bypass all kernel permission checks,
while unprivileged processes are subject to full permission checking
based on the process's credentials (usually: effective UID, effective
GID, and supplementary group list).

Starting with kernel 2.2, Linux divides the privileges traditionally
associated with superuser into distinct units known as `capabilities`,
which can be independently enabled and disabled.

Running mdtmFTP server requires four capabilities:

* ``CAP_SYS_NICE``, to bind threads to cores.

* ``CAP_IPC_LOCK``, to lock memory.

* ``CAP_SYS_RESOURCE``, to increase pipe capacity.

* ``CAP_SYS_ADMIN``, to increase the maximum number of open files.

Therefore, when system admin runs mdtmFTP server as root,
no additional actions are needed.

However, if mdtmFTP server is run as a normal application, please add
the above capabilities to ``mdtm-ftp-server`` binary.

Assuming ``mdtm-ftp-server`` has been installed in the directory
``/opt/mdtmftp``, please run the following command to add
the required capabilities:

.. code-block:: console

   $ sudo setcap \
      cap_sys_nice,cap_ipc_lock,cap_sys_admin,cap_sys_resource+ep \
      /opt/mdtmftp/sbin/mdtm-ftp-server
  
  
Server 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.