Improve system documentation
authorJan Dittberner <jandd@cacert.org>
Tue, 30 Jul 2019 22:42:15 +0000 (00:42 +0200)
committerJan Dittberner <jandd@cacert.org>
Tue, 30 Jul 2019 22:51:50 +0000 (00:51 +0200)
- add monitoring links and index entry to Monitoring section
- adapt to modified template structure

21 files changed:
docs/systems/blog.rst
docs/systems/board.rst
docs/systems/bugs.rst
docs/systems/cats.rst
docs/systems/email.rst
docs/systems/git.rst
docs/systems/infra02.rst
docs/systems/ircserver.rst
docs/systems/issue.rst
docs/systems/jenkins.rst
docs/systems/lists.rst
docs/systems/monitor.rst
docs/systems/proxyout.rst
docs/systems/puppet.rst
docs/systems/svn.rst
docs/systems/test.rst
docs/systems/test3.rst
docs/systems/translations.rst
docs/systems/web.rst
docs/systems/webmail.rst
docs/systems/webstatic.rst

index 94303d6..482d24e 100644 (file)
@@ -85,6 +85,9 @@ Logical Location
 
    See :doc:`../network`
 
+.. index::
+   single: Monitoring; Blog
+
 Monitoring
 ----------
 
@@ -335,25 +338,28 @@ Wordpress configuration
 Tasks
 =====
 
-.. todo:: switch to Puppet management
-.. todo:: replace nrpe with icinga2 agent
-.. todo:: update wordpress to 5.x
+.. todo:: add a section documenting wordpress and plugin updates
+.. todo:: add a section documenting wordpress user management
+
+Changes
+=======
 
 Planned
 -------
 
+.. todo:: switch to Puppet management
+.. todo:: replace nrpe with icinga2 agent
+.. todo:: update wordpress to 5.x
+.. todo:: update to Debian 9/10
 .. todo:: setup IPv6
 
 .. todo::
    setup CRL checks (can be borrowed from :doc:`svn`) for client certificates
 
-Changes
-=======
-
 System Future
 -------------
 
-.. todo:: system should be upgraded to Debian 9 or 10
+* No plans
 
 Additional documentation
 ========================
index e664b24..3a34cf5 100644 (file)
@@ -70,6 +70,9 @@ Logical Location
 
    See :doc:`../network`
 
+.. index::
+   single: Monitoring; Board
+
 Monitoring
 ----------
 
@@ -346,22 +349,24 @@ that the XML-RPC service binds to.
 Tasks
 =====
 
-.. todo:: switch to Puppet management
-.. todo:: replace nrpe with icinga2 agent
+.. todo:: add a section documenting how to add/remove openerp users
+
+Changes
+=======
 
 Planned
 -------
 
+.. todo:: switch to Puppet management
+.. todo:: replace nrpe with icinga2 agent
 .. todo:: disable unneeded Apache modules
 .. todo:: setup IPv6
-
-Changes
-=======
+.. todo:: update to Debian 8/9/10
 
 System Future
 -------------
 
-.. todo:: system should be updated to Debian 8/9/10
+* No plans
 
 Additional documentation
 ========================
index 1b85bfd..79d37d7 100644 (file)
@@ -71,6 +71,9 @@ Logical Location
 
    See :doc:`../network`
 
+.. index::
+   single: Monitoring; Bugs
+
 Monitoring
 ----------
 
@@ -354,13 +357,17 @@ add an additional logging socket in the Postfix chroot.
 Tasks
 =====
 
-.. todo:: upgrade to Debian 10 (when Puppet is available)
+.. todo:: add a section documenting how to manage mantis projects
+.. todo:: add a section documenting how to manage mantis users
+
+Changes
+=======
 
 Planned
 -------
 
-Changes
-=======
+.. todo:: upgrade to Debian 10 (when Puppet is available)
+
 
 System Future
 -------------
index 73b9f6b..b640cb2 100644 (file)
@@ -357,23 +357,24 @@ MySQL configuration is stored in the :file:`/etc/mysql/` directory.
 Tasks
 =====
 
