Bareos Configuration

Bareos Configuration Resource

To display a Bareos specific resource configuration file, use a code block:

.. code-block:: bareosconfig
   :caption: bareos-sd.d/device/FileStorage.conf

   Device {
     Name = FileStorage
     ...
     Archive Device = /var/lib/bareos/storage
     ...
   }

which will be displayed as

bareos-sd.d/device/FileStorage.conf
Device {
  Name = FileStorage
  ...
  Archive Device = /var/lib/bareos/storage
  ...
}

The caption shows the relevant path where to expect the configuration resource:

  1. <daemon>.d/ (bareos-dir.d, bareos-sd.d, bareos-fd.d, …)

  2. <resource type>/

  3. <resource name>.conf

The prefix path is not shown, as it is platform specific.

The directives should be written like shown in the documentation, meaning a separate words (‘’Archive Device’’ instead of ‘’ArchiveDevice’’ or ‘’archivedevice’’).

Use ... to indicate left out directives not relevant for the example.

Note

Remember to start each code-block line by 3 indenting spaces. However, the code itself is indented by the rules of the resource (2 spaces for Bareos configuration resources).

If the content is a separate file, use

.. literalinclude:: /include/config/bareos-sd.d/device/FileStorage.conf
   :language: bareosconfig
   :caption: bareos-dir.d/job/consolidate.conf

All configuration snippets should be located in the /include/config/ subdirectory of the documentation.

Normally, these snippets contain a complete Bareos configuration resource.

Resource Type

If you want to display a resource type, the following formatting should be used:

If you want to display the name of a specific resource, the following formatting should be used:

:config:option:`dir/job`

This will get displayed as

Job (Dir)

Resource Name

If you want to display the name of a specific resource, the following formatting should be used:

:config:option:`dir/job = backup-client1`

This will get displayed as

backup-client1 (Dir->Job)

Resource Directive

Resource Directive Definition

The documentation outline for resource directives is autogenerated (by https://github.com/bareos/bareos/blob/master/docs/manuals/scripts/generate-resource-descriptions.py) and stored into the https://github.com/bareos/bareos/tree/master/docs/manuals/source/include/autogenerated/ directory.

Inside the documentation, they can be referenced by the :config:option: directive. From extern, the URL to access them is

The automatically generated descriptions are defined in the C++ source code (as ResourceItem.description). They have to be short (1-2 short sentences) and can only contain plain text. Longer descriptions or descriptions that require formatting have to be written by creating of modifying the corresponding file in the manually_added_config_directive_descriptions/ subdirectory, e.g.:

Reference to a Resource Directive

If you want to display a resource directive, the following formatting should be used:

:config:option:`dir/job/AlwaysIncrementalJobRetention`

This will get displayed as

Always Incremental Job Retention (Dir->Job)

The signature must be given as:

<dir|sd|fd|console>/<resourcetype_lower_case>/<DirectiveInCamelCase>

Note

If the reference to a Resource Directive does not match a Resource Directive Definition, the displayed text will look the same, but there will be no hyperlink behind it.

In such cases, Sphinx issues a warning during build (WARNING: config:option reference target not found: ...).

Resource Directive With Value

If you want to display a resource directive along with its value, the following formatting should be used:

:config:option:`dir/job/AlwaysIncrementalJobRetention = 900`

This will get displayed as

Always Incremental Job Retention (Dir->Job) = 900