From d7792657a7de7050311cf8a9f144127b37480657 Mon Sep 17 00:00:00 2001 From: Niels Thykier Date: Tue, 1 May 2018 04:25:54 +0000 Subject: [PATCH] doc: Use a different style for hints config and file names Signed-off-by: Niels Thykier --- doc/setting-up-britney.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/doc/setting-up-britney.rst b/doc/setting-up-britney.rst index 3b7f53b..c3e921f 100644 --- a/doc/setting-up-britney.rst +++ b/doc/setting-up-britney.rst @@ -45,12 +45,12 @@ hints - Configuring who can provide which hints ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Britney reads all hints from a set of `hints` files. These files must -be placed in the directory denoted by the `HINTSDIR` configuration. -This is complimented with the `HINTS_` configurations that +be placed in the directory denoted by the ``HINTSDIR`` configuration. +This is complimented with the ``HINTS_`` configurations that defines a "hint file" and the related hint permissions for it. -For each `HINTS_` configuration, britney will attempt to read -`/`. Note that it lowercases `` when looking +For each ``HINTS_`` configuration, britney will attempt to read +``/``. Note that it lowercases ```` when looking for the file. @@ -62,36 +62,36 @@ Configuration example:: HINTS_FREEZE = block block-all block-udeb HINTS_AUTO-REMOVALS = remove -In the above example, we have defined 4 hints files named `anna`, -`john`, `freeze` and `auto-removals`. These must be placed in -`/etc/britney2/hints` and be readable by britney. Furthermore, they +In the above example, we have defined 4 hints files named ``anna``, +``john``, ``freeze`` and ``auto-removals``. These must be placed in +``/etc/britney2/hints`` and be readable by britney. Furthermore, they must be writable by (only) the people that are allowed to use the -particular hints file (apply `chown`, `chmod` and `setfacl` as +particular hints file (apply ``chown``, ``chmod`` and ``setfacl`` as neccesary). The values on the right hand side of the `=` decides which hints are permitted in the files. With the above definitions: - * The file `anna` may use any known hint (including potentially - dangerous ones like `force` and `force-hint`) + * The file ``anna`` may use any known hint (including potentially + dangerous ones like ``force`` and ``force-hint``) - * The file `john` may use most of the known hints. The set called STANDARD + * The file ``john`` may use most of the known hints. The set called STANDARD includes a lot of hints for overriding most policies when it can be done without (additional) side-effects. However, it - excludes `force` and `force-hint` as they can cause unintentional + excludes ``force`` and ``force-hint`` as they can cause unintentional results. - * The file `freeze` can use any of the hints `block`, `block-all` - and `block-udeb`. + * The file ``freeze`` can use any of the hints ``block``, ``block-all`` + and ``block-udeb``. - * The file `auto-removals` can only use the hint called `remove`. + * The file ``auto-removals`` can only use the hint called ``remove``. There are no fixed rules for how to use hints files. Though usually, each person with permissions to give hints to britney will have their own hint file along with write permissions for that file. It can also make sense to create hint files for "roles". Like in the above -example there are two human hinters (`anna` and `john`) plus two -non-human hinters (`freeze` and `auto-removals`). +example there are two human hinters (``anna`` and ``john``) plus two +non-human hinters (``freeze`` and ``auto-removals``). Please see :doc:`hints` for which hints are available and what they can do.