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 documenation, meaning a separate 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 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.
Internally, 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
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.
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>
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