SFTPPlus Documentation
2.4. macOS Installation¶
2.4.1. Overview¶
For macOS systems, SFTPPlus is distributed as a gzipped TAR archive. Installing SFTPPlus on macOS 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 launched at startup, you may use the included plist file.
2.4.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: /Library/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 /Library/sftpplus directory.
2.4.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.4.4. Working with the SFTPPlus process account and group¶
On macOS, SFTPPlus’ process is managed by launchd.
The following are details for configuring the SFTPPlus account and group for macOS systems.
2.4.4.1. Configuring the process user and group on macOS¶
On macOS 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.
2.4.4.2. Configuring the process user and group on macOS¶
To create an sftpplus group and a corresponding user on macOS, 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 macOS, 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.4.4.3. 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 plist file to use root instead of sftpplus for the UserName key. 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 /Library/sftpplus && chown -R sftpplus configuration/ log/ run/
Note
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). 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.4.5. Init system configuration for macOS¶
The next step is to configure your operating system to automatically start SFTPPlus on boot.
For macOS systems, 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 ‘plist’. Edit this file with your favourite editor, e.g. vi:
vi bin/sftpplus-mft.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 each time the macOS system starts, you need to copy it in the appropriate place:
cp bin/sftpplus-mft.plist /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
During startup, 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.
Note
You can read more about launchd on the official documentation page
2.4.6. 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.