=====
Usage
=====

**NOTE**: As of FreeNAS 11.1, the API calls needed to install and activate new
certificates for the FreeNAS GUI are usable only by users with *root* permissions.
Since the configuration files for Certbot are not protected, the username and
password you supply to this script will be visible to anyone who can inspect
the configuration files.

There are two methods of using this tool: automatically (as a deploy-hook in
Certbot, which is the intended usage), and manually (by specifying all
necessary command-line arguments).

First, let's review the complete help text for the tool::

    Usage: certbot_freenas_deployer [OPTIONS]

    A tool for deploying TLS certificates obtained by certbot to FreeNAS 11.1
    (or later) systems.

  Options:
    --url TEXT                      URL of FreeNAS system
    --tls-verify / --no-tls-verify  Enable or disable verification of existing
                                    TLS certificate during deployment (default:
                                    enabled)
    --user TEXT                     Name of user with root privileges on FreeNAS
                                    system
    --password TEXT                 Password for specified user
    --certfile TEXT                 Path to certificate file (usually
                                    fullchain.pem)
    --keyfile TEXT                  Path to private key file (usually
                                    privkey.pem)
    --debug / --no-debug            Enable or disable debugging output of API
                                    requests to FreeNAS system (default:
                                    disabled)
    --quiet / --no-quiet            Enable or disable output of progress
                                    messages (default: disabled)
    --help                          Show this message and exit.

In automatic mode, you will typically only supply the \--url, \--user, and \--password
arguments. In manual mode you will also need to supply the \--certfile and \--keyfile
arguments. All of the other arguments are optional, and only necessary in
specific scenarios.

The \--tls-verify option can be used to disable verification of the existing TLS
certificate on the FreeNAS system. This may be necessary if the FreeNAS system
is using a self-signed certificate, or a CA-signed certificate that has expired
or does not match the system's domain name. In both of those cases, if you
have not disabled HTTP access to the FreeNAS GUI, you can also perform a single
deployment using an *HTTP* URL instead of an *HTTPS* URL, in order to get a valid
and trusted certificate in place. This will communicate your username and password
in plaintext, though, so do not choose this option unless you fully trust the
ntework path between the system where you are running this tool and the FreeNAS
system.

For automatic deployments, you can add \--quiet option to disable the normal
progress messages generated by the tool. This may be valuable if you are using
a *cron* job or something similar to run Certbot regularly, and don't want to
see the progress messages from normal (successful) deployments.

For manual deployments, if you experience problems during the deployment process,
you can use the \--debug option to display the HTTP requests and responses
sent and received by the tool.

================
Invoking the tool
================

There are two ways to invoke the tool: the installation process (on most operating
systems) will install a *console script* which can be run directly, and in addition
the tool can be run using the Python *runpy* module mechanism.

.. highlight:: shell

to invoke the console script:

.. code-block:: console

    $ certbot_freenas_deployer --url ... --user ... --password ...

To invoke the tool using *runpy*:

.. code-block:: console

    $ python3 -m certbot_freenas_deployer --url ... --user ... --password ...

==============
Automatic Mode
==============

In automatic mode there is no need to supply the paths to the certificate file
or private key file, as Certbot will supply an environment variable which the
tool will use to locate these files.

Using an RFC2136 style DNS-01 challenge, a suitable certbot invocation would
look like this::

  certbot certonly -d freenas.domain.invalid --dns-rfc2136 --dns-rfc2136-credentials /etc/letsencrypt/dnsupdate.ini --deploy-hook "certbot_freenas_deployer --url https://freenas.domain.invalid --user root --password abcd1234"

This assumes you have placed appropriate RFC2136 credentials into
/etc/letsencrypt/dnsupdate.ini, and that you're using the default password
for the *root* user account in FreeNAS.

Certbot is configured in *certonly* mode so that it will not attempt to use
any of its installers to install the certificate.

===========
Manual Mode
===========

In manual mode you will need to supply the \-\-certfile and \-\-keyfile arguments,
with paths to the *full* certificate file (server certificate and all CA
certificates in the chain) and the private key file.
