Warning: This document is for the development version of Bareos Documentation. The main version is bareos-21.

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 documenation, meaning a seperate words (‘’Archive Device’’ instead if ‘’ArchiveDevice’’ or ‘’archrivedevice’’).

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 seperate 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 documenation outline for resource directives is autogenerated (by https://github.com/bareos/bareos/blob/master/docs/manuals/scripts/generate-resoure-descriptions.py) and stored into the https://github.com/bareos/bareos/tree/master/docs/manuals/source/include/autogenerated/ directory.

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

While the automatically generated may contain a short description (if available in the source code), the description can be extended by creating of modifying the corresponding file in the manually_added_config_directive_descriptions/ subdirectory.

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>

For example:

dir/job/AlwaysIncrementalJobRetention

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.

Unfortenatly, if this is the case (the reference is wrong (e.g. because of a typo)) there will be no hint about this during Sphinx build.

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