-.. todo:: switch to Puppet management
-.. todo:: replace nrpe with icinga2 agent
+.. todo:: document how to update the CATS software
+
+Changes
+=======
 
 Planned
 -------
 
+.. todo:: switch to Puppet management
+.. todo:: replace nrpe with icinga2 agent
 .. todo:: update to Debian 8/9/10
 .. todo:: setup IPv6
 .. todo:: setup CRL checks
 
-Changes
-=======
-
 System Future
 -------------
 
-.. todo:: system should be updated to Debian 8/9
+* No plans
 
 Additional documentation
 ========================
index 65d32bc..a078357 100644 (file)
@@ -54,6 +54,9 @@ Logical Location
 
    See :doc:`../network`
 
+.. index::
+   single: Monitoring; Email
+
 Monitoring
 ----------
 
@@ -533,6 +536,15 @@ There are two types of aliases.
    cacertusers database. The reason for this implementation is to only allow
    the designated person to send email from this email address.
 
+Client certificate authentication
+---------------------------------
+
+There were plans for X.509 certificate authentication for mail services, but
+there is no progress so far.
+
+Changes
+=======
+
 Planned
 -------
 
@@ -548,12 +560,6 @@ Planned
 .. todo::
    consider to use LDAP to consolidate user, password and email information
 
-* there were plans for X.509 certificate authentication for mail services, but
-  there is no progress so far
-
-Changes
-=======
-
 System Future
 -------------
 
index 4b59901..2569538 100644 (file)
@@ -73,6 +73,14 @@ Logical Location
 
    See :doc:`../network`
 
+.. index::
+   single: Monitoring; Git
+
+Monitoring
+----------
+
+:internal checks: :monitor:`git.infra.cacert.org`
+
 DNS
 ---
 
@@ -326,14 +334,14 @@ The runit service handling is triggered through :file:`/etc/inittab`.
 Tasks
 =====
 
+Changes
+=======
+
 Planned
 -------
 
 .. todo:: enable IPv6
 
-Changes
-=======
-
 System Future
 -------------
 
index 93d934c..69af457 100644 (file)
@@ -330,32 +330,6 @@ Risk assessments and critical packages
 The system is the host system for all other infrastructure systems. Access to
 this system has to be tightly controlled.
 
-Tasks
-=====
-
-The system can be rebooted safely since the Debian Buster installation on
-2019-07-13.
-
-.. todo:: document how to setup a new container
-.. todo:: document how to setup firewall rules/forwarding
-.. todo:: document how the backup system works
-.. todo:: add DNS setup for IPv6 address
-.. todo:: switch to Puppet management
-.. todo:: replace nrpe with icinga2 agent
-
-Planned
--------
-
-* Replace ferm with nftables setup
-
-Changes
-=======
-
-System Future
--------------
-
-* No plans
-
 Critical Configuration items
 ============================
 
@@ -390,6 +364,50 @@ The container configuration is contained in files named
 The root filesystems of the containers are stored on :term:`LVM` volumes that
 are mounted in :file:`/var/lib/lxc/<container>/rootfs` for each container.
 
+Tasks
+=====
+
+.. todo:: document how to setup a new container
+.. todo:: document how to setup firewall rules/forwarding
+.. todo:: document how the backup system works
+
+Reboot
+------
+
+The system can be rebooted safely since the Debian Buster installation on
+2019-07-13:
+
+.. code-block:: bash
+
+   systemctl reboot
+
+Restarting the firewall
+-----------------------
+
+To restart the firewall setup perform a configuration syntax check and use
+systemctl to reload ferm's configuration.
+
+.. code-block:: bash
+
+   ferm -n /etc/ferm/ferm.conf
+   systemctl reload ferm.service
+
+Changes
+=======
+
+Planned
+-------
+
+.. todo:: add DNS setup for IPv6 address
+.. todo:: switch to Puppet management
+.. todo:: replace nrpe with icinga2 agent
+.. todo:: replace ferm with nftables setup
+
+System Future
+-------------
+
+* No plans
+
 Additional documentation
 ========================
 
