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
The caption shows the relevant path where to expect the configuration resource:
<daemon>
.d/(bareos-dir.d, bareos-sd.d, bareos-fd.d, …)<resource type>
/<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
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
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
Always Incremental Job Retention (Dir->Job)
.../Configuration/Director.html#config-Dir_Job_AlwaysIncrementalJobRetention
Allow Bandwidth Bursting (Fd->Client)
.../Configuration/FileDaemon.html#config-Fd_Client_AllowBandwidthBursting
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.:
Always Incremental Job Retention (Dir->Job)
manually_added_config_directive_descriptions/dir-job-AlwaysIncrementalJobRetention.rst.inc
Allow Bandwidth Bursting (Fd->Client)
manually_added_config_directive_descriptions/fd-client-AllowBandwidthBursting.rst.inc
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