improve documentation

certbot_haproxy/authenticator.py

@@ -1,46 +1,47 @@
-"""
-    HAProxy Authenticator.
+"""HAProxy Authenticator.
 
-    This authenticator creates its own ephemeral TCP listener on the necessary
-    port in order to respond to incoming `http-01` challenges from the
-    certificate authority. You need to forward port requests for
-    `/.well-known/acme-challenge/` on port 80 to the `http-01` port
-    (default:8000). You may do this like this for example:
+The HAProxy Authenticator is an extension of the "standalone" authenticator
+that is part of certbot. It limits its functionality to only support the
+`http-01` challenge because `tls-sni-01` checks the challenge by connecting to
+port 443.  We can't proxy requests to certbot because we can't see the
+requested uri until the request is decrypted, and we can't do decryption in
+HAProxy because `tls-sni-01` expects to do a TLS handshake.
 
-    ```
-        default_backend nodes
+This authenticator creates its own ephemeral TCP listener on the necessary port
+in order to respond to incoming `http-01` challenges from the certificate
+authority. You need to forward port requests for `/.well-known/acme-challenge/`
+on port 80 to the configured value for `internal_port` (default:8000). This can
+be achieved by adding this example to your haproxy configuration file::
 
-        acl is_cerbot path_beg -i /.well-known/acme-challenge
-        use_backend certbot if is_cerbot
+    default_backend nodes
 
-        backend certbot
-            log global
-            mode http
-            server certbot 127.0.0.1:8000
+    acl is_cerbot path_beg -i /.well-known/acme-challenge
+    use_backend certbot if is_cerbot
 
-        backend nodes
-            log global
-            mode http
-            option tcplog
-            balance roundrobin
-            option forwardfor
-            option http-server-close
-            option httpclose
-            http-request set-header X-Forwarded-Port %[dst_port]
-            http-request add-header X-Forwarded-Proto https if { ssl_fc }
-            option httpchk HEAD / HTTP/1.1\r\nHost:localhost
-            server node1 127.0.0.1:8080 check
-            server node2 127.0.0.1:8080 check
-            server node3 127.0.0.1:8080 check
-            server node4 127.0.0.1:8080 check
-    ```
+    backend certbot
+        log global
+        mode http
+        server certbot 127.0.0.1:8000
 
-    The Authenticator is simply an extension of the "standalone" plugin that is
-    part of certbot. It limits its functionality to only support the `http-01`
-    challenge because checks the challenge by connecting to port 443. We can't
-    proxy requests to certbot because we can't see the requested uri until the
-    request is decrypted, and we can't do decryption in HAProxy because
-    `tls-sni-01` expects to do a TLS handshake.
+    backend nodes
+        log global
+        mode http
+        option tcplog
+        balance roundrobin
+        option forwardfor
+        option http-server-close
+        option httpclose
+        http-request set-header X-Forwarded-Port %[dst_port]
+        http-request add-header X-Forwarded-Proto https if { ssl_fc }
+        option httpchk HEAD / HTTP/1.1\\r\\nHost:localhost
+        server node1 127.0.0.1:8080 check
+        server node2 127.0.0.1:8080 check
+        server node3 127.0.0.1:8080 check
+        server node4 127.0.0.1:8080 check
+
+For instructions on how to make HAProxy serve certificates that were created
+with this authenticator, read the documentation of the
+`.certbot_haproxy.installer`
 """
 import logging
 
@@ -73,9 +74,11 @@ class HAProxyAuthenticator(standalone.Authenticator):
             The arguments can be retrieved by asking for corresponding names
             in `self.conf([argument name])`
 
-            NOTE: This is an override a method defined in the parent, we are
-            deliberately not calling super() because it would add arguments
-            that we don't support.
+            .. note:: This overrides a method defined in the parent, we
+                are deliberately not calling super() because it would add
+                arguments that are not supported.
+
+            :param func add: The function to be called to add an argument.
         """
         add(
             "internal-port",

certbot_haproxy/constants.py

@@ -1,9 +1,22 @@
-"""HAProxy plugin constants."""
+"""HAProxy plugin constants.
+
+Operation system specific variables are saved in this module. Currently
+includes:
+
+    - server_root: the folder containing HAProxy files
+    - restart_cmd: the command to restart haproxy (command is a list)
+    - conftest_cmd: the command to test the haproxy configuration
+    - haproxy_config: the path to the haproxy configuration file
+    - crt_directory: the directory to which the crt frontend option points.
+
+Defaults to the values for DEBIAN_JESSIE if no suitable operating system is
+found.
+"""
 from certbot import util
 
 CLI_DEFAULTS_DEBIAN_JESSIE = dict(
     server_root="/etc/haproxy",
-    version_cmd=['haproxy', '-v'],
+    # version_cmd=['haproxy', '-v'],
     restart_cmd=['sudo', 'systemctl', 'restart', 'haproxy'],
     # Needs the config file as an argument:
     conftest_cmd=['/usr/sbin/haproxy', '-c', '-f'],
@@ -13,7 +26,7 @@ CLI_DEFAULTS_DEBIAN_JESSIE = dict(
 
 CLI_DEFAULTS_DEBIAN_WHEEZY = dict(
     server_root="/etc/haproxy",
-    version_cmd=['haproxy', '-v'],
+    # version_cmd=['haproxy', '-v'],
     restart_cmd=['service', 'haproxy', 'restart'],
     # Needs the config file as an argument:
     conftest_cmd=['/usr/sbin/haproxy', '-c', '-f'],

certbot_haproxy/installer.py

@@ -2,7 +2,28 @@
     HAProxy Installer.
 
     This installer combines the certificate files into one file and places them
-    in the specified directory so HAProxy can use them.
+    in the specified directory so HAProxy can use them. The directory can be
+    specified in `.certbot_haproxy.constants` and has to be configured with
+    HAProxy using the crt option for the bind directive::
+
+        frontend http-in
+            bind *:80
+            mode http
+            bind *:443 ssl crt /etc/ssl/crt/
+
+    .. note:: You need to install one (default) certificate into this
+        directory, otherwise HAProxy will not be able to start.
+
+    .. note:: You need at least version 1.5 of HAProxy with OpenSSL built in.
+
+    HAProxy is restarted by the installer with the restart_cmd from the
+    `.certbot_haproxy.constants`. If you do not want to run lehaproxy as root
+    (this is recommended), add this line to your sudoers file::
+
+        $USER ALL=NOPASSWD: /bin/systemctl restart haproxy
+
+    Be sure to replace `$USER` with the user that will be running the lehaproxy
+    installer.
 """
 import logging
 import os
@@ -27,7 +48,7 @@ logger = logging.getLogger(__name__)  # pylint:disable=invalid-name
 class HAProxyInstaller(common.Plugin):
     """HAProxy Installer."""
 
-    description = "Certbot installer for HAProxy."
+    description = "Certbot certificate installer for HAProxy."
 
     def __init__(self, *args, **kwargs):
         super(HAProxyInstaller, self).__init__(*args, **kwargs)
@@ -140,8 +161,26 @@ class HAProxyInstaller(common.Plugin):
 
         .. note:: This doesn't save the files!
 
+        HAProxy needs the certificates and private key to be in one file. The
+        private key in key_path is combined with the fullchain path if one is
+        provided.  If no fullchain path is provided, the cert_path and the
+        chain_path are used to create a similar document.
+
+        These files are added to an internal dictionary. If the domain in
+        ``domain`` already has a file in the ``crt_directory`` from
+        `.certbot_haproxy.constants` it is added to self.crt_files, otherwise it
+        is added to self.new_crt_files. These files are saved by the `.save`
+        function.
+
+        :param str domain: domain to deploy certificate file
+        :param str cert_path: absolute path to the certificate file
+        :param str key_path: absolute path to the private key file
+        :param str chain_path: absolute path to the certificate chain file
+        :param str fullchain_path: absolute path to the certificate fullchain
+            file (cert plus chain)
+
         :raises errors.PluginError: When unable to deploy certificate due to
-            a lack of directives or configuration
+            a lack of information
         """
         crt_filename = constants.os_constant("crt_directory") + domain + \
             self.crt_postfix
@@ -212,6 +251,8 @@ class HAProxyInstaller(common.Plugin):
     def save(self, title=None, temporary=False):
         """Saves all changes to the configuration files.
 
+        This saves new files and file changes to the certificate directory.
+
         :param str title: The title of the save. If a title is given, the
             configuration will be saved as a new checkpoint and put in a
             timestamped directory.
@@ -295,7 +336,7 @@ class HAProxyInstaller(common.Plugin):
         logger.warn("get_all_certs_keys called, not doing anything :(")
 
     def restart(self):
-        """Runs a config test and reloads the Apache server.
+        """Runs a config test and restarts HAProxy.
 
         :raises .errors.MisconfigurationError: If either the config test
             or reload fails.
@@ -308,7 +349,7 @@ class HAProxyInstaller(common.Plugin):
             raise errors.MisconfigurationError(str(err))
 
     def config_test(self):  # pylint: disable=no-self-use
-        """Check the configuration of HaProxy for errors.
+        """Check the configuration of HAProxy for errors.
 
         :raises .errors.MisconfigurationError: If config_test fails
 

docs/api/authenticator.rst

@@ -0,0 +1,5 @@
+:mod:`certbot_haproxy.authenticator`
+--------------------------------------
+
+.. automodule:: certbot_haproxy.authenticator
+   :members:

docs/api/configurator.rst

@@ -1,5 +0,0 @@
-:mod:`certbot_haproxy.configurator`
---------------------------------------
-
-.. automodule:: certbot_haproxy.configurator
-   :members:

docs/api/constants.rst

@@ -0,0 +1,6 @@
+:mod:`certbot_haproxy.constants`
+--------------------------------
+
+.. automodule:: certbot_haproxy.constants
+   :members:
+

docs/api/installer.rst

@@ -0,0 +1,5 @@
+:mod:`certbot_haproxy.installer`
+--------------------------------------
+
+.. automodule:: certbot_haproxy.installer
+   :members: