Add documentation of file system layout and service configuration

defaults/main.yml

@@ -1,7 +1,7 @@
 ---
 # .. vim: foldmarker=[[[,]]]:foldmethod=marker
 
-# Default Role Variables [[[
+# Default role variables [[[
 # ==========================
 
 # .. contents:: Sections

docs/index.rst

@@ -7,6 +7,7 @@ Ansible role: ganto.acme_tiny
    introduction
    getting-started
    defaults
+   system-configuration
    copyright
 
 ..

docs/introduction.rst

@@ -8,9 +8,14 @@ automates the creation of certificate requests and renewal of certificates,
 including service restart after the certificates have been replaced.
 
 
+.. _acme_tiny_installation:
+
 Installation
 ~~~~~~~~~~~~
 
+
+.. _acme_tiny_ansible_role:
+
 Ansible Role
 ^^^^^^^^^^^^
 
@@ -20,6 +25,9 @@ This role requires at least Ansible ``v2.0.0``. To install it, run:
 
     ansible-galaxy install ganto.acme_tiny
 
+
+.. _acme_tiny_upstream:
+
 acme-tiny
 ^^^^^^^^^
 

docs/system-configuration.rst

@@ -0,0 +1,141 @@
+System configuration
+====================
+
+.. _acme_tiny_ref_fs_layout
+
+File system layout
+------------------
+
+The role will setup a configurable directory layout to store the certificates
+and make them accessible by the services.
+
+Example layout of the default configuration:
+
+======================================================= ==================================
+Server path                                             Ansible role variable
+======================================================= ==================================
+:file:`/etc/ssl/acme-tiny`                              :envvar:`acme_tiny__config_dir`
+:file:`/etc/ssl/acme-tiny/example.com`                  :envvar:`acme_tiny__cert_dir`
+:file:`/etc/ssl/acme-tiny/example.com/example.com.key`  :envvar:`acme_tiny__private_key`
+:file:`/etc/ssl/acme-tiny/example.com/example.com.crq`  :envvar:`acme_tiny__cert_request`
+:file:`/etc/ssl/acme-tiny/example.com/example.com.crt`  :envvar:`acme_tiny__certificate`
+======================================================= ==================================
+
+When setting a :envvar:`acme_tiny_cert_type` other than ``plain`` or ``chain``
+an additional layer of indirection through symlinks which will make the
+certificates accessible in a transparent way. For each service the role will
+create a :file:`ssl/` subdirectory from where the actual certificates and keys
+are symlinked. Like this the CA could be changed easily without reconfiguration
+of the secured services.
+
+E.g. For for Apache :program:`httpd` this would look like this::
+
+    /etc/apache2/ssl/example.com.crt -> /etc/ssl/acme-tiny/example.com/example.com_chain.crt
+    /etc/apache2/ssl/example.com.key -> /etc/ssl/acme-tiny/example.com/example.com.key
+
+For :program:`lighttpd`::
+
+    /etc/lighttpd/ssl/example.com.pem -> /etc/ssl/acme-tiny/example.com/example.com_lighttpd.pem
+    /etc/lighttpd/ssl/ca.crt          -> /etc/ssl/acme-tiny/intermediate.crt
+
+For :program:`Dovecot`::
+
+    /etc/dovecot/ssl/example.com.crt -> /etc/ssl/acme-tiny/example.com/example.com.crt
+    /etc/dovecot/ssl/example.com.key -> /etc/ssl/acme-tiny/example.com/example.com.key
+
+
+.. _acme_tiny_ref_service_cfg
+
+Service configuration
+---------------------
+
+To secure a service the key and certificate have to be referenced in the
+individual service configurations. When using the symlinks created by the role
+this only has to be done once. Any certificate changes and even the change of
+a certificate authority can be easily handled by pointing the symlinks to a
+new target.
+
+.. note:: The configuration of the certificates in the service configuration
+          files has to be done manually.
+
+
+.. _acme_tiny_ref_apache_cfg
+
+Apache httpd
+~~~~~~~~~~~~
+
+.. code-block:: apacheconf
+
+    SSLCertificateFile    /etc/apache2/ssl/example.com.crt
+    SSLCertificateKeyFile /etc/apache2/ssl/example.com.key
+
+- Upstream documentation:
+  `Apache Module mod_ssl <https://httpd.apache.org/docs/2.4/mod/mod_ssl.html>`_
+
+
+.. _acme_tiny_ref_dovecot_cfg
+
+Dovecot
+~~~~~~~
+
+.. code-block:: dovecotconf
+
+    ssl_cert = </etc/dovecot/ssl/example.com.crt
+    ssl_key  = </etc/dovecot/ssl/example.com.key
+
+- Upstream documentation:
+  `Dovecot Wiki: SSL <http://wiki.dovecot.org/SSL>`_
+
+
+.. _acme_tiny_ref_lighttpd
+
+Lighttpd
+~~~~~~~~
+
+.. code-block:: lighttpdconf
+
+    ssl.pemfile /etc/lighttpd/ssl/example.com.pem
+    ssl.cafile  /etc/lighttpd/ssl/ca.crt
+
+- Upstream documentation:
+  `Lighttpd Wiki: Secure HTTP <http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_SSL>`_
+
+
+.. _acme_tiny_ref_nginx
+
+Nginx
+~~~~~
+
+.. code-block:: nginxconf
+
+    ssl_certificate     /etc/nginx/ssl/example.com.crt
+    ssl_certificate_key /etc/nginx/ssl/example.com.key
+
+- Upstream documentation:
+  `Module ngx_http_ssl_module <http://nginx.org/en/docs/http/ngx_http_ssl_module.html>`_
+
+
+.. _acme_tiny_ref_postfix 
+
+Postfix
+~~~~~~~
+
+.. code-block:: postfixconf
+
+    smtpd_tls_cert_file = /etc/nginx/ssl/example.com.crt
+    smtpd_tls_key_file  = /etc/nginx/ssl/example.com.key
+
+- Upstream documentation:
+  `Postfix TLS Support <http://www.postfix.org/TLS_README.html>`_
+
+
+.. _acme_tiny_ref_cert_renewal
+
+Certificate renewal
+-------------------
+
+..
+ Local Variables:
+ mode: rst
+ ispell-local-dictionary: "american"
+ End: