SFTPPlus Documentation
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.