Add more documentation for the CommModule files
authorJan Dittberner <jandd@cacert.org>
Mon, 29 Oct 2018 21:23:13 +0000 (22:23 +0100)
committerJan Dittberner <jandd@cacert.org>
Mon, 29 Oct 2018 21:23:13 +0000 (22:23 +0100)
source/directories.rst

index cc2b7ab..3cba141 100644 (file)
@@ -43,7 +43,8 @@ This directory contains the CommModule that is implemented in Perl:
 
 .. _commmodule-client-pl:
 
 
 .. _commmodule-client-pl:
 
-- :file:`client.pl` the real client, running on the webserver
+- :file:`client.pl` the :doc:`signer protocol <signer>` client, running
+  on the webserver and talking to the server via a serial link.
 
   The style of the Perl code seems a bit inconsistent (mix of uppercase and
   lowercase function names, usage of brackets). The code uses database polling
 
   The style of the Perl code seems a bit inconsistent (mix of uppercase and
   lowercase function names, usage of brackets). The code uses database polling
@@ -131,31 +132,63 @@ This directory contains the CommModule that is implemented in Perl:
   could be implemented via :command:`supervisor` or :command:`systemd`
   instead of a custom script.
 
   could be implemented via :command:`supervisor` or :command:`systemd`
   instead of a custom script.
 
-- :file:`commmodule` a script for startup/shutdown of CommModule from
-  /etc/init.d
+- :file:`commmodule` a System V style init script for startup/shutdown of
+  CommModule
+
+  On test.cacert.org two slightly different versions are deployed in
+  :file:`/etc/init.d` the first version starts
+  :ref:`client.pl <commmodule-client-pl>` in
+  :file:`/home/cacert/www/CommModule/` and the
+  second variant starts :ref:`server.pl <commmodule-server-pl>` in
+  :file:`/home/signer/cacert-devel/CommModule/`.
+
 - :file:`logclean.sh` maintenance script for logfiles generated by CommModule
 - :file:`logclean.sh` maintenance script for logfiles generated by CommModule
+
+  The :file:`logclean.sh` script performs log rotation of signer logfiles.
+
+  .. todo::
+
+     discuss replacement of this script with :command:`logrotate` and a
+     custom logrotate.conf for the signer
+
 - :file:`serial.conf` serial port configuration file
 
 - :file:`serial.conf` serial port configuration file
 
+  This file is read and written by both
+  :ref:`client.pl <commmodule-client-pl>` and
+  :ref:`server.pl <commmodule-server-pl>` therefore both cannot be run from
+  the same directory without interfering with each other.
+
+  .. todo::
+
+     add a serial.conf template and move the actual serial.conf into
+     configuration management
+
 .. _commmodule-server-pl:
 
 - :file:`server.pl` the real server, running on the signing server
 
 .. _commmodule-server-pl:
 
 - :file:`server.pl` the real server, running on the signing server
 
-  This script implements the signer (server) side of the signer protocol and
-  performs the actual signing operations.
+  This script implements the signer (server) side of the :doc:`signer
+  protocol <signer>` and performs the actual signing operations.
 
   The script contains a some code that is duplicated by
   :ref:`client.pl <commmodule-client-pl>`.
 
 
   The script contains a some code that is duplicated by
   :ref:`client.pl <commmodule-client-pl>`.
 
-- :file:`usbclient.pl` obsoleted USB version of
-  :ref:`client.pl <commmodule-client-pl>` above
+  .. note::
+
+     The :file:`server.pl` used on test.cacert.org is different from the
+     version in the cacert-devel repository. The git origin is recorded as
+     `git://git-cacert.it-sls.de/cacert-devel.git` and there are some small
+     uncommitted changes too.
 
 
-.. todo: remove unused file (usbclient.pl)
+  .. todo::
 
 
-.. todo: add a serial.conf template and move the actual serial.conf into
-   configuration management
+     get the versions of server.pl on git.cacert.org, the real production
+     signer and the cacert-devel repository synchronized
+
+- :file:`usbclient.pl` obsoleted USB version of
+  :ref:`client.pl <commmodule-client-pl>` above
 
 
-.. todo: clarify why log rotation is implemented with a custom
-   logclean.sh script instead of using logrotate
+  .. todo:: remove unused file (usbclient.pl)
 
 Directory :file:`includes`
 ==============================
 
 Directory :file:`includes`
 ==============================