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.

..  contents:: :local:


.. _generate-encrypted-password:

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 <https://en.wikipedia.org/wiki/Crypt_%28C%29>`_ for more info
    on this subject.


.. _generate-ssh-key:

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


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


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


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
    <http://tools.ietf.org/html/rfc6125#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
<https://cryptoreport.websecurity.symantec.com/checker/views/csrCheck.jsp>`_.

You can check all fields of the generated certificate using a web-based
decoder, such as the one provided by
`Cert Logic <https://certlogik.com/decoder/>`_.


.. _generate-uuid:

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
<http://en.wikipedia.org/wiki/Universally_unique_identifier>`_.
