SFTPPlus Documentation

Start Page › 2. Installation and Upgrade Instructions › 2.3. Unix, Linux and OS X Installation

2.3. Unix, Linux and OS X Installation¶

Overview
Unpacking the archive
Initializing the configuration
Working with the SFTPPlus process account and group
Running SFTPPlus daemon/service under an unprivileged account
- 1. Start as root and mostly operate as unprivileged account
- 2. Start as unprivileged account and always operate under it
Starting and stopping the server
Init system configuration for Unix and Linux
Starting and stopping SFTPPlus on Unix and Linux
Init system configuration for Apple Mac OS X
SFTPPlus directory hierarchy and permissions
First Steps

2.3.1. Overview ¶

For Unix, Linux, and OS X systems, SFTPPlus is distributed as a gzipped TAR archive. Installing SFTPPlus on these operating systems consists of unpacking the archive, initializing the configuration and generating the SSH keys and the SSL certificate which will 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 run SFTPPlus as root, especially if you want it to authenticate operating system users.

In order to have SFTPPlus started at boot time, you may use one of the included init, unit, service or plist files. For Unix and Linux, the service initialization script has been tested on all supported operating systems, but it should work on other systems as well.

2.3.2. Unpacking the archive ¶

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

gunzip -dc sftpplus-os-arch-version.tar.gz | tar -xf -

Note

The tar archive has been created using pax, and should be extractable by the GNU tar command or its alternatives.

To install SFTPPlus, move (or copy/link) the unpacked directory to your preferred installation path, for example: /opt/sftpplus or, if you are using OS X, /Library/sftpplus.

Note

SFTPPlus may be installed in any location on the local file system. For this documentation, we will assume that on Unix and Linux systems, SFTPPlus is unpacked in the /opt/sftpplus directory (we will discuss the INSTALL_ROOT more later).

Note

For OS X we will assume that SFTPPlus is unpacked in the /Library/sftpplus directory. In the following examples please replace /opt/sftpplus/ with /Library/sftpplus.

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 a machine-specific SSH key. A self-signed SSL certificate will also be generated to help with the initial FTPS testing.

To initialize SFTPPlus, execute the following commands:

cd /opt/sftpplus
./bin/admin-commands.sh initialize

Warning

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.

2.3.4. Working with the SFTPPlus process account and group ¶

On Unix and Linux systems, SFTPPlus’ process runs as a single, self managed daemon. It does not depend on inetd (the Internet daemon).

On OS X systems, SFTPPlus’ process is managed by launchd.

On Linux/Unix the SFTPPlus is designed to run as a foreground process executed under the root account and will drop privileges after it is launched.

The following are details for configuring the SFTPPlus account and group for Unix / Linux / OSX.

2.3.4.1. Configuring the process user and group on Unix/Linux ¶

On Unix and Linux systems, SFTPPlus is able to drop privileges to a regular account. The default configuration takes advantage of this feature, 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 recommended.

In the following example 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 in Linux and Solaris (with the exception of Alpine Linux):

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

To create an sftpplus group and user in Alpine Linux:

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

Note

To run SFTPPlus in Alpine Linux under an unprivileged account at all times through the included OpenRC init script, avoid creating the user with “/bin/false” as shell and “/dev/null” as home, eg.: adduser -G sftpplus -g “SFTPPlus” -h /opt/sftpplus -H -D sftpplus

Note

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

To create an sftpplus group and user in FreeBSD:

pw group add sftpplus
pw user add sftpplus -g sftpplus -c SFTPPlus -s /usr/bin/false -d /dev/null

To create an sftpplus group and user in HP-UX (where useradd doesn’t allow creating accounts with a /dev/null home):

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

To create an sftpplus group and user in AIX:

mkgroup sftpplus
mkuser sftpplus
usermod -g sftpplus -d /dev/null -s /bin/false -c "SFTPPlus" sftpplus

Note

On AIX you’ll need to add /bin/false to the list of valid login shells in /etc/security/login.cfg before changing the shell of the sftpplus user with usermod.

2.3.4.2. Configuring the process user and group on OS X ¶