index 73bc66d..ac8e68a 100644 (file)
@@ -69,6 +69,14 @@ Logical Location
 
    See :doc:`../network`
 
+.. index::
+   single: Monitoring; Ircserver
+
+Monitoring
+----------
+
+:internal checks: :monitor:`ircserver.infra.cacert.org`
+
 DNS
 ---
 
index 111c685..99f127c 100644 (file)
@@ -74,6 +74,14 @@ Logical Location
 
    See :doc:`../network`
 
+.. index::
+   single: Monitoring; Issue
+
+Monitoring
+----------
+
+:internal checks: :monitor:`issue.infra.cacert.org`
+
 DNS
 ---
 
@@ -303,6 +311,38 @@ Postfix configuration
 Tasks
 =====
 
+Creating new OTRS user accounts
+-------------------------------
+
+* Go to Admin -> Users -> Add
+* Fill out user details
+
+  * Use a securely random generated password (min. 12 chars, mixed of capital-
+    non-capital letters, numbers and special chars), send it to the user via
+    encrypted mail (also include URL of the issue tracking system, username and
+    some initial instructions or a link to documentation if available)
+  * Use CAcert email addresses only
+
+* Set the preferences for the user. Good standards are:
+
+  * Show tickets: 25
+  * New ticket notification: Yes (or No for high volume queues having agents regulary looking at
+  * Follow up notification: Yes
+  * Ticket lock timeout notification: Yes
+  * Move notification: Yes (or No if the queues for the user get many new tickets)
+  * Spelling Dictionary: English 
+
+* Submit
+* Do NOT set any groups for the user.
+* Go to Admin -> Users -> Roles <-> Users
+* Choose the newly created user
+* Set the roles the user has
+* Submit
+* Now you are done :) 
+
+Changes
+=======
+
 Planned
 -------
 
@@ -334,10 +374,6 @@ Ideas
 
 * Use centralised logging
 
-
-Changes
-=======
-
 System Future
 -------------
 
@@ -346,36 +382,6 @@ System Future
 Additional documentation
 ========================
 
-Creating new OTRS user accounts
--------------------------------
-
-* Go to Admin -> Users -> Add
-* Fill out user details
-
-  * Use a securely random generated password (min. 12 chars, mixed of capital-
-    non-capital letters, numbers and special chars), send it to the user via
-    encrypted mail (also include URL of the issue tracking system, username and
-    some initial instructions or a link to documentation if available)
-  * Use CAcert email addresses only
-
-* Set the preferences for the user. Good standards are:
-
-  * Show tickets: 25
-  * New ticket notification: Yes (or No for high volume queues having agents regulary looking at
-  * Follow up notification: Yes
-  * Ticket lock timeout notification: Yes
-  * Move notification: Yes (or No if the queues for the user get many new tickets)
-  * Spelling Dictionary: English 
-
-* Submit
-* Do NOT set any groups for the user.
-* Go to Admin -> Users -> Roles <-> Users
-* Choose the newly created user
-* Set the roles the user has
-* Submit
-* Now you are done :) 
-
-
 .. seealso::
 
    * :wiki:`PostfixConfiguration`
index ccbc23d..456967b 100644 (file)
@@ -68,6 +68,14 @@ Logical Location
 
    See :doc:`../network`
 
+.. index::
+   single: Monitoring; Jenkins
+
+Monitoring
+----------
+
+:internal checks: :monitor:`jenkins.infra.cacert.org`
+
 DNS
 ---
 
@@ -234,11 +242,19 @@ management web interface with role based access control.
 Tasks
 =====
 
+Changes
+=======
+
 Planned
 -------
 
 * build more of CAcert's software on the Jenkins instance
 
+System Future
+-------------
+
+* No plans
+
 Additional documentation
 ========================
 
index 02e4be1..1adfe36 100644 (file)
@@ -375,16 +375,15 @@ Adding a list
 
 5. add subscribers/ other owners
 
