SFTPPlus Documentation

Start Page 2. Installation and Upgrade Instructions 2.3. Linux Installation

2.3. Linux Installation

2.3.1. Overview

For Linux systems, SFTPPlus is distributed as a gzipped TAR archive. Installing SFTPPlus on Linux consists of unpacking the archive, initializing the configuration, and generating the SSH keys and the SSL certificate to be used by the product.

The included default configuration requires the creation of a system account, named sftpplus, under which the SFTPPlus process is executed. Optionally, you may choose to start SFTPPlus as root, especially if you want it to authenticate operating system users. But the sftpplus user is still required in order to drop privileges for all other operations.

To have SFTPPlus started at boot, you may use one of the included unit, init, or service files. These service initialization files have been tested on all supported Linux distributions, but they should work on other Linux systems as well.

2.3.2. Unpacking the archive

After downloading the compressed archive, you can extract its files using the following command:

tar xfz sftpplus-os-arch-version.tar.gz

To install SFTPPlus, move (or copy/link) the unpacked directory to your preferred installation path, for example: /opt/sftpplus.

SFTPPlus may be installed in any location on the local file system. In this documentation page we will assume that SFTPPlus is unpacked in the /opt/sftpplus directory (we will discuss INSTALL_ROOT more later).

2.3.3. Initializing the configuration

When installing SFTPPlus on a machine for the first time, you need to generate the initial configuration file and machine-specific SSH keys. A self-signed SSL certificate will also be generated to help with the initial FTPS and HTTPS testing.

To initialize a fresh SFTPPlus installation, execute the following command (where $ADMIN should be replaced with your favourite administrative username and $PASS with the associated password):

cd /opt/sftpplus
./bin/admin-commands.sh initialize --init-admin $ADMIN --init-password $PASS

Default configuration allows external connections to the management web page. Therefore, use a secure password to protect the management web page.

Note

If you don’t want to allow external connections to the Local Manager web-based console, append the –local-admin-access command line argument to the initialization command above:

./bin/admin-commands.sh initialize \
    --local-admin-access \
    --init-admin $ADMIN \
    --init-password $PASS

Note

The initialization step is not required when upgrading SFTPPlus. It will not overwrite the configuration file, SSH keys, and SSL certificate, if existing. In the case that you want to generate a new configuration, manually remove the existing files first.

2.3.4. Working with the SFTPPlus process account and group

On Linux, SFTPPlus’ process is managed by the init system bundled with the operating system: systemd, OpenRC, SysV init, etc.

The following are details for configuring the SFTPPlus account and group for all supported distributions.

2.3.4.1. Configuring the process user and group on Linux

On Linux systems, SFTPPlus is able to drop privileges to a regular account even when launched as root. The default configuration takes this a step further, always running under a regular account, thus requiring a dedicated sftpplus operating system account to be created. Creating a dedicated new group and a new user for running SFTPPlus’ process is therefore strongly recommended.

In the following examples we will use the default configuration value of sftpplus for the name of the user to run SFTPPlus.

To create an sftpplus group and user on Linux:

groupadd sftpplus
useradd -g sftpplus -c "SFTPPlus" -s /bin/false -d /dev/null sftpplus

Note

The generic Linux commands should work in Alpine Linux too, as long as you have the shadow package installed.

Alternatively, to create an sftpplus group and user on Alpine Linux with the default-installed tools, use:

addgroup sftpplus
adduser -G sftpplus -s /bin/false -h /dev/null -H -D sftpplus

To run SFTPPlus on Alpine Linux under an unprivileged account at all times through the included OpenRC service file, avoid creating the user with /bin/false as shell and /dev/null as home, e.g.:

adduser -G sftpplus -h /opt/sftpplus -H -D sftpplus

2.3.4.2. Finalizing the .ini configuration file for OS account configuration

This is only needed if you require to authenticate OS accounts. In most cases, you will only authenticate SFTP / FTP dedicated application accounts and you can skip this step.

To configure SFTPPlus to start as root, but to run under the dedicated application account, you have to edit the default-included unit, init, or service file to use root instead of sftpplus for launching SFTPPlus. Then make sure the following option is present in the configuration/server.ini configuration file:

[server]
account = sftpplus

You need to adjust the ownership of the files, otherwise some of the functionality (logging and saving configuration changes) will not work:

cd /opt/sftpplus && chown -R sftpplus configuration/ log/ run/

Note

At the very least, SFTPPlus needs read access to all the files under /opt/sftpplus, but in a typical installation it also requires write permission to the log/ subdirectory (for logging) and the configuration/ subdirectory (for saving changes to the running configuration). If running at all times under an unprivileged account, write permissions to the run/ sub-directory holding the PID file are needed as well.

2.3.5. Init system configuration for Linux

The next step is to configure your operating system to automatically start SFTPPlus on boot.

On systemd-based distributions, you can use the example unit file provided with SFTPPlus. Customize the WorkingDirectory, ExecStart, and PIDFile paths in accordance to your SFTPPlus installation. It is also recommended to run SFTPPlus under a non-root account at all times through systemd by changing User and Group in the systemd unit file. Edit this file with your favourite editor, e.g. vi:

vi bin/sftpplus-mft.service

When done, copy it to your systemd’s system sub-directory:

cp bin/sftpplus-mft.service /etc/systemd/system/

Note

For systems still using SysV init, a sample init script is provided.

Make sure the script is executable, then amend the INSTALL_ROOT variable found inside the script to the installation path of your SFTPPlus instance.

Copy the modified script to the standard location used by the initialization system of your distribution:

vi bin/sftpplus-mft.sysv.sh
chmod +x bin/sftpplus-mft.sysv.sh
cp bin/sftpplus-mft.sysv.sh /etc/init.d/sftpplus-mft

Note

On Alpine Linux, you may use the included OpenRC service file, customizing the INSTALL_ROOT variable if necessary for your installation:

vi bin/sftpplus-mft.openrc.sh
chmod +x bin/sftpplus-mft.openrc.sh
cp bin/sftpplus-mft.openrc.sh /etc/init.d/sftpplus-mft

2.3.6. Starting and stopping SFTPPlus on Linux

On Linux systems, in order to start / stop / restart SFTPPlus, or to check its status, you should use the relevant service management tool provided by your distribution. Assuming you have installed the relevant unit / init / service file in the appropriate place, as described in the previous section, you should be able to use:

service sftpplus-mft COMMAND

The following COMMANDs are available:

  • start
  • stop
  • restart
  • status
  • force-reload (alias for restart, only for the SysV init script)
  • force-stop (only for the SysV init script)
  • zap (only for the OpenRC service file)
  • describe (only for the OpenRC service file)

On Linux systems with systemd, you may use:

systemctl COMMAND sftpplus-mft

On Alpine Linux, you may use:

rc-service sftpplus-mft COMMAND

On SysV-based distributions, you can call the script directly as:

/etc/init.d/sftpplus-mft COMMAND

2.3.7. Running SFTPPlus on boot

Typically, this requires running a specific tool to automatically enable launching SFTPPlus on startup. Following examples (run under the root account) show how to do that on supported Linux distributions.

Linux systems with systemd (including RHEL, Ubuntu Server, Amazon Linux 2):

systemctl enable sftpplus-mft

Amazon Linux prior to version 2:

chkconfig --add sftpplus-mft

Specific command for Alpine Linux:

rc-update add sftpplus-mft

On SysV-based distributions, you can alternatively manually create symbolic links to the initialization script from the rcN.d directories (where N is the runlevel), e.g.:

ln -s /etc/init.d/sftpplus-mft /etc/rc3.d/S90sftpplus-mft
ln -s /etc/init.d/sftpplus-mft /etc/rc6.d/K90sftpplus-mft
ln -s /etc/init.d/sftpplus-mft /etc/rc0.d/K90sftpplus-mft
ln -s /etc/init.d/sftpplus-mft /etc/rc1.d/K90sftpplus-mft

2.3.8. First Steps

After starting SFTPPlus, the Local Manager is a good way to visualize the current configuration that is available, and is even configurable itself.

Note

We highly recommend going through the Getting Started guide first as it contains additional tips for new SFTPPlus installations.

There is also an FAQ section if you have an idea, but are in search of answers.

If you want to skip ahead, the Configuration Instructions or the Usage Instructions will contain detailed information to configure and operate SFTPPlus.