To create an sftpplus group and a corresponding user on OS X, replace the value of 240 from the following example with a unique ID for your system:

# Create the group dedicated to the service account.
dscl . create /Groups/sftpplus
# Assign an unique ID to the group.
dscl . create /Groups/sftpplus PrimaryGroupID 240
# Disable group password.
dscl . create /Groups/sftpplus Password '*'
# Create a user for the service account.
dscl . create /Users/sftpplus
# Assign a unique ID to the new user.
dscl . create /Users/sftpplus UniqueID 240
# Assign this account to the dedicated group.
dscl . create /Users/sftpplus PrimaryGroupID 240
# Disable shell access.
dscl . create /Users/sftpplus UserShell /usr/bin/false
# Make sure it has a default empty home folder.
dscl . create /Users/sftpplus NFSHomeDirectory /var/empty
# Disable password to block any authentication request.
dscl . create /Users/sftpplus Password '*'
# Initialize blank password and authentication rules.
dscl . delete /Users/sftpplus PasswordPolicyOption
dscl . delete /Users/sftpplus AuthenticationAuthority

Note

On OS X, you can use dscacheutil -q user or dscacheutil -q group to identify the used IDs and pick a unique ID for the system.

Note

The above commands are included into an easy to use script which is available as osx_useradd.sh

2.3.4.3. Finalizing the .ini configuration file with the new process account ¶

To configure SFTPPlus to run under the newly created account, make sure the following option is present in the server.ini configuration file:

[server]
account = sftpplus

Note

Don’t forget to adjust the ownership of the files, otherwise some of the functionality (logging and saving configuration changes) may not work. At the very least, SFTPPlus needs read access to all the files under /opt/sftpplus, but in a typical installation it would also require 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.

A quick and easy way to achieve the above would be: cd /opt/sftpplus && chown -R sftpplus configuration/ log/ run/

2.3.5. Running SFTPPlus daemon/service under an unprivileged account ¶

Like any other Linux/Unix process, the main process of SFTPPlus runs under an operating-system account.

SFTPPlus can start under the root OS account, and then drop privileges in order to mainly operate under a regular OS account.

As in most deployments such a regular account is dedicated to running SFTPPlus, our documentation refers to this regular OS account as the service account.

We recommend to always run SFTPPlus under such an unprivileged OS account, even when the SFTPPlus process is launched as root.

In this regard, the SFTPPlus process has 2 main modes of operation, each one with its own advantages and disadvantages.

2.3.5.1. 1. Start as root and mostly operate as unprivileged account ¶

This is the default mode, in which the init script or unit file is configured to start SFTPPlus as root, while the configuration file defines an unprivileged OS account (by default, sftpplus) for the process’ operation.

If you want the SFTPPlus process launched as root, but operating under the sftpplus account, make sure the configuration file reads as follows:

[server]
account = sftpplus

Advantages:

Binding to ports below 1024 works out of the box.
The OS accounts can be used for file transfer services.

Disadvantages:

Even though most of the time SFTPPlus will operate under the unprivileged account, for requests to authenticate an OS account SFTPPlus will briefly switch to running as root in order to perform the OS authentication. If there is a security bug in SFTPPlus, and that bug is exploited during the brief amount of time SFTPPlus runs as root, an attacker can theoretically gain privileged access to OS resources.

2.3.5.2. 2. Start as unprivileged account and always operate under it ¶

If you want the SFTPPlus process launched and always operating as an unprivileged user, you have to edit the init script or unit file to start SFTPPlus under that user, and then make sure the configuration file reads as follows:

[server]
account = Disabled

SFTPPlus will then operate under the same OS account that is used to launch it.

Advantages:

Operating under the principle of least privilege.
Even if there are security bugs in SFTPPlus, a successfull exploit will not have unprivileged access to OS resources.

Disadvantages:

Binding to ports below 1024 requires extra configuration steps. If at all possible, as on some Unix systems you can only bind those ports as root. You can still configure the file transfer services to listen on any ports above 1024.
The OS accounts cannot be used for file transfer services.

Note