+Changes
+=======
+
 Planned
 -------
 
 .. todo:: upgrade the lists system OS to Debian 9 (Stretch)
-
 .. todo:: manage the lists system using Puppet
 
-Changes
-=======
-
 System Future
 -------------
 
index 20b89a2..72439bb 100644 (file)
@@ -83,6 +83,14 @@ Logical Location
 
    See :doc:`../network`
 
+.. index::
+   single: Monitoring; Monitor
+
+Monitoring
+----------
+
+:internal checks: :monitor:`monitor.infra.cacert.org`
+
 DNS
 ---
 
@@ -311,14 +319,12 @@ configurations are defined in the :file:`objects/` subdirectory.
 Tasks
 =====
 
-Planned
--------
-
-.. todo:: switch to Icinga2 and Icingaweb2
-
 Changes
 =======
 
+Planned
+-------
+
 System Future
 -------------
 
index d28c710..e2ca456 100644 (file)
@@ -70,6 +70,14 @@ Logical Location
 
    See :doc:`../network`
 
+.. index::
+   single: Monitoring; Proxyout
+
+Monitoring
+----------
+
+:internal checks: :monitor:`proxyout.infra.cacert.org`
+
 DNS
 ---
 
@@ -217,6 +225,11 @@ configuration items outside of the Puppet repository.
 Tasks
 =====
 
+.. todo:: add a section describing how to add ACLs to Squid
+
+Changes
+=======
+
 Planned
 -------
 
@@ -225,6 +238,11 @@ Planned
 
 .. todo:: Add more APT repositories and ACLs if needed
 
+System Future
+-------------
+
+* No plans
+
 Additional documentation
 ========================
 
index 9c06c49..699ce52 100644 (file)
@@ -72,6 +72,14 @@ Logical Location
 
    See :doc:`../network`
 
+.. index::
+   single: Monitoring; Puppet
+
+Monitoring
+----------
+
+:internal checks: :monitor:`puppet.infra.cacert.org`
+
 DNS
 ---
 
@@ -254,7 +262,6 @@ trusted Puppet agents.
 The CA data is stored in :file:`/etc/puppetlabs/puppet/ssl` and managed by
 puppet itself.
 
-
 Eyaml private key
 -----------------
 
