2.5.3.1. Unpacking the archive¶

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

tar xfz sftpplus-macos-arm64-VERSION.tar.gz

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

sudo mv sftpplus-macos-arm64-VERSION /Library/sftpplus

SFTPPlus may be installed in any location on the local file system. In this documentation page we assume that SFTPPlus is unpacked in the /Library/sftpplus directory. Avoid using spaces or special characters in the SFTPPlus installation path.

2.5.3.2. Automated installation from unpacked archive¶

The easiest way to install SFTPPlus is to execute the shell script found at bin/install.sh in the hierarchy of SFTPPlus files. For example:

sudo /Library/sftpplus/bin/install.sh

The install.sh script will guide you through all the necessary steps.

Once the installation is complemented, the install script will automatically start the SFTPPlus process. You can check the status of the SFTPPlus process using:

launchctl list | grep SFTPPlus

After a successful installation using the shell script, jump to Listening on privileged ports to learn how to enable SFTPPlus to listen on privileged ports.

Otherwise, only go further down this page for manual installation or debugging.

2.5.3.3. Manual installation from unpacked archive¶

To install SFTPPlus manually, you have to perform step-by-step all the operations automatically done through the shell script installers, starting with 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 a password to be used for the SFTPPlus administrative user):

cd /Library/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.

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

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

After initializing the configuration, you need to configure the operating system user and group to be used by SFTPPlus. On macOS systems, SFTPPlus always runs under a regular account, thus requiring a dedicated operating system account, such as sftpplus, to be created. Creating a dedicated new group and a new user for running SFTPPlus is therefore strongly recommended.

In the following examples we use the default configuration value of sftpplus for the name of the user to run SFTPPlus. To create an sftpplus group and a corresponding user, use the commands exemplified below. You can replace the value of 299 from the following commands with a unique ID for your system. On macOS, you can use dscacheutil -q user or dscacheutil -q group to identify the used IDs and pick a unique ID. The commands below are included into an easy-to-use script available on GitHub Gist:

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

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

cd /Library && chown -R root:admin sftpplus
cd /Library/sftpplus && chown -R sftpplus configuration/ log/ run/

At the very least, SFTPPlus needs read access to all the files under /Library/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). Since SFTPPlus on macOS runs under an unprivileged OS account at all times, write permissions for the run/ sub-directory are needed for saving its PID.

The next step is to configure your operating system to automatically start SFTPPlus on boot. On macOS, SFTPPlus is designed to be started via the launchd system tool as a daemon that runs continuously. You can use the example launchd job definition provided with SFTPPlus. The job definition file is formatted as XML, and it is called a property list file or a plist file. Edit this file with your favourite editor, e.g. vi:

vi bin/sftpplus-mft.plist

Depending on where the job definition is copied onto your system, it will be treated as a service or an agent. In order to have SFTPPlus act as a global service, launching each time the macOS system starts, you need to copy it in the appropriate place:

sudo cp bin/sftpplus-mft.plist /Library/LaunchDaemons/sftpplus-mft.plist

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

sudo launchctl load /Library/LaunchDaemons/sftpplus-mft.plist

To stop SFTPPlus, use the following command:

sudo launchctl unload /Library/LaunchDaemons/sftpplus-mft.plist

In the case that there are problems starting the server, you can check the log files at SFTPPLUS-INSTALL-DIR/log/launchd-stdout.log and SFTPPLUS-INSTALL-DIR/log/launchd-stderr.log. You can read more about launchd on the official documentation page.