You can also start SFTPPlus under the privileged root account in the init script or unit file, and keep running the SFTPPlus process as root using account = Disabled in the server’s configuration file. For security reasons, we don’t recommend this mode of operation.

2.3.6. Starting and stopping the server ¶

For your convenience, the SFTPPlus installation comes with a script which can be integrated into the boot or startup process of your operating system, as discussed in the next section.

All the scripts for every operating system, are using the base command for starting and stopping the SFTPPlus product, as described in this chapter.

To start the server, use the following command:

./bin/admin-commands.sh start

By default it will start using the configuration file located at configuration/server.ini and will store the process ID inside the run/server.pid file.

To stop the server, send the kill signal to the process ID stored inside the run/server.pid file.

To store the process ID in a different file, start the server using -p or –pid arguments:

./bin/admin-commands.sh start --pid=/path/to/PID_FILE

If you want to launch the server using a configuration file from a specific location, use the -c or –config= argument:

./bin/admin-commands.sh start --config=/path/to/CONFIGURATION_FILE

2.3.7. Init system configuration for Unix and Linux ¶

For Unix and Linux systems, the following script is provided as a starting point for creating custom initialization scripts for various service managers (SysVinit, Upstart, OpenRC, systemd with SysV compatibility, SMF, etc.):

./bin/sftpplus-mft.sysv.sh

You should copy the sample script to the standard location used by the initialization system of your operating system:

Linux and Solaris:

/etc/init.d/sftpplus-mft

AIX:

/etc/rc.d/init.d/sftpplus-mft

HP-UX:

/sbin/init.d/sftpplus-mft

Make sure the script is executable, and amend the INSTALL_ROOT variable found inside the script to the installation path of your SFTPPlus instance. In the case that SFTPPlus is installed at /opt/sftpplus, the script’s relevant section should look as follows:

Replace INSTALL_ROOT with your installation path.
INSTALL_ROOT="/opt/sftpplus"

Note

You can run SFTPPlus under a non-root account through a SysV-compatible init by changing DAEMON_USER in the init script.

On systemd-based distributions (especially on those without the SysV compatibility bits, such as Arch Linux) you can use the following unit file:

./bin/sftpplus-mft.service

Note

You should copy it to /etc/systemd/system/, customizing the WorkingDirectory, ExecStart and PIDFile paths based on your SFTPPlus installation. You can run SFTPPlus under a non-root account through systemd by changing User and Group in the systemd unit file.

On Alpine Linux, you may use the included OpenRC service file:

./bin/sftpplus-mft.openrc.sh

Note

You should copy it to /etc/init.d/sftpplus-mft, customizing the INSTALL_ROOT variable, if necessary for your SFTPPlus installation. You can run SFTPPlus under a non-root account through OpenRC by changing DAEMON_USER in the OpenRC service file.

On FreeBSD, you can use the following rc script:

./bin/sftpplus_mft.rc.sh

Note

You should copy it to /usr/local/etc/rc.d/sftplus_mft, customizing the sftpplus_mft_chdir variable, if necessary for your SFTPPlus installation. You can run SFTPPlus under a non-root account in FreeBSD by changing DAEMON_USER in the SysV init script referenced in command.

Depending on your operating system, you will have to either manually create symbolic links to the initialization script from the rcN.d directories (where N is the runlevel) or run a specific tool that will automatically do that.

Examples (as root):

RHEL, Amazon Linux, and SUSE:

chkconfig --add sftpplus-mft

Ubuntu, Debian:

update-rc.d sftpplus-mft defaults

Linux systems with systemd (including RHEL 7, Ubuntu 16.04 and 18.04, Debian 9, Amazon Linux 2, and SLES 12):

systemctl enable sftpplus-mft

Alpine Linux:

rc-update add sftpplus-mft

Solaris:

ln -s /etc/init.d/sftpplus-mft /etc/rc3.d/S99sftpplus-mft

AIX:

ln -s /etc/rc.d/init.d/sftpplus-mft /etc/rc.d/rc2.d/S99sftpplus-mft

HP-UX:

ln -s /sbin/init.d/sftpplus-mft /sbin/rc3.d/S999sftpplus-mft

FreeBSD:

echo 'sftpplus_mft_enable="YES"' >> /etc/rc.conf

Note

On Solaris the above command will configure the service using the legacy init scripting start-up mechanism common to prior releases of Solaris and other UNIX operating systems. Please contact us in the case that you need integration with the Service Management Facility (SMF).

2.3.8. Starting and stopping SFTPPlus on Unix and Linux ¶

On Linux systems, in order to start / stop / restart SFTPPlus, or to check its status, you can either call the script directly as:

/etc/init.d/sftpplus-mft COMMAND

or through the relevant service management tool provided by the operating system:

service sftpplus-mft COMMAND

For Linux systems with systemd you may use:

systemctl COMMAND sftpplus-mft

For Alpine Linux you may use:

rc-service sftpplus-mft COMMAND

The following COMMANDs are available:

start

stop

restart

status

force-reload (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)

Note

The force-reload action is an alias for restart, in order to comply with the Linux Standard Base.

On FreeBSD, you can directly call the SysV init script from the installation directory with the above options. Or you can call the supplied rc script, either directly or through the service command. The following options are available: start, stop, restart, and status.

Note

Please note that the poll action is not yet supported, and fast, force, quiet actions are identical to the default actions.

On other Unix systems (AIX, Solaris, HP-UX) the same commands are supported as for the Linux systems, but only the option to call the script directly is available.

For Solaris:

/etc/init.d/sftpplus-mft COMMAND

For AIX:

/etc/rc.d/init.d/sftpplus-mft COMMAND

For HP-UX:

/sbin/init.d/sftpplus-mft COMMAND

Note

When running the legacy SFTPPlus WebAdmin on the same machine, SFTPPlus should be started after Apache, as it will check the availability of the configured legacy SFTPPlus WebAdmin.

2.3.9. Init system configuration for Apple Mac OS X ¶

For Mac OS X systems newer than 10.8, the following launchd job definition is provided together with the SFTPPlus distribution. The job definition file is formatted as XML, and it is called a property list file or plist:

bin/Library_LaunchDaemons_sftpplus.plist

The sample job definition file assumes that SFTPPlus is installed in the /Library/sftpplus directory. Depending on where the job definition is stored, it will be treated as a daemon or an agent. In order to have SFTPPlus act as a global daemon, launching it each time the OS X system starts, you need to copy the plist file into the following location: /Library/LaunchDaemons/sftpplus.plist

After the file is copied, you need to instruct launchd to load/read the new job definition file using the command:

launchctl load /Library/LaunchDaemons/sftpplus.plist

Note

At boot time, the launchd process will scan and automatically load job definitions found in the /Library/LaunchDaemons directory.

To stop SFTPPlus, use the following command:

launchctl unload /Library/LaunchDaemons/sftpplus.plist

Note

In the case that there are problems starting the server, you can check the log files at /var/log/system.log and /var/log/sftpplus-launchd.log.

You can also launch SFTPPlus in debug mode using:

./bin/admin-commands.sh debug

Note

You can read more about launchd on the official documentation page

2.3.10. SFTPPlus directory hierarchy and permissions ¶

Once unpacked, the SFTPPlus installation should have the following hierarchical directory structure on disk.

This list also describes the permissions required for the service account.

bin/ - read-only Contains SFTPPlus administration commands and the init script. Only available on Unix and Linux systems.
configuration/ - read-only Stores all data related to SFTPPlus configuration.
configuration/server.ini - read-and-write Stores the main configuration.
doc/ - read-only Contains documentation and release notes for SFTPPlus.
extension/ - read-only Contains custom extensions implemented using the SFTPPlus API.
include/ - read-only This directory is for developers interested in extending the functionality of SFTPPlus. May be missing in some releases.
lib/ - read-only This directory is for internal use.
log/ - read, write, create file and delete file Stores all SFTPPlus log messages. SFTPPlus will write log entries into the log files. When log rotation is enabled, it will also create new rotated files and delete old rotated files.
run/ - read, write, create file and delete file Stores various SFTPPlus runtime information.

2.3.11. 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.

‹ 2.2. Windows Installation

2.4. Installation Validation and Troubleshooting ›