Documentation

10.10. Command line administration

SFTPPlus provides a command line utility for managing the product.

The admin-commands utility is the main tool for administering SFTPPlus from the command line.

10.10.1. Generating encrypted passwords

The admin-commands utility can generate encrypted passwords for use inside the configuration file.

Passwords can be generated in interactive or non-interactive mode.

After the command is executed, it will list the encrypted password. This can be copied inside the configuration file.

To generate a password in non-interactive mode using the default hashing function:

./bin/admin-commands.sh generate-password NEW_PASSWORD
NEW_ENCRYPTED_PASSWORD_HERE

You can specify a certain password hashing function. In this example, the password is hashed using PBKDF2-SHA512:

./bin/admin-commands.sh generate-password NEW-PASS --format=pbkdf2-sha512
NEW_ENCRYPTED_PASSWORD_HERE

When generating a password in interactive mode, the command will ask for the new password and confirmation for it:

./bin/admin-commands.sh generate-password
Enter password (not echoed)  :
Confirm password (not echoed):
NEW_ENCRYPTED_PASSWORD_HERE

Note

The entered password will not be printed / echoed to the standard output.

Note

Hashes generated by SFTPPlus follow the Modular Crypt Format. Thus, they are prefixed with a common identificator and the default parameters. For example, passwords starting with $5$rounds=80000$ denote an SHA2-based algorithm, performed 80.000 times on the same password: $5$rounds=80000$RZ48ALAHbUEdKWmi$FH7DMux4O9jVKVQfNoYo6FJVr/Rfp6gQP5fBn5QcfEB . Click here for more info on this subject.

10.10.2. Generating SSH keys

To generate an SSH key pair use the following command:

./bin/admin-commands.sh \
    generate-ssh-key \
    --key-type=rsa \
    --key-file=KEY_FILENAME \
    --key-comment=COMMENT

You can replace rsa with dsa to generate a DSA key pair.

This will generate the following files:

  • KEY_FILENAME containing the private part of the key in OpenSSH format.

  • KEY_FILENAME.pub containing the public part of the key in OpenSSH format.

Keys can be exchanged between SFTPPlus and an OpenSSH Server without requiring any additional conversion steps.

Use the included help command to see all the options available for creating a new SSH key:

./bin/admin-commands.sh generate-ssh-key --help

10.10.3. Generating PGP keys

To generate a PGP key pair, use the following command:

./bin/admin-commands.sh \
    generate-pgp-key \
    --key-type=rsa \
    --key-file=KEY_FILENAME \
    --key-comment='Test PGP key' \
    --email=your.name@example.com \
    --name='Your Name'

You can replace rsa with dsa to generate a DSA key pair.

This will generate the following files:

  • KEY_FILENAME, containing the private part of the new PGP key pair.

  • KEY_FILENAME.pub, containing the public part of the new PGP key pair.

Use the included help command to see all options available for creating a new PGP key:

./bin/admin-commands.sh generate-pgp-key --help

10.10.4. Generating Self-Signed Certificates

To generate a new self-signed certificate for DNS name localhost from the command line, use the following command:

$ ./bin/admin-commands.sh generate-self-signed \
    --common-name=localhost \
    --alternative-name=DNS:localhost,IP:127.0.0.1 \
    --key-size=3072 \
    --sign-algorithm=sha256

The certificate and the private key are then generated on the standard output. You can copy the output to a file or inside the SFTPPlus configuration file.

The generated certificate is valid for 10 years.

There are multiple options available to generate self-signed certificates, including specifying the X.509 basic constraints or the X.509 key usage:

$ ./bin/admin-commands.sh generate-self-signed --help

10.10.5. Generating SSL keys and Certificate Signing Requests

Before you can order an SSL Certificate from any provider, you must first generate a CSR (Certificate Signing Request) for your server.

To generate a new SSL key and an associated certificate signing request:

./bin/admin-commands.sh \
    generate-csr \
    --common-name=fs.domain.tld \
    --key-size=3072 \
    --key-file=KEY_FILENAME.key \
    --alternative-name="IP:192.168.7.1,DNS:www.fs.domain.tld" \
    --email="admin@domain.tld" \
    --constraints="CA:FALSE" \
    --key-usage="critical:server-authentication" \
    --organization=ACME \
    --organization-unit="ACME IT Services" \
    --locality=London \
    --state=England \
    --country=GB

Note

On Windows, you should quote values with spaces using double quotes. Single quotes are not supported.

On Windows, the reported error messages are not displayed in Unicode, but instead as ASCII, using Unicode transliteration.

To enter Unicode characters from the Windows command prompt, you will need a font which supports Unicode (Lucida Console).

The private key is generated in RSA format. The certificate request is signed using SHA256 hash function.

This will generate the following files:

  • KEY_FILENAME.key containing the SSL private key in PEM PKCS#8 format.

  • KEY_FILENAME.csr containing the associated certificate signing request for the server at fs.domain.tld in PEM x509 format.

Please consult your SSL certificate provider for details about what values to use for common name, organization, and locality.

--common-name is mandatory and should be the same value as the address used by the client to access this server. Usually, it is the Fully Qualified Domain Name (FQDN) of your server.

--organization and --organization-unit are optional. Most of the time you will need to only pass the --organization option.

In the case that you don't use alternative names to access the server, you don't need to pass the --alternative-name option. The IP address used in the alternative name option can be in either IPv4 or IPv6 format.

Note

Unicode domain names in --common-name, --email and --alternative-name options are assumed to be using Internationalized Domain Name (IDN) and they are encoded using the Internationalizing Domain Names in Applications (IDNA) encoding, as described in RFC 6125 section 6.4.2.

Note

Unicode values in --organization, --organization-unit, --locality and --state options are encoded using UTF-8.

Note

The --country option does not support Unicode values.

You can validate your certificate using the web-based Symantec SSL Tools.

You can check all fields of the generated certificate using a web-based decoder, such as the one provided by Cert Logic.

10.10.6. Generating UUID

To generate a version 4 UUID, use the following command:

./bin/admin-commands.sh generate-uuid (on Unix-like systems)
CMD> admin-commands.bat generate-uuid (on Windows)

After the command is executed, it will list the generated UUID in version 4 format on standard output. This can be copied inside the configuration file.

For more details about UUID, please check Wikipedia's article on UUID.