@@ -264,7 +271,6 @@ key in :file:`keys/public_key.pkcs7.pem` in the `CAcert puppet Git repository
 private key is stored in
 :file:`/etc/puppetlabs/code/environments/production/keys/private_key.pkcs7.pem`.
 
-
 hiera configuration
 -------------------
 
@@ -272,7 +278,6 @@ Puppet uses Hiera for hierarchical information retrieval. The global hiera
 configuration is stored in :file:`/etc/puppetlabs/puppet/hiera.yaml` and
 defines the hierarchy lookup as well as the eyaml key locations.
 
-
 puppet configuration
 --------------------
 
@@ -288,21 +293,19 @@ pattern (see references below) and code/data separation via Hiera.
 Updates to the cacert-puppet repository trigger a web hook listening on tcp
 port 8000 that automatically updates the production environment directory.
 
-
 Tasks
 =====
 
+.. todo:: add a section to describe how to add a system for puppet management
+
+Changes
+=======
+
 Planned
 -------
 
 * migrate as many systems as possible to use Puppet for a more
   reproducible/auditable system setup
-* automate updates of the Puppet code from Git
-
-.. todo:: improve Webhook to run r10k after git pull
-
-Changes
-=======
 
 System Future
 -------------
index 45a4244..f041269 100644 (file)
@@ -83,6 +83,14 @@ Logical Location
 
    See :doc:`../network`
 
+.. index::
+   single: Monitoring; Svn
+
+Monitoring
+----------
+
+:internal checks: :monitor:`svn.infra.cacert.org`
+
 DNS
 ---
 
@@ -317,12 +325,6 @@ CRLs are updated by :file:`/etc/cron.daily/fetchcrls`.
 Tasks
 =====
 
-Planned
--------
-
-The configuration of this system will be migrated to a setup fully managed by
-Puppet.
-
 X.509 Auth for policy
 ---------------------
 
@@ -337,6 +339,13 @@ Mail notifications
 Changes
 =======
 
+Planned
+-------
+
+The configuration of this system will be migrated to a setup fully managed by
+Puppet.
+
+
 System Future
 -------------
 
index 0f9ac65..c9f620b 100644 (file)
@@ -70,6 +70,14 @@ Logical Location
 
    See :doc:`../network`
 
+.. index::
+   single: Monitoring; Test
+
+Monitoring
+----------
+
+:internal checks: :monitor:`test.infra.cacert.org`
+
 DNS
 ---
 
@@ -434,6 +442,9 @@ and to use mbox style mailboxes in /var/mail/%u in the following files:
 Tasks
 =====
 
+Changes
+=======
+
 Planned
 -------
 
@@ -441,8 +452,6 @@ Planned
 
    Upgrade test to Debian Stretch when the software is ready.
 
-Changes
-=======
 
 System Future
 -------------
index 444cf87..f735bec 100644 (file)
@@ -83,6 +83,14 @@ there are some special mappings in the infra02 firewall to get access to this sy
 
    See :doc:`../network`
 
+.. index::
+   single: Monitoring; Test3
+
+Monitoring
+----------
+
+.. :internal checks: :monitor:`test3.infra.cacert.org`
+
 DNS
 ---
 
@@ -449,14 +457,14 @@ all mail is delivered to the mailbox of the *cacertmail* user in
 Tasks
 =====
 
+Changes
+=======
+
 Planned
 -------
 
 .. todo:: implement git workflows for updates maybe using :doc:`jenkins`
 
-Changes
-=======
-
 System Future
 -------------
 
index 572849b..c9252e3 100644 (file)
@@ -71,6 +71,14 @@ Logical Location
 
    See :doc:`../network`
 
+.. index::
+   single: Monitoring; Translations
+
+Monitoring
+----------
+
+:internal checks: :monitor:`translations.infra.cacert.org`
+
 DNS
 ---
 
@@ -394,6 +402,9 @@ Pootle version and have to be checked/updated.
 Tasks
 =====
 
+Changes
+=======
+
 Planned
 -------
 
@@ -413,8 +424,6 @@ Planned
    them with the :program:`sudo` system to allow members of the `pootle-update`
    group to run them in the context of the `pootle` system user
 
-Changes
-=======
 
 System Future
 -------------
index 546572c..4be3549 100644 (file)
@@ -68,6 +68,14 @@ Logical Location
 
    See :doc:`../network`
 
+.. index::
+   single: Monitoring; Web
+
+Monitoring
+----------
+
+:internal checks: :monitor:`web.infra.cacert.org`
+
 DNS
 ---
 
@@ -310,14 +318,14 @@ Apache httpd configuration
 Tasks
 =====
 
+Changes
+=======
+
 Planned
 -------
 
 .. todo:: manage the web system using Puppet
 
-Changes
-=======
-
 System Future
 -------------
 
index 7878236..0eb88d8 100644 (file)
@@ -329,14 +329,14 @@ The board voting system uses a SQLite database in
 Tasks
 =====
 
+Changes
+=======
+
 Planned
 -------
 
 .. todo:: implement CRL checking
 
-Changes
-=======
-
 System Future
 -------------
 
index 77c175b..8892a0b 100644 (file)
@@ -77,6 +77,14 @@ Logical Location
 
    See :doc:`../network`
 
+.. index::
+   single: Monitoring; Webstatic
+
+Monitoring
+----------
+
+:internal checks: :monitor:`webstatic.infra.cacert.org`
+
 DNS
 ---
 
@@ -274,14 +282,14 @@ The main configuration files for Apache httpd are:
 Tasks
 =====
 
+Changes
+=======
+
 Planned
 -------
 
 .. todo:: manage the webstatic system using Puppet
 
-Changes
-=======
-
 System Future
 -------------