Add documentation of file system layout and service configuration

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,69 @@
+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::
+
+======================================================= ==================================
+: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.
+
+With help of the `acme_tiny__cert_type` an appropriate service certificate
+will be assembled and symlinked.
+
+E.g. For for Apache :program:`httpd` this would look like this:
+
+```txt
+/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 Lighttpd:
+
+```txt
+/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 Dovecot:
+
+```txt
+/etc/postfix/ssl/example.com.crt -> /etc/ssl/acme-tiny/example.com/example.com.crt
+/etc/postfix/ssl/example.com.key -> /etc/ssl/acme-tiny/example.com/example.com.key
+
+
+
+.. _acme_tiny_ref_service_cfg
+
+Service configuration
+---------------------
+
+
+.. _acme_tiny_ref_cert_renewal
+
+Certificate renewal
+-------------------
+
+..
+ Local Variables:
+ mode: rst
+ ispell-local-dictionary: "american"
+ End: