diff --git a/docs/manuals/en/new_main_reference/replace.sh b/docs/manuals/en/new_main_reference/replace.sh index ca6b2e335c9..5536d4fd826 100755 --- a/docs/manuals/en/new_main_reference/replace.sh +++ b/docs/manuals/en/new_main_reference/replace.sh @@ -67,8 +67,8 @@ sed -i 's#:raw-latex:`\\yeno`#yes\\|no#g' *.rst #sed -i 's|:raw-latex:`\\command{bconsole}`|:command:`bconsole`|g' *.rst #sed -i -E 's|:raw-latex:`\\command\{(.*)\}`|:command:`\1`|g' *.rst -perl -i -pe 's#:raw-latex:`\\command\{(.*?)\}`#:command:`\1`#g' *.rst -perl -i -pe 's#:raw-latex:`\\bcommand\{(.*?)\}\{(.*?)\}`#:command:`\1 \2`#g' *.rst +perl -i -pe 's#:raw-latex:`\\command\{(.*?)\}`#:program:`\1`#g' *.rst +perl -i -pe 's#:raw-latex:`\\bcommand\{(.*?)\}\{(.*?)\}`#:program:`\1 \2`#g' *.rst @@ -138,11 +138,11 @@ sed -i -E 's|:raw-latex:`\\index\[sd\]\{(.*)\}`|.. index:: SD; \1 |g' *.rst #sed -i -E 's|:raw-latex:`\\label\{(.*)\}`|.. _\1: \1|g' *.rst sed -i -E 's|:raw-latex:`\\label\{(.*)\}`|\n\n.. _`\1`: \1|g' *.rst -perl -i -pe 's|:raw-latex:`\\nameref\{(.*?)\}`|:ref:`\1`|g' *.rst +perl -i -pe 's|:raw-latex:`\\nameref\{(.*?)\}`|:ref:`\1`_|g' *.rst sed -i -E 's|:raw-latex:`\\elink\{(.*)\}\{(.*)\}`|`\1 <\2>`_|g' *.rst -perl -i -pe 's|:raw-latex:`\\ilink\{(.*?)\}\{(.*?)\}`|:ref:`\2 \1`|g' *.rst +perl -i -pe 's|:raw-latex:`\\ilink\{(.*?)\}\{(.*?)\}`|:ref:`\1 <\2>`_|g' *.rst # # Warnings @@ -155,6 +155,7 @@ sed -i -E 's|:raw-latex:`\\linkResourceDirectiveValue\{(.*)\}\{(.*)\}\{(.*)\}\{( sed -i -E 's|:raw-latex:`\\resourceDirectiveValue\{(.*)\}\{(.*)\}\{(.*)\}\{(.*)\}`|**\3 = \4** (\1 configuration, \2 resource)|g' *.rst +sed -i -E 's#sec:#section_#g' *.rst # # IMAGES (JUST A FEW, SO MAYBE MANUALLY) diff --git a/docs/manuals/en/new_main_reference/source/always-incremental.rst b/docs/manuals/en/new_main_reference/source/always-incremental.rst index 75ea8f6e39d..d1cfa4321c8 100644 --- a/docs/manuals/en/new_main_reference/source/always-incremental.rst +++ b/docs/manuals/en/new_main_reference/source/always-incremental.rst @@ -1,21 +1,17 @@ -.. _sec:alwaysincremental: +.. _sec-alwaysincremental: Always Incremental Backup Scheme ================================ -.. index:: General; Always Incremental -.. _`Always Incremental`: - +:raw-latex:`\index[general]{Always Incremental}` Always Incremental Backups are available since Bareos -16.2.4. +:raw-latex:`\sinceVersion{dir}{Always Incremental}{16.2.4}`. Conventional Backup Scheme Drawbacks ------------------------------------ -.. index:: General; Retention -.. _`Retention`: - +:raw-latex:`\index[general]{Retention}` To better understand the advantages of the Always Incremental Backup scheme, we first analyze the way that the conventional Incremental - @@ -70,7 +66,7 @@ These two steps are then executed every day: - Consolidation of the jobs older than maximum configure age Deleted files will be in the backup forever, if they are not detected as -deleted using **Accurate** (Dir configuration, Job resource) +deleted using :raw-latex:`\linkResourceDirective{Dir}{Job}{Accurate}` backup. The Always Incremental Backup Scheme does not provide the option to have @@ -116,69 +112,67 @@ Always Incremental Backup Job To configure a job to use Always Incremental Backup Scheme, following configuration is required: -.. raw:: latex +:: - \begin{bareosConfigResource}{bareos-dir}{job}{example} - Job { - ... - Accurate = yes - Always Incremental = yes - Always Incremental Job Retention = - Always Incremental Keep Number = - ... - } - \end{bareosConfigResource} + {bareos-dir}{job}{example} + Job { + ... + Accurate = yes + Always Incremental = yes + Always Incremental Job Retention = + Always Incremental Keep Number = + ... + } -**Accurate = yes** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirectiveValue{Dir}{Job}{Accurate}{yes}` is required to detect deleted files and prevent that they are kept in the consolidated backup jobs. -**Always Incremental = yes** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirectiveValue{Dir}{Job}{Always Incremental}{yes}` enables the Always Incremental feature. -**Always Incremental Job Retention** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Job Retention}` set the age where incrementals of this job will be kept, older jobs will be consolidated. -**Always Incremental Keep Number** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Keep Number}` sets the number of incrementals that will be kept without regarding the age. This should make sure that a certain history of a job will be kept even if the job is not executed for some time. -**Always Incremental Max Full Age** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Max Full Age}` is described later, see - :ref:`sec:AlwaysIncrementalMaxFullAge`. + :raw-latex:`\nameref{sec-AlwaysIncrementalMaxFullAge}`. Consolidate Job ~~~~~~~~~~~~~~~ -.. raw:: latex +:: - \begin{bareosConfigResource}{bareos-dir}{job}{Consolidate} - Job { - Name = "Consolidate" - Type = "Consolidate" - Accurate = "yes" - JobDefs = "DefaultJob" - } - \end{bareosConfigResource} + {bareos-dir}{job}{Consolidate} + Job { + Name = "Consolidate" + Type = "Consolidate" + Accurate = "yes" + JobDefs = "DefaultJob" + } -**Type = Consolidate** (Dir configuration, Job resource) +:raw-latex:`\resourceDirectiveValue{Dir}{Job}{Type}{Consolidate}` configures a job to be a consolidate job. This type have been introduced with the Always Incremental feature. When used, it automatically trigger the consolidation of incremental jobs that need to be consolidated. -**Accurate = yes** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirectiveValue{Dir}{Job}{Accurate}{yes}` let the generated virtual backup job keep the accurate information. -**Max Full Consolidations** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirective{Dir}{Job}{Max Full Consolidations}` is described later, see - :ref:`sec:MaxFullConsolidations`. + :raw-latex:`\nameref{sec-MaxFullConsolidations}`. -The **Consolidate** job evaluates all jobs configured +The :raw-latex:`\job{Consolidate}` job evaluates all jobs configured with -**Always Incremental = yes** (Dir configuration, Job resource). +:raw-latex:`\linkResourceDirectiveValue{Dir}{Job}{Always Incremental}{yes}`. When a job is selected for consolidation, all job runs are taken into account, independent of the pool and storage where they are located. @@ -198,61 +192,58 @@ Storages and Pools ~~~~~~~~~~~~~~~~~~ For the Always Incremental Backup Scheme at least two storages are -needed. See :ref:`sec:MultipleStorageDevices` how to +needed. See :raw-latex:`\nameref{sec-MultipleStorageDevices}` how to setup multiple storages. -.. raw:: latex - - \begin{bareosConfigResource}{bareos-dir}{pool}{AI-Incremental} - Pool { - Name = AI-Incremental - Pool Type = Backup - Recycle = yes # Bareos can automatically recycle Volumes - Auto Prune = yes # Prune expired volumes - Volume Retention = 360 days # How long should jobs be kept? - Maximum Volume Bytes = 50G # Limit Volume size to something reasonable - Label Format = "AI-Incremental-" - Volume Use Duration = 23h - Storage = File1 - Next Pool = AI-Consolidated # consolidated jobs go to this pool - } - \end{bareosConfigResource} - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-dir}{pool}{AI-Consolidated} - Pool { - Name = AI-Consolidated - Pool Type = Backup - Recycle = yes # Bareos can automatically recycle Volumes - Auto Prune = yes # Prune expired volumes - Volume Retention = 360 days # How long should jobs be kept? - Maximum Volume Bytes = 50G # Limit Volume size to something reasonable - Label Format = "AI-Consolidated-" - Volume Use Duration = 23h - Storage = File2 - Next Pool = AI-Longterm # copy jobs write to this pool - } - \end{bareosConfigResource} - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-dir}{pool}{AI-Longterm} - Pool { - Name = AI-Longterm - Pool Type = Backup - Recycle = yes # Bareos can automatically recycle Volumes - Auto Prune = yes # Prune expired volumes - Volume Retention = 10 years # How long should jobs be kept? - Maximum Volume Bytes = 50G # Limit Volume size to something reasonable - Label Format = "AI-Longterm-" - Volume Use Duration = 23h - Storage = File1 - } - \end{bareosConfigResource} - -**AI-Longterm** is optional and will be explained in -:ref:`sec:AlwaysIncrementalLongTermStorage`. +:: + + {bareos-dir}{pool}{AI-Incremental} + Pool { + Name = AI-Incremental + Pool Type = Backup + Recycle = yes # Bareos can automatically recycle Volumes + Auto Prune = yes # Prune expired volumes + Volume Retention = 360 days # How long should jobs be kept? + Maximum Volume Bytes = 50G # Limit Volume size to something reasonable + Label Format = "AI-Incremental-" + Volume Use Duration = 23h + Storage = File1 + Next Pool = AI-Consolidated # consolidated jobs go to this pool + } + +:: + + {bareos-dir}{pool}{AI-Consolidated} + Pool { + Name = AI-Consolidated + Pool Type = Backup + Recycle = yes # Bareos can automatically recycle Volumes + Auto Prune = yes # Prune expired volumes + Volume Retention = 360 days # How long should jobs be kept? + Maximum Volume Bytes = 50G # Limit Volume size to something reasonable + Label Format = "AI-Consolidated-" + Volume Use Duration = 23h + Storage = File2 + Next Pool = AI-Longterm # copy jobs write to this pool + } + +:: + + {bareos-dir}{pool}{AI-Longterm} + Pool { + Name = AI-Longterm + Pool Type = Backup + Recycle = yes # Bareos can automatically recycle Volumes + Auto Prune = yes # Prune expired volumes + Volume Retention = 10 years # How long should jobs be kept? + Maximum Volume Bytes = 50G # Limit Volume size to something reasonable + Label Format = "AI-Longterm-" + Volume Use Duration = 23h + Storage = File1 + } + +:raw-latex:`\pool{AI-Longterm}` is optional and will be explained in +:raw-latex:`\nameref{sec-AlwaysIncrementalLongTermStorage}`. How it works ------------ @@ -262,34 +253,32 @@ configured for always incremental Backup. The Backup itself is scheduled every night to run as incremental backup, while the consolidation is scheduled to run every day. -.. raw:: latex +:: - \begin{bareosConfigResource}{bareos-dir}{job}{BackupClient1} - Job { - Name = "BackupClient1" - JobDefs = "DefaultJob" + {bareos-dir}{job}{BackupClient1} + Job { + Name = "BackupClient1" + JobDefs = "DefaultJob" - # Always incremental settings - AlwaysIncremental = yes - AlwaysIncrementalJobRetention = 7 days + # Always incremental settings + AlwaysIncremental = yes + AlwaysIncrementalJobRetention = 7 days - Accurate = yes + Accurate = yes - Pool = AI-Incremental - Full Backup Pool = AI-Consolidated - } - \end{bareosConfigResource} + Pool = AI-Incremental + Full Backup Pool = AI-Consolidated + } -.. raw:: latex +:: - \begin{bareosConfigResource}{bareos-dir}{job}{Consolidate} - Job { - Name = "Consolidate" - Type = "Consolidate" - Accurate = "yes" - JobDefs = "DefaultJob" - } - \end{bareosConfigResource} + {bareos-dir}{job}{Consolidate} + Job { + Name = "Consolidate" + Type = "Consolidate" + Accurate = "yes" + JobDefs = "DefaultJob" + } The following image shows the available backups for each day: @@ -300,13 +289,13 @@ The following image shows the available backups for each day: - Every day a incremental backup is done and is additionally available. - When the age of the oldest incremental reaches - **Always Incremental Job Retention** (Dir configuration, Job resource), + :raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Job Retention}`, the consolidation job consolidates the oldest incremental with the full backup before to a new full backup. This can go on more or less forever and there will be always an incremental history of -**Always Incremental Job Retention** (Dir configuration, Job resource). +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Job Retention}`. The following plot shows what happens if a job is not run for a certain amount of time. @@ -318,18 +307,18 @@ until the last incremental is too old and then only one full backup is left. This is usually not what is intended. For this reason, the directive -**Always Incremental Keep Number** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Keep Number}` is available which sets the minimum number of incrementals that should be kept even if they are older than -**Always Incremental Job Retention** (Dir configuration, Job resource). +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Job Retention}`. Setting -**Always Incremental Keep Number** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Keep Number}` to 7 in our case leads to the following result: |image| -**Always Incremental Keep Number** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Keep Number}` incrementals are always kept, and when the backup starts again the consolidation of old incrementals starts again. @@ -375,35 +364,35 @@ always incremental scheme. |image| -.. _sec:AlwaysIncrementalMaxFullAge: +.. _sec-AlwaysIncrementalMaxFullAge: Always Incremental Max Full Age ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To be able to cope with this problem, the directive -**Always Incremental Max Full Age** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Max Full Age}` was added. When -**Always Incremental Max Full Age** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Max Full Age}` is configured, in daily operation the Full Backup is left untouched while the incrementals are consolidated as usual. Only if the Full Backup is older than -**Always Incremental Max Full Age** (Dir configuration, Job resource), +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Max Full Age}`, the full backup will also be part of the consolidation. Depending on the setting of the -**Always Incremental Max Full Age** (Dir configuration, Job resource), +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Max Full Age}`, the amount of daily data being moved can be reduced without losing the advantages of the always incremental Backup Scheme. -**Always Incremental Max Full Age** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Max Full Age}` must be larger than -**Always Incremental Job Retention** (Dir configuration, Job resource). +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Job Retention}`. The resulting interval between full consolidations when running daily backups and daily consolidations is -**Always Incremental Max Full Age** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Max Full Age}` - -**Always Incremental Job Retention** (Dir configuration, Job resource). +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Job Retention}`. .. raw:: latex @@ -423,16 +412,16 @@ backups and daily consolidations is Jobs Available with "Always Incremental Max Full Age" -.. _sec:MaxFullConsolidations: +.. _sec-MaxFullConsolidations: Max Full Consolidations ~~~~~~~~~~~~~~~~~~~~~~~ When the -**Always Incremental Max Full Age** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Max Full Age}` of many clients is set to the same value, it is probable that all full backups will reach the -**Always Incremental Max Full Age** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Max Full Age}` at once and so consolidation jobs including the full backup will be started for all clients at once. This would again mean that the whole data being stored from all clients will be moved in one day. @@ -447,28 +436,27 @@ As can be seen, virtual jobs including the full are triggered for all three clients at the same time. This is of course not desirable so the directive -**Max Full Consolidations** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirective{Dir}{Job}{Max Full Consolidations}` was introduced. -**Max Full Consolidations** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirective{Dir}{Job}{Max Full Consolidations}` needs to be configured in the -**Type = Consolidate** (Dir configuration, Job resource) job: +:raw-latex:`\resourceDirectiveValue{Dir}{Job}{Type}{Consolidate}` job: -.. raw:: latex +:: - \begin{bareosConfigResource}{bareos-dir}{job}{Consolidate} - Job { - Name = "Consolidate" - Type = "Consolidate" - Accurate = "yes" - JobDefs = "DefaultJob" + {bareos-dir}{job}{Consolidate} + Job { + Name = "Consolidate" + Type = "Consolidate" + Accurate = "yes" + JobDefs = "DefaultJob" - Max Full Consolidations = 1 - } - \end{bareosConfigResource} + Max Full Consolidations = 1 + } If -**Max Full Consolidations** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirective{Dir}{Job}{Max Full Consolidations}` is configured, the consolidation job will not start more than the specified Consolidations that include the Full Backup. @@ -478,9 +466,9 @@ jobs are completed before the next normal backup run starts. The number of always incremental jobs, the interval that the jobs are triggered and the setting of -**Always Incremental Max Full Age** (Dir configuration, Job resource) +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Max Full Age}` influence the value that makes sense for -**Max Full Consolidations** (Dir configuration, Job resource). +:raw-latex:`\linkResourceDirective{Dir}{Job}{Max Full Consolidations}`. .. raw:: latex @@ -500,7 +488,7 @@ influence the value that makes sense for Jobs Available with Max Full Consolidations = 1 -.. _sec:AlwaysIncrementalLongTermStorage: +.. _sec-AlwaysIncrementalLongTermStorage: Long Term Storage of Always Incremental Jobs -------------------------------------------- @@ -511,7 +499,7 @@ store a certain job for a longer time. When using always incremental, the usual maximum age of data stored during the backup cycle is -**Always Incremental Job Retention** (Dir configuration, Job resource). +:raw-latex:`\linkResourceDirective{Dir}{Job}{Always Incremental Job Retention}`. Usually, it is desired to be able to store a certain backup for a longer time, e.g. monthly a backup should be kept for half a year. @@ -524,23 +512,22 @@ Copy Jobs The configuration of archiving via copy job is simple, just configure a copy job that copies over the latest full backup at that point in time. -As all full backups go into the **AI-Consolidated**, we +As all full backups go into the :raw-latex:`\pool{AI-Consolidated}`, we just copy all uncopied backups in the -**AI-Consolidated** to a longterm pool: +:raw-latex:`\pool{AI-Consolidated}` to a longterm pool: -.. raw:: latex +:: - \begin{bareosConfigResource}{bareos-dir}{job}{CopyLongtermFull} - Job { - Name = "CopyLongtermFull" - Schedule = LongtermFull - Type = Copy - Level = Full - Pool = AI-Consolidated - Selection Type = PoolUncopiedJobs - Messages = Standard - } - \end{bareosConfigResource} + {bareos-dir}{job}{CopyLongtermFull} + Job { + Name = "CopyLongtermFull" + Schedule = LongtermFull + Type = Copy + Level = Full + Pool = AI-Consolidated + Selection Type = PoolUncopiedJobs + Messages = Standard + } As can be seen in the plot, the copy job creates a copy of the current full backup that is available and is already 7 days old. @@ -556,38 +543,37 @@ Virtual Full Jobs The alternative to Copy Jobs is creating a virtual Full Backup Job when the data should be stored in a long-term pool. -.. raw:: latex - - \begin{bareosConfigResource}{bareos-dir}{job}{VirtualLongtermFull} - Job { - Name = "VirtualLongtermFull" - Client = bareos-fd - FileSet = SelfTest - Schedule = LongtermFull - Type = Backup - Level = VirtualFull - Pool = AI-Consolidated - Messages = Standard - - Priority = 13 # run after Consolidate - Run Script { - console = "update jobid=%i jobtype=A" - Runs When = After - Runs On Client = No - Runs On Failure = No - } - } - \end{bareosConfigResource} +:: + + {bareos-dir}{job}{VirtualLongtermFull} + Job { + Name = "VirtualLongtermFull" + Client = bareos-fd + FileSet = SelfTest + Schedule = LongtermFull + Type = Backup + Level = VirtualFull + Pool = AI-Consolidated + Messages = Standard + + Priority = 13 # run after Consolidate + Run Script { + console = "update jobid=%i jobtype=A" + Runs When = After + Runs On Client = No + Runs On Failure = No + } + } To make sure the longterm -**Level = VirtualFull** (Dir configuration, Job resource) is +:raw-latex:`\resourceDirectiveValue{Dir}{Job}{Level}{VirtualFull}` is not taken as base for the next incrementals, the job type of the copied job is set to -**Type = Archive** (Dir configuration, Job resource) with the -**Run Script** (Dir configuration, Job resource). +:raw-latex:`\resourceDirectiveValue{Dir}{Job}{Type}{Archive}` with the +:raw-latex:`\linkResourceDirective{Dir}{Job}{Run Script}`. As can be seen on the plot, the -**Level = VirtualFull** (Dir configuration, Job resource) +:raw-latex:`\resourceDirectiveValue{Dir}{Job}{Level}{VirtualFull}` archives the current data, i.e. it consolidates the full and all incrementals that are currently available. @@ -634,11 +620,10 @@ incremental backup of the remote client. Run the first backup but make sure that you choose the remote storage to be used. -.. raw:: latex +:: - \begin{bconsole}{run} - *run job=BackupClient-remote level=Full storage=File-remote - \end{bconsole} + {run} + *run job=BackupClient-remote level=Full storage=File-remote Transport the volumes that were used for that backup over to the local storage daemon and make them available to the local storage daemon. This @@ -654,35 +639,33 @@ daemon. List volumes shows that the volumes used still belong to the remote storage: -.. raw:: latex +:: - \begin{bconsole}{list volumes} - *list volumes - ..... - Pool: Full - +---------+------------+-----------+---------+----------+----------+--------------+---------+------+-----------+-----------+---------------------+-------------+ - | MediaId | VolumeName | VolStatus | Enabled | VolBytes | VolFiles | VolRetention | Recycle | Slot | InChanger | MediaType | LastWritten | Storage | - +---------+------------+-----------+---------+----------+----------+--------------+---------+------+-----------+-----------+---------------------+-------------+ - | 1 | Full-0001 | Append | 1 | 38600329 | 0 | 31536000 | 1 | 0 | 0 | File | 2016-07-28 14:00:47 | File-remote | - +---------+------------+-----------+---------+----------+----------+--------------+---------+------+-----------+-----------+---------------------+-------------+ - \end{bconsole} - -Use :command:`update volume` to set the right storage and + {list volumes} + *list volumes + ..... + Pool: Full + +---------+------------+-----------+---------+----------+----------+--------------+---------+------+-----------+-----------+---------------------+-------------+ + | MediaId | VolumeName | VolStatus | Enabled | VolBytes | VolFiles | VolRetention | Recycle | Slot | InChanger | MediaType | LastWritten | Storage | + +---------+------------+-----------+---------+----------+----------+--------------+---------+------+-----------+-----------+---------------------+-------------+ + | 1 | Full-0001 | Append | 1 | 38600329 | 0 | 31536000 | 1 | 0 | 0 | File | 2016-07-28 14:00:47 | File-remote | + +---------+------------+-----------+---------+----------+----------+--------------+---------+------+-----------+-----------+---------------------+-------------+ + +Use :raw-latex:`\bcommand{update}{volume}` to set the right storage and check with list volumes that it worked: -.. raw:: latex +:: - \begin{bconsole}{update volume} - *update volume=Full-0001 storage=File - *list volumes - ... - Pool: Full - +---------+------------+-----------+---------+----------+----------+--------------+---------+------+-----------+-----------+---------------------+---------+ - | MediaId | VolumeName | VolStatus | Enabled | VolBytes | VolFiles | VolRetention | Recycle | Slot | InChanger | MediaType | LastWritten | Storage | - +---------+------------+-----------+---------+----------+----------+--------------+---------+------+-----------+-----------+---------------------+---------+ - | 1 | Full-0001 | Append | 1 | 38600329 | 0 | 31536000 | 1 | 0 | 0 | File | 2016-07-28 14:00:47 | File | - +---------+------------+-----------+---------+----------+----------+--------------+---------+------+-----------+-----------+---------------------+---------+ - \end{bconsole} + {update volume} + *update volume=Full-0001 storage=File + *list volumes + ... + Pool: Full + +---------+------------+-----------+---------+----------+----------+--------------+---------+------+-----------+-----------+---------------------+---------+ + | MediaId | VolumeName | VolStatus | Enabled | VolBytes | VolFiles | VolRetention | Recycle | Slot | InChanger | MediaType | LastWritten | Storage | + +---------+------------+-----------+---------+----------+----------+--------------+---------+------+-----------+-----------+---------------------+---------+ + | 1 | Full-0001 | Append | 1 | 38600329 | 0 | 31536000 | 1 | 0 | 0 | File | 2016-07-28 14:00:47 | File | + +---------+------------+-----------+---------+----------+----------+--------------+---------+------+-----------+-----------+---------------------+---------+ Now the remote storage daemon can be disabled as it is not needed anymore. @@ -709,10 +692,10 @@ case to make the incremental backups possible. - Configure the Job that should backup the remote client with the fileset. -- Run :command:`estimate listing` on the remote backup +- Run :raw-latex:`\bcommand{estimate}{listing}` on the remote backup job. -- Run :command:`list filesets` to make sure the fileset +- Run :raw-latex:`\bcommand{list}{filesets}` to make sure the fileset was added to the catalog. Then we need to create a backup on the remote machine onto a portable @@ -727,7 +710,7 @@ On remote machine: - Add fileset which the client will be backed up. -- Add Pool with name **transfer** where the data will +- Add Pool with name :raw-latex:`\pool{transfer}` where the data will be written to. - create job that will backup the remote client with the remote fileset @@ -741,9 +724,9 @@ files (e.g. /var/lib/bareos/storage) Shutdown Director on local director machine. -Import data form volume via :command:`bscan`, you need to +Import data form volume via :raw-latex:`\command{bscan}`, you need to set which database backend is used: -:command:`bscan -B sqlite3 FileStorage -V Transfer-0001 -s -S` +:raw-latex:`\command{bscan -B sqlite3 FileStorage -V Transfer-0001 -s -S}` If the import was successfully completed, test if an incremental job really only backs up the minimum amount of data. diff --git a/docs/manuals/en/new_main_reference/source/autochangers.rst b/docs/manuals/en/new_main_reference/source/autochangers.rst index 19379aa670b..11506133dd3 100644 --- a/docs/manuals/en/new_main_reference/source/autochangers.rst +++ b/docs/manuals/en/new_main_reference/source/autochangers.rst @@ -1,31 +1,29 @@ +.. _AutochangersChapter: + Autochanger Support =================== - -.. index:: - triple: General; Support; Autochanger - -.. index:: - triple: General; Autochanger; Support +:raw-latex:`\index[general]{Support!Autochanger}` +:raw-latex:`\index[general]{Autochanger!Support}` Bareos provides autochanger support for reading and writing tapes. In order to work with an autochanger, Bareos requires a number of things, each of which is explained in more detail after this list: -- The package **bareos-storage-tape** must be +- The package :raw-latex:`\package{bareos-storage-tape}` must be installed. - A script that actually controls the autochanger according to commands sent by Bareos. Bareos contains the script - :command:`mtx-changer`, that utilize the command - :command:`mtx`. It’s config file is normally located at - */etc/bareos/mtx-changer.conf* + :raw-latex:`\command{mtx-changer}`, that utilize the command + :raw-latex:`\command{mtx}`. It’s config file is normally located at + :raw-latex:`\file{/etc/bareos/mtx-changer.conf}` - That each Volume (tape) to be used must be defined in the Catalog and have a Slot number assigned to it so that Bareos knows where the Volume is in the autochanger. This is generally done with the - :command:`label ` command, but can also done after the - tape is labeled using the :command:`update slots` + :raw-latex:`\bcommand{label}{}` command, but can also done after the + tape is labeled using the :raw-latex:`\bcommand{update}{slots}` command. See below for more details. You must pre-label the tapes manually before using them. @@ -35,27 +33,27 @@ each of which is explained in more detail after this list: - You need to ensure that your Storage daemon has access permissions to both the tape drive and the control device. On Linux, the system user - **bareos** is added to the groups - **disk}` and :raw-latex:`\group{tape**, so that it + :raw-latex:`\user{bareos}` is added to the groups + :raw-latex:`\group{disk}` and :raw-latex:`\group{tape}`, so that it should have the permission to access the library. - Set - Auto Changer = yes (Dir configuration, Storage resource). + :raw-latex:`\linkResourceDirectiveValue{Dir}{Storage}{Auto Changer}{yes}`. -Bareos uses its own :command:`mtx-changer` script to +Bareos uses its own :raw-latex:`\command{mtx-changer}` script to interface with a program that actually does the tape changing. Thus in -principle, :command:`mtx-changer` can be adapted to function +principle, :raw-latex:`\command{mtx-changer}` can be adapted to function with any autochanger program, or you can call any other script or -program. The current version of :command:`mtx-changer` works -with the :command:`mtx` program. FreeBSD users might need to -adapt this script to use :command:`chio`. For more details, +program. The current version of :raw-latex:`\command{mtx-changer}` works +with the :raw-latex:`\command{mtx}` program. FreeBSD users might need to +adapt this script to use :raw-latex:`\command{chio}`. For more details, refer to the -:ref:`Testing Autochanger AutochangerTesting` chapter. +:raw-latex:`\ilink{Testing Autochanger}{AutochangerTesting}` chapter. Bareos also supports autochangers with barcode readers. This support -includes two Console commands: :command:`label barcodes` -and :command:`update slots`. For more details on these -commands, see the chapter about :ref:`Barcodes`. +includes two Console commands: :raw-latex:`\bcommand{label}{barcodes}` +and :raw-latex:`\bcommand{update}{slots}`. For more details on these +commands, see the chapter about :raw-latex:`\nameref{Barcodes}`. Current Bareos autochanger support does not include cleaning, stackers, or silos. Stackers and silos are not supported because Bareos expects to @@ -64,16 +62,16 @@ to setup Bareos to access the Volumes in the autochanger sequentially, you may be able to make Bareos work with stackers (gravity feed and such). -In principle, if :command:`mtx` will operate your changer +In principle, if :raw-latex:`\command{mtx}` will operate your changer correctly, then it is just a question of adapting the -:command:`mtx-changer` script (or selecting one already +:raw-latex:`\command{mtx-changer}` script (or selecting one already adapted) for proper interfacing. If you are having troubles, please use the **auto** command in the -:command:`btape` program to test the functioning of your +:raw-latex:`\command{btape}` program to test the functioning of your autochanger with Bareos. Please remember, that on most distributions, -the |bareosSd| runs as user **bareos** and -not as **root**. You will need to ensure that the +the |bareosSd| runs as user :raw-latex:`\user{bareos}` and +not as :raw-latex:`\user{root}`. You will need to ensure that the Storage daemon has sufficient permissions to access the autochanger. Some users have reported that the the Storage daemon blocks under @@ -85,43 +83,49 @@ time (up to 7 minutes on a slow drive) waiting for the cassette to rewind and to unload before the drive can be used with a different Volume. +.. _SCSI devices: + Knowing What SCSI Devices You Have ---------------------------------- -.. index:: General; SCSI devices - -.. index:: - triple: General; Devices; SCSI - -.. index:: - triple: General; Devices; Detecting +:raw-latex:`\index[general]{SCSI devices}` +:raw-latex:`\index[general]{Devices!SCSI}` +:raw-latex:`\index[general]{Devices!Detecting}` Linux ~~~~~ Under Linux, you can +.. raw:: latex + \footnotesize :: cat /proc/scsi/scsi +.. raw:: latex + \normalsize to see what SCSI devices you have available. You can also: +.. raw:: latex + \footnotesize :: cat /proc/scsi/sg/device_hdr /proc/scsi/sg/devices +.. raw:: latex + \normalsize to find out how to specify their control address (**/dev/sg0** for the first, **/dev/sg1** for the second, ...) on the -Changer Device +:raw-latex:`\linkResourceDirective{Sd}{Autochanger}{Changer Device}` Bareos directive. You can also use the excellent **lsscsi** tool. @@ -136,32 +140,38 @@ You can also use the excellent **lsscsi** tool. [3:0:0:0] enclosu HP A6255A HP04 - /dev/sg3 [3:0:1:0] disk HP 36.4G ST336753FC HP00 /dev/sdd /dev/sg4 +.. raw:: latex + \normalsize FreeBSD ~~~~~~~ Under FreeBSD, use the following command to list the SCSI devices as -well as the */dev/passN* +well as the :raw-latex:`\path`\|/dev/passN\| that you will use on the Bareos -Changer Device +:raw-latex:`\linkResourceDirective{Sd}{Autochanger}{Changer Device}` directive: +.. raw:: latex + \footnotesize :: camcontrol devlist +.. raw:: latex + \normalsize Please check that your Storage daemon has permission to access this device. The following tip for FreeBSD users comes from Danny Butroyd: on reboot Bareos will NOT have permission to control the device -*/dev/pass0* (assuming this is your changer device). -To get around this just edit the */etc/devfs.conf* +:raw-latex:`\file{/dev/pass0}` (assuming this is your changer device). +To get around this just edit the :raw-latex:`\file{/etc/devfs.conf}` file and add the following to the bottom: :: @@ -171,17 +181,18 @@ file and add the following to the bottom: own nsa0.0 root:bareos perm nsa0.0 0666 +.. raw:: latex + \normalsize This gives the bareos group permission to write to the nsa0.0 device too just to be on the safe side. To bring these changes into effect just run:- -.. raw:: latex +:: - \begin{commands}{} - /etc/rc.d/devfs restart - \end{commands} + {} + /etc/rc.d/devfs restart Basically this will stop you having to manually change permissions on these devices to make Bareos work when operating the AutoChanger after a @@ -191,12 +202,12 @@ Solaris ~~~~~~~ On Solaris, the changer device will typically be some file under -*/dev/rdsk*. +:raw-latex:`\file{/dev/rdsk}`. Slots ----- -.. index:: General; Slots}` :raw-latex:`\label{Slots +:raw-latex:`\index[general]{Slots}` :raw-latex:`\label{Slots}` To properly address autochangers, Bareos must know which Volume is in each **slot** of the autochanger. Slots are where the changer cartridges @@ -211,31 +222,30 @@ will, using the Console program, assign a slot. This information is kept in Bareos’s catalog database along with the other data for the volume. If no slot is given, or the slot is set to zero, Bareos will not attempt to use the autochanger even if all the necessary configuration records -are present. When doing a :command:`mount ` command on an +are present. When doing a :raw-latex:`\bcommand{mount}{}` command on an autochanger, you must specify which slot you want mounted. If the drive is loaded with a tape from another slot, it will unload it and load the correct tape, but normally, no tape will be loaded because an -:command:`unmount ` command causes Bareos to unload the +:raw-latex:`\bcommand{unmount}{}` command causes Bareos to unload the tape in the drive. You can check if the Slot number and InChanger flag by: -.. raw:: latex +:: - \begin{bconsole}{list volumes} - *list volumes - \end{bconsole} + {list volumes} + *list volumes + +.. _sec-MultipleDevices: Multiple Devices ---------------- - -.. index:: - triple: General; Devices; Multiple -.. index:: General; Multiple Devices +:raw-latex:`\index[general]{Devices!Multiple}` +:raw-latex:`\index[general]{Multiple Devices}` Some autochangers have more than one read/write device (drive). The -:ref:`Autochanger resource AutochangerRes` permits you to +:raw-latex:`\ilink{Autochanger resource}{AutochangerRes}` permits you to group Device resources, where each device represents a drive. The Director may still reference the Devices (drives) directly, but doing so, bypasses the proper functioning of the drives together. Instead, the @@ -245,50 +255,46 @@ one drive uses the mtx-changer script at a time, and also that two drives don’t reference the same Volume. Multi-drive requires the use of the -Drive Index directive. +:raw-latex:`\linkResourceDirective{Sd}{Device}{Drive Index}` directive. Drive numbers or the Device Index are numbered beginning at zero, which is the default. To use the second Drive in an autochanger, you need to define a second Device resource, set the -Drive Index and set the -Archive Device. +:raw-latex:`\linkResourceDirective{Sd}{Device}{Drive Index}` and set the +:raw-latex:`\linkResourceDirective{Sd}{Device}{Archive Device}`. As a default, Bareos jobs will prefer to write to a Volume that is already mounted. If you have a multiple drive autochanger and you want Bareos to write to more than one Volume in the same Pool at the same time, you will need to set -Prefer Mounted Volumes = no (Dir configuration, Job resource). +:raw-latex:`\linkResourceDirectiveValue{Dir}{Job}{Prefer Mounted Volumes}{no}`. This will cause the Storage daemon to maximize the use of drives. Device Configuration Records ---------------------------- -.. index:: General; Device Configuration Records +:raw-latex:`\index[general]{Device Configuration Records}` Configuration of autochangers within Bareos is done in the Device resource of the Storage daemon. Following records control how Bareos uses the autochanger: -Autochanger +:raw-latex:`\linkResourceDirective{Sd}{Device}{Autochanger}` Specifies if the current device belongs to an autochanger resource. -Changer Command -(Changer Command) -Changer Device -(Changer Device) -Drive Index +:raw-latex:`\linkResourceDirective{Sd}{Autochanger}{Changer Command}` (:raw-latex:`\linkResourceDirective{Sd}{Device}{Changer Command}`) +:raw-latex:`\linkResourceDirective{Sd}{Autochanger}{Changer Device}` (:raw-latex:`\linkResourceDirective{Sd}{Device}{Changer Device}`) +:raw-latex:`\linkResourceDirective{Sd}{Device}{Drive Index}` Individual driver number, starting at 0. -Maximum Changer Wait +:raw-latex:`\linkResourceDirective{Sd}{Device}{Maximum Changer Wait}` Specifying Slots When Labeling ------------------------------ -.. index:: General; Specifying Slots When Labeling - -.. index:: - triple: General; Label; Specifying Slots When Labeling -.. _SpecifyingSlots: +:raw-latex:`\index[general]{Specifying Slots When Labeling}` +:raw-latex:`\index[general]{Label!Specifying Slots When Labeling}` +:raw-latex:`\label{SpecifyingSlots}` If you add an **Autochanger = yes** record to the Storage resource in your Director’s configuration file, the Bareos Console will @@ -300,8 +306,8 @@ automatically load the correct tape during the label command. You must also set **Autochanger = yes** in the Storage daemon’s Device resource as we have described above in order for the autochanger to be used. Please see -Auto Changer and -Autochanger for more +:raw-latex:`\linkResourceDirective{Dir}{Storage}{Auto Changer}` and +:raw-latex:`\linkResourceDirective{Sd}{Device}{Autochanger}` for more details on these records. Thus all stages of dealing with tapes can be totally automated. It is @@ -315,14 +321,16 @@ name). If your autochanger has barcode labels, you can label all the Volumes in your autochanger one after another by using the -:command:`label barcodes` command. For each tape in the +:raw-latex:`\bcommand{label}{barcodes}` command. For each tape in the changer containing a barcode, Bareos will mount the tape and then label it with the same name as the barcode. An appropriate Media record will also be created in the catalog. Any barcode that begins with the same -characters as specified on the “CleaningPrefix=xxx” command, will be +characters as specified on the "CleaningPrefix=xxx" command, will be treated as a cleaning tape, and will not be labeled. For example with: +.. raw:: latex + \footnotesize :: @@ -331,7 +339,9 @@ treated as a cleaning tape, and will not be labeled. For example with: Cleaning Prefix = "CLN" } +.. raw:: latex + \normalsize Any slot containing a barcode of CLNxxxx will be treated as a cleaning tape and will not be mounted. @@ -339,13 +349,13 @@ tape and will not be mounted. Changing Cartridges ------------------- - -.. index:: - triple: General; Cartridges; Changing If you wish to insert +:raw-latex:`\index[general]{Cartridges!Changing}` If you wish to insert or remove cartridges in your autochanger or you manually run the **mtx** program, you must first tell Bareos to release the autochanger by doing: +.. raw:: latex + \footnotesize :: @@ -353,7 +363,9 @@ program, you must first tell Bareos to release the autochanger by doing: (change cartridges and/or run mtx) mount +.. raw:: latex + \normalsize If you do not do the unmount before making such a change, Bareos will become completely confused about what is in the autochanger and may stop @@ -363,9 +375,7 @@ while it has the drive mounted. Dealing with Multiple Magazines ------------------------------- - -.. index:: - triple: General; Magazines; Dealing with Multiple +:raw-latex:`\index[general]{Magazines!Dealing with Multiple}` If you have several magazines or if you insert or remove cartridges from a magazine, you should notify Bareos of this. By doing so, Bareos will @@ -378,7 +388,9 @@ task of informing Bareos is simple. Every time, you change a magazine, or add or remove a cartridge from the magazine, simply use following commands in the Console program: +.. raw:: latex + \footnotesize :: @@ -388,7 +400,9 @@ commands in the Console program: update slots mount +.. raw:: latex + \normalsize This will cause Bareos to request the autochanger to return the current Volume names in the magazine. This will be done without actually @@ -408,13 +422,17 @@ several alternatives. #. You can issue a - + .. raw:: latex + + \footnotesize :: update slots scan - + .. raw:: latex + + \normalsize command that will cause Bareos to read the label on each of the cartridges in the magazine in turn and update the information (Slot, @@ -422,74 +440,78 @@ several alternatives. time to load each cartridge into the drive in turn and read the Volume label. -:raw-latex:`\hide{ -% unwanted, commented out -\section{Simulating Barcodes in your Autochanger} -\index[general]{Autochanger!Simulating Barcodes in your} -\index[general]{Simulating Barcodes in your Autochanger} -\label{simulating} - -You can simulate barcodes in your autochanger by making the {\bf mtx-changer} -script return the same information that an autochanger with barcodes would do. -This is done by commenting out the one and only line in the {\bf list)} case, -which is: - -\footnotesize -\begin{verbatim} - ${MTX} -f $ctl status | grep " *Storage Element [0-9]*:.*Full" | awk "{print \$3 \$4}" | sed "s/Full *\(:VolumeTag=\)*//" -\end{verbatim} -\normalsize - -at approximately line 99 by putting a \# in column one of that line, or by -simply deleting it. Then in its place add a new line that prints the contents -of a file. For example: - -\footnotesize -\begin{verbatim} -cat /etc/bareos/changer.volumes -\end{verbatim} -\normalsize - -Be sure to include a full path to the file, which can have any name. The -contents of the file must be of the following format: - -\footnotesize -\begin{verbatim} -1:Volume1 -2:Volume2 -3:Volume3 -... -\end{verbatim} -\normalsize - -Where the 1, 2, 3 are the slot numbers and Volume1, Volume2, ... are the -Volume names in those slots. You can have multiple files that represent the -Volumes in different magazines, and when you change magazines, simply copy the -contents of the correct file into your {\bf /etc/bareos/changer.volumes} file. -There is no need to stop and start Bareos when you change magazines, simply -put the correct data in the file, then run the {\bf update slots} command, and -your autochanger will appear to Bareos to be an autochanger with barcodes. -}` +.. raw:: latex + + \hide{ + % unwanted, commented out + \section{Simulating Barcodes in your Autochanger} + \index[general]{Autochanger!Simulating Barcodes in your} + \index[general]{Simulating Barcodes in your Autochanger} + \label{simulating} + + You can simulate barcodes in your autochanger by making the {\bf mtx-changer} + script return the same information that an autochanger with barcodes would do. + This is done by commenting out the one and only line in the {\bf list)} case, + which is: + + \footnotesize + \begin{verbatim} + ${MTX} -f $ctl status | grep " *Storage Element [0-9]*:.*Full" | awk "{print \$3 \$4}" | sed "s/Full *\(:VolumeTag=\)*//" + \end{verbatim} + \normalsize + + at approximately line 99 by putting a \# in column one of that line, or by + simply deleting it. Then in its place add a new line that prints the contents + of a file. For example: + + \footnotesize + \begin{verbatim} + cat /etc/bareos/changer.volumes + \end{verbatim} + \normalsize + + Be sure to include a full path to the file, which can have any name. The + contents of the file must be of the following format: + + \footnotesize + \begin{verbatim} + 1:Volume1 + 2:Volume2 + 3:Volume3 + ... + \end{verbatim} + \normalsize + + Where the 1, 2, 3 are the slot numbers and Volume1, Volume2, ... are the + Volume names in those slots. You can have multiple files that represent the + Volumes in different magazines, and when you change magazines, simply copy the + contents of the correct file into your {\bf /etc/bareos/changer.volumes} file. + There is no need to stop and start Bareos when you change magazines, simply + put the correct data in the file, then run the {\bf update slots} command, and + your autochanger will appear to Bareos to be an autochanger with barcodes. + } Update Slots Command -------------------- - -.. index:: - triple: General; Console!Command; update slots -.. _updateslots: +:raw-latex:`\index[general]{Console!Command!update slots}` +:raw-latex:`\label{updateslots}` If you change only one cartridge in the magazine, you may not want to scan all Volumes, so the **update slots** command (as well as the **update slots scan** command) has the additional form: +.. raw:: latex + \footnotesize :: update slots=n1,n2,n3-n4, ... +.. raw:: latex + \normalsize where the keyword **scan** can be appended or not. The n1,n2, ... represent Slot numbers to be updated and the form n3-n4 represents a @@ -501,25 +523,33 @@ expensive) and restrict the update to one or two slots. For example, the command: +.. raw:: latex + \footnotesize :: update slots=1,6 scan +.. raw:: latex + \normalsize will cause Bareos to load the Volume in Slot 1, read its Volume label and update the Catalog. It will do the same for the Volume in Slot 6. The command: +.. raw:: latex + \footnotesize :: update slots=1-3,6 +.. raw:: latex + \normalsize will read the barcoded Volume names for slots 1,2,3 and 6 and make the appropriate updates in the Catalog. If you don’t have a barcode reader @@ -528,10 +558,8 @@ the above command will not find any Volume names so will do nothing. Using the Autochanger --------------------- - -.. index:: - triple: General; Autochanger; Using the -.. _using: +:raw-latex:`\index[general]{Autochanger!Using the}` +:raw-latex:`\label{using}` Let’s assume that you have properly defined the necessary Storage daemon Device records, and you have added the **Autochanger = yes** record to @@ -544,7 +572,9 @@ What do you do to make Bareos access those tapes? One strategy is to prelabel each of the tapes. Do so by starting Bareos, then with the Console program, enter the **label** command: +.. raw:: latex + \footnotesize :: @@ -553,11 +583,15 @@ then with the Console program, enter the **label** command: 1000 OK: rufus-dir Version: 1.26 (4 October 2002) *label +.. raw:: latex + \normalsize it will then print something like: +.. raw:: latex + \footnotesize :: @@ -567,23 +601,31 @@ it will then print something like: 2: File Select Storage resource (1-2): 1 +.. raw:: latex + \normalsize I select the autochanger (1), and it prints: +.. raw:: latex + \footnotesize :: Enter new Volume name: TestVolume1 Enter slot (0 for none): 1 +.. raw:: latex + \normalsize where I entered **TestVolume1** for the tape name, and slot **1** for the slot. It then asks: +.. raw:: latex + \footnotesize :: @@ -592,14 +634,18 @@ the slot. It then asks: 2: File Select the Pool (1-2): 1 +.. raw:: latex + \normalsize I select the Default pool. This will be automatically done if you only have a single pool, then Bareos will proceed to unload any loaded volume, load the volume in slot 1 and label it. In this example, nothing was in the drive, so it printed: +.. raw:: latex + \footnotesize :: @@ -613,7 +659,9 @@ was in the drive, so it printed: You have messages. * +.. raw:: latex + \normalsize You may then proceed to label the other volumes. The messages will change slightly because Bareos will unload the volume (just labeled @@ -622,11 +670,13 @@ TestVolume1) before loading the next volume to be labeled. Once all your Volumes are labeled, Bareos will automatically load them as they are needed. -To “see” how you have labeled your Volumes, simply enter the **list +To "see" how you have labeled your Volumes, simply enter the **list volumes** command from the Console program, which should print something like the following: +.. raw:: latex + \footnotesize :: @@ -645,16 +695,16 @@ like the following: | ... | +-------+----------+--------+---------+-------+--------+----------+-------+------+ +.. raw:: latex + \normalsize Barcode Support --------------- - -.. index:: - triple: General; Support; Barcode -.. index:: General; Barcode Support -.. _Barcodes: +:raw-latex:`\index[general]{Support!Barcode}` +:raw-latex:`\index[general]{Barcode Support}` +:raw-latex:`\label{Barcodes}` Bareos provides barcode support with two Console commands, **label barcodes** and **update slots**. @@ -684,7 +734,9 @@ Use bconsole to display Autochanger content The **status slots storage=xxx** command displays autochanger content. +.. raw:: latex + \footnotesize :: @@ -695,7 +747,9 @@ The **status slots storage=xxx** command displays autochanger content. 3*| 00003 | Append | DiskChangerMedia | Scratch | 0 | 4 | | | | | 0 | +.. raw:: latex + \normalsize If you see a **** near the slot number, you have to run **update slots** command to synchronize autochanger content with your catalog. @@ -703,10 +757,8 @@ command to synchronize autochanger content with your catalog. Bareos Autochanger Interface ---------------------------- - -.. index:: - triple: General; Autochanger; Interface -.. _autochanger-interface: +:raw-latex:`\index[general]{Autochanger!Interface}` +:raw-latex:`\label{autochanger-interface}` Bareos calls the autochanger script that you specify on the **Changer Command** statement. Normally this script will be the **mtx-changer** @@ -716,7 +768,9 @@ Bareos uses, which are **loaded**, **load**, **unload**, **list**, and **slots**. In addition, each of those commands must return the information in the precise format as specified below: +.. raw:: latex + \footnotesize :: @@ -736,7 +790,9 @@ information in the precise format as specified below: field is blank. slots -- returns total number of slots in the autochanger. +.. raw:: latex + \normalsize Bareos checks the exit status of the program called, and if it is zero, the data is accepted. If the exit status is non-zero, Bareos will print @@ -745,33 +801,25 @@ an error message and request the tape be manually mounted on the drive. Tapespeed and blocksizes ------------------------ +:raw-latex:`\index[general]{Tuning!Tape}` +:raw-latex:`\index[general]{Tuning!blocksize}` +:raw-latex:`\index[general]{Tape!speed}` +:raw-latex:`\index[general]{Blocksize!optimize}` +:raw-latex:`\label{Tapespeed and blocksizes}` +:raw-latex:`\label{setblocksizes}` -.. index:: - triple: General; Tuning; Tape - -.. index:: - triple: General; Tuning; blocksize - -.. index:: - triple: General; Tape; speed - -.. index:: - triple: General; Blocksize; optimize -.. _Tapespeed and blocksizes: -.. _setblocksizes: - -The :raw-latex:`\bareosWhitepaperTapeSpeedTuning`shows that the two +The :raw-latex:`\bareosWhitepaperTapeSpeedTuning `shows that the two parameters :raw-latex:`\configdirective{Maximum File Size}` and :raw-latex:`\configdirective{Maximum Block Size}` of the device have significant influence on the tape speed. While it is no problem to change the -Maximum File Size +:raw-latex:`\linkResourceDirective{Sd}{Device}{Maximum File Size}` parameter, unfortunately it is not possible to change the -Maximum Block Size +:raw-latex:`\linkResourceDirective{Sd}{Device}{Maximum Block Size}` parameter, because the previously written tapes would become unreadable in the new setup. It would require that the -Maximum Block Size +:raw-latex:`\linkResourceDirective{Sd}{Device}{Maximum Block Size}` parameter is switched back to the old value to be able to read the old volumes, but of course then the new volumes would be unreadable. @@ -779,7 +827,7 @@ Why is that the case? The problem is that Bareos writes the label block (header) in the same block size that is configured in the -Maximum Block Size +:raw-latex:`\linkResourceDirective{Sd}{Device}{Maximum Block Size}` parameter in the device. Per default, this value is 63k, so usually a tape written by Bareos looks like this: @@ -822,7 +870,7 @@ label, this security mechanism does not work and you might label tapes already labeled accidentally. To solve this problem, the block size handling was changed in Bareos -14.2.0 in the +:raw-latex:`\sinceVersion{sd}{Maximum Block Size}{14.2.0}` in the following way: - The tape label block is always written in the standard 63k (64512) @@ -833,9 +881,9 @@ following way: - To be able to change the block size in an existing environment, it is now possible to set the - Maximum Block Size + :raw-latex:`\linkResourceDirective{Dir}{Pool}{Maximum Block Size}` and - Minimum Block Size in + :raw-latex:`\linkResourceDirective{Dir}{Pool}{Minimum Block Size}` in the pool resource. This setting is automatically promoted to each medium in that pool as usual (i.e. when a medium is labeled for that pool or if a volume is transferred to that pool from the scratch @@ -867,23 +915,21 @@ This approach has the following advantages: - If you want to switch an existing installation that uses the default block size and move to a new (usually bigger) block size, you can do that easily by creating a new pool, where - Maximum Block Size is + :raw-latex:`\linkResourceDirective{Dir}{Pool}{Maximum Block Size}` is set to the new value that you wish to use in the future: -.. raw:: latex - - \begin{bconfig}{Pool Ressource: setting Maximum Block Size} - Pool { - Name = LTO-4-1M - Pool Type = Backup - Recycle = yes # Bareos can automatically recycle Volumes - AutoPrune = yes # Prune expired volumes - Volume Retention = 1 Month # How long should the Full Backups be kept? (#06) - Maximum Block Size = 1048576 - Recycle Pool = Scratch - } +:: - \end{bconfig} + {Pool Ressource: setting Maximum Block Size} + Pool { + Name = LTO-4-1M + Pool Type = Backup + Recycle = yes # Bareos can automatically recycle Volumes + AutoPrune = yes # Prune expired volumes + Volume Retention = 1 Month # How long should the Full Backups be kept? (#06) + Maximum Block Size = 1048576 + Recycle Pool = Scratch + } Now configure your backups that they will write into the newly defined pool in the future, and your backups will be written with the new block @@ -891,13 +937,13 @@ size. Your existing tapes can be automatically transferred to the new pool when they expire via the -:ref:`Scratch Pool TheScratchPool` mechanism. When a tape +:raw-latex:`\ilink{Scratch Pool}{TheScratchPool}` mechanism. When a tape in your old pool expires, it is transferred to the scratch pool if you set **Recycle Pool = Scratch**. When your new pool needs a new volume, it will get it from the scratch pool and apply the new pool’s properties to that tape which also include -Maximum Block Size and -Minimum Block Size. +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Maximum Block Size}` and +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Minimum Block Size}`. This way you can smoothly switch your tapes to a new block size while you can still restore the data on your old tapes at any time. @@ -911,7 +957,7 @@ As we now defined the label block to always be 63k, all labels will not be readable. To also solve this problem, the directive -Label Block Size can be +:raw-latex:`\linkResourceDirective{Sd}{Device}{Label Block Size}` can be used to define a different label block size. That way, everything should work smoothly as all label blocks will be readable again. @@ -928,102 +974,92 @@ following in your system’s messages: Here, the block was written with 1M block size but we only read 64k. +.. _direct-access-to-volumes-with-non-default-blocksizes: + Direct access to Volumes with with non-default block sizes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:raw-latex:`\index[general]{bls!block size}` +:raw-latex:`\index[general]{bextract!block size}` +:raw-latex:`\index[general]{Command!bls!block size}` +:raw-latex:`\index[general]{Command!bextract!block size}` -.. index:: - triple: General; bls; block size - -.. index:: - triple: General; bextract; block size - -.. index:: - triple: General; Command!bls; block size - -.. index:: - triple: General; Command!bextract; block size - -:command:`bls}` and :raw-latex:`\command{bextract` can +:raw-latex:`\command{bls}` and :raw-latex:`\command{bextract}` can directly access Bareos volumes without catalog database. This means that these programs don’t have information about the used block size. To be able to read a volume written with an arbitrary block size, you need to set the -Label Block Size (to be +:raw-latex:`\linkResourceDirective{Sd}{Device}{Label Block Size}` (to be able to to read the label block) and the -Maximum Block Size (to +:raw-latex:`\linkResourceDirective{Sd}{Device}{Maximum Block Size}` (to be able to read the data blocks) setting in the device definition used by those tools to be able to open the medium. -Example using :command:`bls` with a tape that was written +Example using :raw-latex:`\command{bls}` with a tape that was written with another blocksize than the -**DEFAULT_BLOCK_SIZE** (63k), but with the default +:raw-latex:`\variable{DEFAULT_BLOCK_SIZE}` (63k), but with the default label block size of 63k: -.. raw:: latex +:: - \begin{commands}{bls with non-default block size} - bls FC-Drive-1 -V A00007L4 - bls: butil.c:289-0 Using device: "FC-Drive-1" for reading. - 25-Feb 12:47 bls JobId 0: No slot defined in catalog (slot=0) for Volume "A00007L4" on "FC-Drive-1" (/dev/tape/by-id/scsi-350011d00018a5f03-nst). - 25-Feb 12:47 bls JobId 0: Cartridge change or "update slots" may be required. - 25-Feb 12:47 bls JobId 0: Ready to read from volume "A00007L4" on device "FC-Drive-1" (/dev/tape/by-id/scsi-350011d00018a5f03-nst). - 25-Feb 12:47 bls JobId 0: Error: block.c:1004 Read error on fd=3 at file:blk 0:1 on device "FC-Drive-1" (/dev/tape/by-id/scsi-350011d00018a5f03-nst). ERR=Cannot allocate memory. - Bareos status: file=0 block=1 - Device status: ONLINE IM_REP_EN file=0 block=2 - 0 files found. - \end{commands} - -As can be seen, :command:`bls` manages to read the label + {bls with non-default block size} + bls FC-Drive-1 -V A00007L4 + bls: butil.c:289-0 Using device: "FC-Drive-1" for reading. + 25-Feb 12:47 bls JobId 0: No slot defined in catalog (slot=0) for Volume "A00007L4" on "FC-Drive-1" (/dev/tape/by-id/scsi-350011d00018a5f03-nst). + 25-Feb 12:47 bls JobId 0: Cartridge change or "update slots" may be required. + 25-Feb 12:47 bls JobId 0: Ready to read from volume "A00007L4" on device "FC-Drive-1" (/dev/tape/by-id/scsi-350011d00018a5f03-nst). + 25-Feb 12:47 bls JobId 0: Error: block.c:1004 Read error on fd=3 at file:blk 0:1 on device "FC-Drive-1" (/dev/tape/by-id/scsi-350011d00018a5f03-nst). ERR=Cannot allocate memory. + Bareos status: file=0 block=1 + Device status: ONLINE IM_REP_EN file=0 block=2 + 0 files found. + +As can be seen, :raw-latex:`\command{bls}` manages to read the label block as it knows what volume is mounted (Ready to read from volume -**A00007L4**), but fails to read the data blocks. +:raw-latex:`\parameter{A00007L4}`), but fails to read the data blocks. -.. raw:: latex +:: - \begin{commands}{dmesg} - dmesg - [...] - st2: Failed to read 131072 byte block with 64512 byte transfer. - [...] - \end{commands} + {dmesg} + dmesg + [...] + st2: Failed to read 131072 byte block with 64512 byte transfer. + [...] This shows that the block size for the data blocks that we need is 131072. Now we have to set this block size in the -*bareos-sd.conf*, device resource as -Maximum Block Size: +:raw-latex:`\file{bareos-sd.conf}`, device resource as +:raw-latex:`\linkResourceDirective{Sd}{Device}{Maximum Block Size}`: -.. raw:: latex +:: - \begin{bconfig}{Storage Device Resource: setting Maximum Block Size} - Device { - Name = FC-Drive-1 - Drive Index = 0 - Media Type = LTO-4 - Archive Device = /dev/tape/by-id/scsi-350011d00018a5f03-nst - AutomaticMount = yes - AlwaysOpen = yes - RemovableMedia = yes - RandomAccess = no - AutoChanger = yes - Maximum Block Size = 131072 - } - \end{bconfig} + {Storage Device Resource: setting Maximum Block Size} + Device { + Name = FC-Drive-1 + Drive Index = 0 + Media Type = LTO-4 + Archive Device = /dev/tape/by-id/scsi-350011d00018a5f03-nst + AutomaticMount = yes + AlwaysOpen = yes + RemovableMedia = yes + RandomAccess = no + AutoChanger = yes + Maximum Block Size = 131072 + } Now we can call bls again, and everything works as expected: -.. raw:: latex +:: - \begin{commands}{bls with non-default block size} - bls FC-Drive-1 -V A00007L4 - bls: butil.c:289-0 Using device: "FC-Drive-1" for reading. - 25-Feb 12:49 bls JobId 0: No slot defined in catalog (slot=0) for Volume "A00007L4" on "FC-Drive-1" (/dev/tape/by-id/scsi-350011d00018a5f03-nst). - 25-Feb 12:49 bls JobId 0: Cartridge change or "update slots" may be required. - 25-Feb 12:49 bls JobId 0: Ready to read from volume "A00007L4" on device "FC-Drive-1" (/dev/tape/by-id/scsi-350011d00018a5f03-nst). - bls JobId 203: [...] - \end{commands} + {bls with non-default block size} + bls FC-Drive-1 -V A00007L4 + bls: butil.c:289-0 Using device: "FC-Drive-1" for reading. + 25-Feb 12:49 bls JobId 0: No slot defined in catalog (slot=0) for Volume "A00007L4" on "FC-Drive-1" (/dev/tape/by-id/scsi-350011d00018a5f03-nst). + 25-Feb 12:49 bls JobId 0: Cartridge change or "update slots" may be required. + 25-Feb 12:49 bls JobId 0: Ready to read from volume "A00007L4" on device "FC-Drive-1" (/dev/tape/by-id/scsi-350011d00018a5f03-nst). + bls JobId 203: [...] How to configure the block sizes in your environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1044,7 +1080,7 @@ currently not used. However, by default Bareos keeps tapes in the drives, in case the same tape is required again. The directive -Cleaning Prefix is only +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Cleaning Prefix}` is only used for making sure that Bareos does not try to write backups on a cleaning tape. @@ -1053,29 +1089,28 @@ the drives, it’s probably best to set up an admin job that removes the tapes from the drives. This job has to run, when no other backups do run. A job definition for an admin job to do that may look like this: -.. raw:: latex +:: - \begin{bareosConfigResource}{bareos-dir}{job}{ReleaseAllTapeDrives} - Job { - Name = ReleaseAllTapeDrives - JobDefs = DefaultJob - Schedule = "WeeklyCycleAfterBackup" - Type = Admin - Priority = 200 - - RunScript { - Runs When = Before - Runs On Client = no - Console = "release storage=Tape alldrives" - } - } - \end{bareosConfigResource} + {bareos-dir}{job}{ReleaseAllTapeDrives} + Job { + Name = ReleaseAllTapeDrives + JobDefs = DefaultJob + Schedule = "WeeklyCycleAfterBackup" + Type = Admin + Priority = 200 + + RunScript { + Runs When = Before + Runs On Client = no + Console = "release storage=Tape alldrives" + } + } Replace :raw-latex:`\resourcename{Dir}{Storage}{Tape}` by the storage name of your tape library. Use the highest -Priority value to make +:raw-latex:`\linkResourceDirective{Dir}{Job}{Priority}` value to make sure no other jobs are running. In the default configuration for -example, the **CatalogBackup** job has Priority = 100. +example, the :raw-latex:`\job{CatalogBackup}` job has Priority = 100. The higher the number, the lower the job priority. .. |image| image:: \idir blocksize-decisionchart diff --git a/docs/manuals/en/new_main_reference/source/backward-compatibility.rst b/docs/manuals/en/new_main_reference/source/backward-compatibility.rst deleted file mode 100644 index a7459c6e2bf..00000000000 --- a/docs/manuals/en/new_main_reference/source/backward-compatibility.rst +++ /dev/null @@ -1,219 +0,0 @@ -Backward Compatibility -====================== - - -.. index:: - triple: General; Compatibility; Backward -.. _backward-compability: - -Tape Formats ------------- - - -.. index:: - triple: General; Tape; Format -.. _backward-compability-tape-format: - -One of the major goals of Backup softare is to ensure that you can -restore tapes (the word tape should also include disk volumes) that you -wrote years ago. This means that each new version of the software should -be able to read old format tapes. The first problem you will have is to -ensure that the hardware is still working some years down the road, and -the second problem will be to ensure that the media will still be good, -then your OS must be able to interface to the device, and finally Bareos -must be able to recognize old formats. All the problems except the last -are ones that we cannot solve, but by careful planning you can. - -Since the very beginning of Bacula (January 2000) until today (2015), -there have been three major Bacula/Bareos tape formats. The second -format was introduced in Bacula version 1.27 in November of 2002. Bareos -has been required to adapt the tape format to avoid potential trademark -issues, but is able to read also the old Bacula tape formats. - -Though the tape format is basically fixed, the kinds of data that we can -put on the tapes are extensible, and that is how we added new features -such as ACLs, Win32 data, encrypted data, ... Obviously, an older -version of Bacula/Bareos would not know how to read these newer data -streams, but each newer version of Bareos should know how to read all -the older streams. - -Compatibility between Bareos and Bacula ---------------------------------------- - - -.. index:: - triple: General; Compatibility; Bacula -.. index:: General; Bacula}` :raw-latex:`\label{compat-bacula - -A Director and a Storage Daemon should (must) always run at the same -version. This is true for Bareos as well as for Bacula. It is not -possible to mix these components. This is because the protocol between -Director and Storage Daemon itself is not versioned (also true for -Bareos and Bacula). If you want to be able to switch back from Bareos to -Bacula after using a Bareos director and storage daemon you have to -enable the compatible mode in the Bareos storage daemon to have it write -the data in the same format as the Bacula storage daemon. - -The |bareosFd| is compatible with all version of the Bacula -director (tested with version 5.2.13 and lower) when you enable the -compatible mode in the configuration of the |bareosFd| . The -compatible option was set by default in Bareos :math:`<` 15.2.0, and is -disabled by default since -15.2.0. - -To be sure this is enabled you can explicitly set the compatible option: - -Compatible = True (Fd configuration, Client resource) - -A |bareosDir| can only talk to Bacula file daemons of version -2.0 or higher. Through a change in the Bacula network protocols, it is -currently not possible to use a Bacula file daemon :math:`\ge` 6.0 with -a |bareosDir| . - -These combinations of Bareos and Bacula are know to work together: - -+-------------------------------------------+-------------------------------------------+--------------------------------------------------------------------------+---------------+ -| **Director** | **Storage Daemon** | **File Daemon** | **Remarks** | -+===========================================+===========================================+==========================================================================+===============+ -| :raw-latex:`\textcolor{blue}{Bareos\ }` | :raw-latex:`\textcolor{blue}{Bareos\ }` | :raw-latex:`\textcolor{blue}{Bareos\ }` | | -+-------------------------------------------+-------------------------------------------+--------------------------------------------------------------------------+---------------+ -| :raw-latex:`\textcolor{blue}{Bareos\ }` | :raw-latex:`\textcolor{blue}{Bareos\ }` | 2.0 :math:`\leq` :raw-latex:`\textcolor{red}{Bacula\ }`\ :math:`<` 6.0 | | -+-------------------------------------------+-------------------------------------------+--------------------------------------------------------------------------+---------------+ -| :raw-latex:`\textcolor{red}{Bacula\ }` | :raw-latex:`\textcolor{red}{Bacula\ }` | :raw-latex:`\textcolor{red}{Bacula\ }` | | -+-------------------------------------------+-------------------------------------------+--------------------------------------------------------------------------+---------------+ -| :raw-latex:`\textcolor{red}{Bacula\ }` | :raw-latex:`\textcolor{red}{Bacula\ }` | :raw-latex:`\textcolor{blue}{Bareos\ }`(compatibility mode) | | -+-------------------------------------------+-------------------------------------------+--------------------------------------------------------------------------+---------------+ - -Other combinations like Bacula Director with |bareosSd| will -not work. However this wasn’t even possible with different versions of -bacula-dir and bacula-sd. - -Upgrade from Bacula 5.2 to Bareos -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. index:: General; Upgrade from Bacula to Bareos - -.. index:: - triple: General; Bareos; Upgrading -.. _upgrade-from-bacula-to-bareos: - -Upgrade is supported from Bacula version 5.2.x. If you are running any -older version of Bacula, please update to 5.2 first (see Bacula -documentation). - - -.. warning:: - Updating from Bacula $\geq$ 7.0 to Bareos has not been tested. - -:raw-latex:`\warning{As Bareos and Bacula packages bring binaries with identical paths and names, -it is on most platforms not possible to install components from both in parallel. -Your package management tool will warn you about this.}` - -Rename user and group before upgrading -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To have bareos running without any permission hassle, it is recommended -to rename the user and group **bacula** to the user and -group **bareos** before upgrading. That way, we minimize -the effort for the user to recheck all config files and the rights on -every script/directory etc. involved in the existing setup. - -The required commands should look something like this: - -.. raw:: latex - - \begin{commands}{} - usermod -l bareos bacula - groupmod -n bareos bacula - \end{commands} - -MySQL -^^^^^ - -Proceed with the following steps: - -- Stop bacula services - -- Backup your catalog database: - - .. raw:: latex - - \begin{commands}{} - mysqldump bacula > /tmp/bacula_5.2.sql - \end{commands} - -- Make the user bareos have the same userid and the group bareos the - same groupid as the user/group bacula had before. This will solve a - lot of rights problems. - -- Install Bareos packages - -- Run the update script on the old bacula database: - - .. raw:: latex - - \begin{commands}{} - export db_name=bacula - /usr/lib/bareos/update_bareos_tables - unset db_name - \end{commands} - -- Backup upgraded DB: - - .. raw:: latex - - \begin{commands}{} - mysqldump bacula > /tmp/bacula.sql - \end{commands} - -- Create bareos database: - - .. raw:: latex - - \begin{commands}{} - /usr/lib/bareos/create_bareos_database - \end{commands} - -- Insert backuped db into new database: - - .. raw:: latex - - \begin{commands}{} - cat /tmp/bacula.sql | mysql bareos - \end{commands} - -- Grant permissions: - - .. raw:: latex - - \begin{commands}{} - /usr/lib/bareos/grant_mysql_privileges - \end{commands} - -- Adapt file permissions to bareos, if you have any file storage - -- Adapt configs (not complete) - - - With bacula the default setting for pid files was - */var/run* - bareos-director runs as user bareos. Best way is to comment out - the entry :command:`Pid Directory = "/var/run"` in - your director config. Bareos will set a working default value - (supposed to be */var/lib/bareos/* - -PostgreSQL -^^^^^^^^^^ - -Renaming a postgresql database: - -- Become postgresql user - -- psql template1 - - .. raw:: latex - - \begin{commands}{} - ALTER DATABASE bacula RENAME TO bareos; - ALTER USER bacula RENAME TO bareos; - ALTER USER bareos UNENCRYPTED PASSWORD 'password'; - \end{commands} diff --git a/docs/manuals/en/new_main_reference/source/basejob.rst b/docs/manuals/en/new_main_reference/source/basejob.rst index 63294105111..e2ec5e6910a 100644 --- a/docs/manuals/en/new_main_reference/source/basejob.rst +++ b/docs/manuals/en/new_main_reference/source/basejob.rst @@ -1,15 +1,9 @@ File Deduplication using Base Jobs ================================== -.. index:: General; Base Jobs -.. _`Base Jobs`: - -.. index:: General; File Deduplication -.. _`File Deduplication`: - - - -.. _`basejobs`: basejobs A base job is sort of like a Full save +:raw-latex:`\index[general]{Base Jobs}` +:raw-latex:`\index[general]{File Deduplication}` +:raw-latex:`\label{basejobs}` A base job is sort of like a Full save except that you will want the FileSet to contain only files that are unlikely to change in the future (i.e. a snapshot of most of your system after installing it). After the base job has been run, when you are @@ -53,7 +47,7 @@ modification time, size and the checksum of the file to choose between the current backup and the BaseJob file list. You can change this behavior with the ``BaseJob`` FileSet option. This option works like the :raw-latex:`\configdirective{Verify}`, that is described in the -:ref:`FileSetResource FileSet` chapter. +:raw-latex:`\ilink{FileSet}{FileSetResource}` chapter. :: diff --git a/docs/manuals/en/new_main_reference/source/bconsole.rst b/docs/manuals/en/new_main_reference/source/bconsole.rst index a10a47ccc37..deb341b0b09 100644 --- a/docs/manuals/en/new_main_reference/source/bconsole.rst +++ b/docs/manuals/en/new_main_reference/source/bconsole.rst @@ -1,13 +1,13 @@ +.. _sec-bconsole: + Bareos Console ============== -.. index:: General; Bareos Console -.. index:: General; bconsole - -.. index:: - triple: General; Command; bconsole +:raw-latex:`\index[general]{Bareos Console}` +:raw-latex:`\index[general]{verbatim}` +:raw-latex:`\index[general]{Command!bconsole}` -The **Bareos Console** (:command:`bconsole`) is a program +The **Bareos Console** (:raw-latex:`\command{verbatim}`) is a program that allows the user or the System Administrator, to interact with the Bareos Director daemon while the daemon is running. @@ -29,12 +29,8 @@ program, indicates that the new tape is mounted. Console Configuration --------------------- - -.. index:: - triple: General; Configuration; Console - -.. index:: - triple: General; Configuration; bconsole +:raw-latex:`\index[general]{Configuration!Console}` +:raw-latex:`\index[general]{Configuration!bconsole}` When the Console starts, it reads a standard Bareos configuration file named **bconsole.conf** unless you specify the **-c** command line @@ -43,7 +39,7 @@ Console, and at the current time, the only Resource Record defined is the Director resource, which gives the Console the name and address of the Director. For more information on configuration of the Console program, please see the -:ref:`Console Configuration ConsoleConfChapter` chapter +:raw-latex:`\ilink{Console Configuration}{ConsoleConfChapter}` chapter of this document. Running the Console Program @@ -53,35 +49,38 @@ The console program can be run with the following options: :raw-latex:`\index[console]{Command Line Options}` -.. raw:: latex +:: - \begin{commandOut}{bconsole command line options}{}{bconsole -?} - Usage: bconsole [-s] [-c config_file] [-d debug_level] - -D select a Director - -l list Directors defined - -c set configuration file to file - -d set debug level to - -dt print timestamp in debug output - -n no conio - -s no signals - -u set command execution timeout to seconds - -t test - read configuration and exit - -? print this message. - \end{commandOut} + {bconsole command line options}{}{bconsole -?} + Usage: bconsole [-s] [-c config_file] [-d debug_level] + -D select a Director + -l list Directors defined + -c set configuration file to file + -d set debug level to + -dt print timestamp in debug output + -n no conio + -s no signals + -u set command execution timeout to seconds + -t test - read configuration and exit + -? print this message. After launching the Console program (bconsole), it will prompt you for -the next command with an asterisk (\*). Generally, for all commands, you +the next command with an asterisk (*). Generally, for all commands, you can simply enter the command name and the Console program will prompt you for the necessary arguments. Alternatively, in most cases, you may enter the command followed by arguments. The general format is: +.. raw:: latex + \footnotesize :: [=] [=] ... +.. raw:: latex + \normalsize where **command** is one of the commands listed below; **keyword** is one of the keywords listed below (usually followed by an argument); and @@ -94,23 +93,31 @@ abbreviated. For example: +.. raw:: latex + \footnotesize :: list files jobid=23 +.. raw:: latex + \normalsize will list all files saved for JobId 23. Or: +.. raw:: latex + \footnotesize :: show pools +.. raw:: latex + \normalsize will display all the Pool resource records. @@ -121,9 +128,7 @@ line length. Exit the Console Program ~~~~~~~~~~~~~~~~~~~~~~~~ - -.. index:: - triple: General; Command!bconsole; exit +:raw-latex:`\index[general]{Command!bconsole!exit}` Normally, you simply enter **quit** or **exit** and the Console program will terminate. However, it waits until the Director acknowledges the @@ -144,16 +149,16 @@ cancel at the next prompt. Running the Console from a Shell Script ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. index:: - triple: General; Console; Running from a Shell -.. _scripting: +:raw-latex:`\index[general]{Console!Running from a Shell}` +:raw-latex:`\label{scripting}` You can automate many Console tasks by running the console program from a shell script. For example, if you have created a file containing the following commands: +.. raw:: latex + \footnotesize :: @@ -162,7 +167,9 @@ following commands: quit END_OF_DATA +.. raw:: latex + \normalsize when that file is executed, it will unmount the current DDS-4 storage device. You might want to run this command during a Job by using the @@ -171,13 +178,17 @@ device. You might want to run this command during a Job by using the It is also possible to run the Console program from file input where the file contains the commands as follows: +.. raw:: latex + \footnotesize :: bconsole -c ./bconsole.conf ] [storage=] [jobid=] - \end{bconsole} + {add} + add [pool=] [storage=] [jobid=] - Normally, the :command:`label ` command is used rather - than this command because the :command:`label ` + Normally, the :raw-latex:`\bcommand{label}{}` command is used rather + than this command because the :raw-latex:`\bcommand{label}{}` command labels the physical media (tape, disk,, ...) and does the - equivalent of the :command:`add ` command. The - :command:`add ` command affects only the Catalog and + equivalent of the :raw-latex:`\bcommand{add}{}` command. The + :raw-latex:`\bcommand{add}{}` command affects only the Catalog and not the physical media (data on Volumes). The physical media must exist and be labeled before use (usually with the - :command:`label ` command). This command can, however, + :raw-latex:`\bcommand{label}{}` command). This command can, however, be useful if you wish to add a number of Volumes to the Pool that will be physically labeled at a later time. It can also be useful if you are importing a tape from another site. Please see the - :command:`label ` command for the list of legal + :raw-latex:`\bcommand{label}{}` command for the list of legal characters in a Volume name. autodisplay - -.. index:: - triple: General; Console!Command; autodisplay on/off + :raw-latex:`\index[general]{Console!Command!autodisplay on/off}` This command accepts **on** or **off** as an argument, and turns auto-display of messages on or off respectively. The default for the console program is **off**, which means that you will be notified @@ -463,9 +477,7 @@ autodisplay received. automount - -.. index:: - triple: General; Console!Command; automount on/off This + :raw-latex:`\index[general]{Console!Command!automount on/off}` This command accepts **on** or **off** as the argument, and turns auto-mounting of the Volume after a **label** command on or off respectively. The default is **on**. If **automount** is turned off, @@ -473,9 +485,7 @@ automount use it. cancel - -.. index:: - triple: General; Console!Command; cancel jobid This + :raw-latex:`\index[general]{Console!Command!cancel jobid}` This command is used to cancel a job and accepts **jobid=nnn** or **job=xxx** as an argument where nnn is replaced by the JobId and xxx is replaced by the job name. If you do not specify a keyword, @@ -484,11 +494,10 @@ cancel The full form of this command is: - .. raw:: latex + :: - \begin{bconsole}{cancel} - cancel [jobid= job= ujobid=] - \end{bconsole} + {cancel} + cancel [jobid= job= ujobid=] Once a Job is marked to be cancelled, it may take a bit of time (generally within a minute but up to two hours) before the Job @@ -513,36 +522,32 @@ cancel Usage: - .. raw:: latex + :: - \begin{bconsole}{cancel all} - cancel all - cancel all state= - \end{bconsole} + {cancel all} + cancel all + cancel all state= Sometimes the Director already removed the job from its running queue, but the storage daemon still thinks it is doing a backup (or another job) - so you cannot cancel the job from within a console anymore. Therefore it is possible to cancel a job by JobId on the storage daemon. It might be helpful to execute a - :command:`status storage ` on the Storage Daemon to + :raw-latex:`\bcommand{status storage}{}` on the Storage Daemon to make sure what job you want to cancel. Usage: - .. raw:: latex + :: - \begin{bconsole}{cancel on Storage Daemon} - cancel storage= Jobid= - \end{bconsole} + {cancel on Storage Daemon} + cancel storage= Jobid= This way you can also remove a job that blocks any other jobs from running without the need to restart the whole storage daemon. create - -.. index:: - triple: General; Console!Command; create pool This + :raw-latex:`\index[general]{Console!Command!create pool}` This command is not normally used as the Pool records are automatically created by the Director when it starts based on what it finds in the configuration. If needed, this command can be used, to create a Pool @@ -559,11 +564,10 @@ create The full form of this command is: - .. raw:: latex + :: - \begin{bconsole}{create} - create [pool=] - \end{bconsole} + {create} + create [pool=] When starting a Job, if Bareos determines that there is no Pool record in the database, but there is a Pool resource of the @@ -572,130 +576,132 @@ create command to force it to be created. configure - .. _sec:bcommandConfigure: + :raw-latex:`\label{sec-bcommandConfigure}` Configures director resources during runtime. The first configure - subcommands are :command:`configure add` and - :command:`configure export`. Other subcommands may + subcommands are :raw-latex:`\bcommand{configure}{add}` and + :raw-latex:`\bcommand{configure}{export}`. Other subcommands may follow in later releases. configure add - .. _sec:bcommandConfigureAdd: - -.. index:: - triple: General; Console!Command; configure add + :raw-latex:`\label{sec-bcommandConfigureAdd}` + :raw-latex:`\index[general]{Console!Command!configure add}` This command allows to add resources during runtime. Usage: - .. raw:: latex + :: - \begin{bconsole}{configure add usage} - configure add name= = = ... - \end{bconsole} + {configure add usage} + configure add name= = = ... Values that must be quoted in the resulting configuration must be added as: - .. raw:: latex + :: - \begin{bconsole}{configure add usage with values containing spaces} - configure add name= ="\"\"" ... - \end{bconsole} + {configure add usage with values containing spaces} + configure add name= ="\"\"" ... The command generates and loads a new valid resource. As the new resource is also stored at - */bareos-dir.d//.conf* + .. raw:: latex + + \file{/bareos-dir.d//.conf} (see - :ref:`sec:ConfigurationResourceFileConventions`) + :raw-latex:`\nameref{sec-ConfigurationResourceFileConventions}`) it is persistent upon reload and restart. This feature requires - :ref:`sec:ConfigurationSubdirectories`. + :raw-latex:`\nameref{sec-ConfigurationSubdirectories}`. All kinds of resources can be added. When adding a client - resource, the :ref:`ClientResourceDirector` for - the |bareosFd| is also created and stored at: - - */bareos-dir-export/client//bareos-fd.d/director/.conf* + resource, the :raw-latex:`\nameref{ClientResourceDirector}` for + the |bareosFd| is also created and stored at: .. raw:: latex - \begin{bconsole}{Example: adding a client and a job resource during runtime} - *configure add client name=client2-fd address=192.168.0.2 password=secret - Created resource config file "/etc/bareos/bareos-dir.d/client/client2-fd.conf": - Client { - Name = client2-fd - Address = 192.168.0.2 - Password = secret - } - *configure add job name=client2-job client=client2-fd jobdefs=DefaultJob - Created resource config file "/etc/bareos/bareos-dir.d/job/client2-job.conf": - Job { - Name = client2-job - Client = client2-fd - JobDefs = DefaultJob - } - \end{bconsole} + \file{/bareos-dir-export/client//bareos-fd.d/director/.conf} + + :: + + {Example: adding a client and a job resource during runtime} + *configure add client name=client2-fd address=192.168.0.2 password=secret + Created resource config file "/etc/bareos/bareos-dir.d/client/client2-fd.conf": + Client { + Name = client2-fd + Address = 192.168.0.2 + Password = secret + } + *configure add job name=client2-job client=client2-fd jobdefs=DefaultJob + Created resource config file "/etc/bareos/bareos-dir.d/job/client2-job.conf": + Job { + Name = client2-job + Client = client2-fd + JobDefs = DefaultJob + } These two commands create three resource configuration files: - - */etc/bareos/bareos-dir.d/client/client2-fd.conf* + - + + .. raw:: latex - - */etc/bareos/bareos-dir-export/client/client2-fd/bareos-fd.d/director/bareos-dir.conf* + \file{/etc/bareos/bareos-dir.d/client/client2-fd.conf} + + - :raw-latex:`\file{/etc/bareos/bareos-dir-export/client/client2-fd/bareos-fd.d/director/bareos-dir.conf}` (assuming your director resource is named - **bareos-dir**) + :raw-latex:`\name{bareos-dir}`) + + - - - */etc/bareos/bareos-dir.d/job/client2-job.conf* + .. raw:: latex - The files in *bareos-dir-export/client/* - directory are not used by the |bareosDir| . However, + \file{/etc/bareos/bareos-dir.d/job/client2-job.conf} + + The files in :raw-latex:`\directory{bareos-dir-export/client/}` + directory are not used by the |bareosDir|. However, they can be copied to new clients to configure these clients for - the |bareosDir| . + the |bareosDir|. + + .. raw:: latex - -.. warning:: - Don't be confused by the extensive output of \bcommand{help}{configure}. As \bcommand{configure}{add} allows configuring arbitrary resources, the output of \bcommand{help}{configure} lists all the resources, each with all valid directives. The same data is also used for \command{bconsole} command line completion. + \warning{Don't be confused by the extensive output of \bcommand{help}{configure}. As \bcommand{configure}{add} allows configuring arbitrary resources, the output of \bcommand{help}{configure} lists all the resources, each with all valid directives. The same data is also used for \command{verbatim} command line completion.} Available since Bareos - 16.2.4. + :raw-latex:`\sinceVersion{console}{configure add}{16.2.4}`. configure export - .. _sec:bcommandConfigureExport: - -.. index:: - triple: General; Console!Command; configure export + :raw-latex:`\label{sec-bcommandConfigureExport}` + :raw-latex:`\index[general]{Console!Command!configure export}` This command allows to export the :raw-latex:`\resourcetype{Fd}{Director}` resource for clients - already configured in the |bareosDir| . + already configured in the |bareosDir|. Usage: - .. raw:: latex + :: - \begin{bconsole}{Export the bareos-fd Director resource for the client bareos-fd} - configure export client=bareos-fd - Exported resource file "/etc/bareos/bareos-dir-export/client/bareos-fd/bareos-fd.d/director/bareos-dir.conf": - Director { - Name = bareos-dir - Password = "[md5]932d1d3ef3c298047809119510f4bee6" - } - \end{bconsole} + {Export the bareos-fd Director resource for the client bareos-fd} + configure export client=bareos-fd + Exported resource file "/etc/bareos/bareos-dir-export/client/bareos-fd/bareos-fd.d/director/bareos-dir.conf": + Director { + Name = bareos-dir + Password = "[md5]932d1d3ef3c298047809119510f4bee6" + } To use it, copy the :raw-latex:`\resourcetype{Fd}{Director}` resource file to the client machine (on Linux: to - */etc/bareos/bareos-fd.d/director/*) and - restart the |bareosFd| . + :raw-latex:`\directory{/etc/bareos/bareos-fd.d/director/}`) and + restart the |bareosFd|. Available since Bareos - 16.2.4. + :raw-latex:`\sinceVersion{console}{configure export}{16.2.4}`. delete - -.. index:: - triple: General; Console!Command; delete The delete + :raw-latex:`\index[general]{Console!Command!delete}` The delete command is used to delete a Volume, Pool or Job record from the Catalog as well as all associated catalog Volume records that were created. This command operates only on the Catalog database and has @@ -712,67 +718,58 @@ delete The full form of this command is: - .. raw:: latex + :: - \begin{bconsole}{delete} - delete pool= - delete volume= pool= - delete JobId= JobId= ... - delete Job JobId=n,m,o-r,t ... - \end{bconsole} + {delete} + delete pool= + delete volume= pool= + delete JobId= JobId= ... + delete Job JobId=n,m,o-r,t ... The first form deletes a Pool record from the catalog database. The second form deletes a Volume record from the specified pool in the catalog database. The third form deletes the specified Job record from the catalog database. The last form deletes JobId records for JobIds n, m, o, p, q, r, and t. Where each one of the n,m,... is, of - course, a number. That is a “delete jobid” accepts lists and ranges + course, a number. That is a "delete jobid" accepts lists and ranges of jobids. disable - -.. index:: - triple: General; Console!Command; disable This command + :raw-latex:`\index[general]{Console!Command!disable}` This command permits you to disable a Job for automatic scheduling. The job may have been previously enabled with the Job resource **Enabled** directive or using the console **enable** command. The next time the Director is reloaded or restarted, the Enable/Disable state will be set to the value in the Job resource (default enabled) as defined in - the |bareosDir| configuration. + the |bareosDir| configuration. The full form of this command is: - .. raw:: latex + :: - \begin{bconsole}{disable} - disable job= - \end{bconsole} + {disable} + disable job= enable - -.. index:: - triple: General; Console!Command; enable This command + :raw-latex:`\index[general]{Console!Command!enable}` This command permits you to enable a Job for automatic scheduling. The job may have been previously disabled with the Job resource **Enabled** directive or using the console **disable** command. The next time the Director is reloaded or restarted, the Enable/Disable state will be set to the value in the Job resource (default enabled) as defined - in the |bareosDir| configuration. + in the |bareosDir| configuration. The full form of this command is: - .. raw:: latex + :: - \begin{bconsole}{enable} - enable job= - \end{bconsole} + {enable} + enable job= - .. _estimate: + :raw-latex:`\label{estimate}` estimate - -.. index:: - triple: General; Console!Command; estimate Using this + :raw-latex:`\index[general]{Console!Command!estimate}` Using this command, you can get an idea how many files will be backed up, or if you are unsure about your Include statements in your FileSet, you can test them without doing an actual backup. The default is to @@ -798,11 +795,10 @@ estimate The full form of this command is: - .. raw:: latex + :: - \begin{bconsole}{estimate} - estimate job= listing client= accurate= fileset= level= - \end{bconsole} + {estimate} + estimate job= listing client= accurate= fileset= level= Specification of the **job** is sufficient, but you can also override the client, fileset, accurate and/or level by specifying @@ -810,13 +806,12 @@ estimate As an example, you might do: - .. raw:: latex + :: - \begin{bconsole}{estimate: redirected output} - @output /tmp/listing - estimate job=NightlySave listing level=Incremental - @output - \end{bconsole} + {estimate: redirected output} + @output /tmp/listing + estimate job=NightlySave listing level=Incremental + @output which will do a full listing of all files to be backed up for the Job **NightlySave** during an Incremental save and put it in the @@ -831,15 +826,11 @@ estimate option be enabled. exit - -.. index:: - triple: General; Console!Command; exit This command + :raw-latex:`\index[general]{Console!Command!exit}` This command terminates the console program. export - -.. index:: - triple: General; Console!Command; export The export + :raw-latex:`\index[general]{Console!Command!export}` The export command is used to export tapes from an autochanger. Most Automatic Tapechangers offer special slots for importing new tape cartridges or exporting written tape cartridges. This can happen without having @@ -847,11 +838,10 @@ export The full form of this command is: - .. raw:: latex + :: - \begin{bconsole}{export} - export storage= srcslots= [dstslots= volume= scan] - \end{bconsole} + {export} + export storage= srcslots= [dstslots= volume= scan] The export command does exactly the opposite of the import command. You can specify which slots should be transferred to import/export @@ -864,11 +854,10 @@ export Example: - .. raw:: latex + :: - \begin{bconsole}{export volume} - export volume=A00020L4|A00007L4|A00005L4 - \end{bconsole} + {export volume} + export volume=A00020L4|A00007L4|A00005L4 Instead of exporting volumes by names you can also select a number of slots via the srcslots keyword and export those to the slots you @@ -878,24 +867,22 @@ export Example: - .. raw:: latex + :: - \begin{bconsole}{export slots} - export srcslots=1-2 dstslots=37-38 - \end{bconsole} + {export slots} + export srcslots=1-2 dstslots=37-38 To automatically export the Volumes used by a certain backup job, you can use the following RunScript in that job: - .. raw:: latex + :: - \begin{bconsole}{automatic export} - RunScript { - Console = "export storage=TandbergT40 volume=%V" - RunsWhen = After - RunsOnClient = no - } - \end{bconsole} + {automatic export} + RunScript { + Console = "export storage=TandbergT40 volume=%V" + RunsWhen = After + RunsOnClient = no + } To send an e-mail notification via the Messages resource regarding export tapes you can use the Variable %V substitution in the @@ -903,30 +890,23 @@ export does also work in earlier releases inside the job resources. So in versions prior to Bareos 13.2 the following workaround can be used: - .. raw:: latex + :: - \begin{bconsole}{e-mail notification via messages resource regarding export tapes} - RunAfterJob = "/bin/bash -c \"/bin/echo Remove Tape %V | \ - /usr/sbin/bsmtp -h localhost -f root@localhost -s 'Remove Tape %V' root@localhost \"" - \end{bconsole} + {e-mail notification via messages resource regarding export tapes} + RunAfterJob = "/bin/bash -c \"/bin/echo Remove Tape %V | \ + /usr/sbin/bsmtp -h localhost -f root@localhost -s 'Remove Tape %V' root@localhost \"" gui - -.. index:: - triple: General; Console!Command; gui Invoke the + :raw-latex:`\index[general]{Console!Command!gui}` Invoke the non-interactive gui mode. This command is only used when - :command:`bconsole` is commanded by an external program. + :raw-latex:`\command{verbatim}` is commanded by an external program. help - -.. index:: - triple: General; Console!Command; help This command + :raw-latex:`\index[general]{Console!Command!help}` This command displays the list of commands available. import - -.. index:: - triple: General; Console!Command; import The import + :raw-latex:`\index[general]{Console!Command!import}` The import command is used to import tapes into an autochanger. Most Automatic Tapechangers offer special slots for importing new tape cartridges or exporting written tape cartridges. This can happen without having @@ -934,11 +914,10 @@ import The full form of this command is: - .. raw:: latex + :: - \begin{bconsole}{import} - import storage= [srcslots= dstslots= volume= scan] - \end{bconsole} + {import} + import storage= [srcslots= dstslots= volume= scan] To import new tapes into the autochanger, you only have to load the new tapes into the import/export slots and call import from the @@ -951,25 +930,24 @@ import Example with a Library with 36 Slots and 3 Import/Export Slots: - .. raw:: latex + :: - \begin{bconsole}{import example} - *import storage=TandbergT40 - Connecting to Storage daemon TandbergT40 at bareos:9103 ... - 3306 Issuing autochanger "slots" command. - Device "Drive-1" has 39 slots. - Connecting to Storage daemon TandbergT40 at bareos:9103 ... - 3306 Issuing autochanger "listall" command. - Connecting to Storage daemon TandbergT40 at bareos:9103 ... - 3306 Issuing autochanger transfer command. - 3308 Successfully transfered volume from slot 37 to 20. - Connecting to Storage daemon TandbergT40 at bareos:9103 ... - 3306 Issuing autochanger transfer command. - 3308 Successfully transfered volume from slot 38 to 21. - Connecting to Storage daemon TandbergT40 at bareos:9103 ... - 3306 Issuing autochanger transfer command. - 3308 Successfully transfered volume from slot 39 to 25. - \end{bconsole} + {import example} + *import storage=TandbergT40 + Connecting to Storage daemon TandbergT40 at bareos:9103 ... + 3306 Issuing autochanger "slots" command. + Device "Drive-1" has 39 slots. + Connecting to Storage daemon TandbergT40 at bareos:9103 ... + 3306 Issuing autochanger "listall" command. + Connecting to Storage daemon TandbergT40 at bareos:9103 ... + 3306 Issuing autochanger transfer command. + 3308 Successfully transfered volume from slot 37 to 20. + Connecting to Storage daemon TandbergT40 at bareos:9103 ... + 3306 Issuing autochanger transfer command. + 3308 Successfully transfered volume from slot 38 to 21. + Connecting to Storage daemon TandbergT40 at bareos:9103 ... + 3306 Issuing autochanger transfer command. + 3308 Successfully transfered volume from slot 39 to 25. You can also import certain slots when you don’t have enough free slots in your autochanger to put all the import/export slots in. @@ -977,34 +955,28 @@ import Example with a Library with 36 Slots and 3 Import/Export Slots importing one slot: - .. raw:: latex + :: - \begin{bconsole}{import example} - *import storage=TandbergT40 srcslots=37 dstslots=20 - Connecting to Storage daemon TandbergT40 at bareos:9103 ... - 3306 Issuing autochanger "slots" command. - Device "Drive-1" has 39 slots. - Connecting to Storage daemon TandbergT40 at bareos:9103 ... - 3306 Issuing autochanger "listall" command. - Connecting to Storage daemon TandbergT40 at bareos:9103 ... - 3306 Issuing autochanger transfer command. - 3308 Successfully transfered volume from slot 37 to 20. - \end{bconsole} + {import example} + *import storage=TandbergT40 srcslots=37 dstslots=20 + Connecting to Storage daemon TandbergT40 at bareos:9103 ... + 3306 Issuing autochanger "slots" command. + Device "Drive-1" has 39 slots. + Connecting to Storage daemon TandbergT40 at bareos:9103 ... + 3306 Issuing autochanger "listall" command. + Connecting to Storage daemon TandbergT40 at bareos:9103 ... + 3306 Issuing autochanger transfer command. + 3308 Successfully transfered volume from slot 37 to 20. label - -.. index:: - triple: General; Console!Command; label - -.. index:: - triple: General; Console!Command; relabel This command + :raw-latex:`\index[general]{Console!Command!label}` + :raw-latex:`\index[general]{Console!Command!relabel}` This command is used to label physical volumes. The full form of this command is: - .. raw:: latex + :: - \begin{bconsole}{label} - label storage= volume= slot= - \end{bconsole} + {label} + label storage= volume= slot= If you leave out any part, you will be prompted for it. The media type is automatically taken from the Storage resource definition @@ -1025,14 +997,18 @@ label labeled. If you wish to avoid getting these messages, please write an EOF mark on your tape before attempting to label it: - + .. raw:: latex + + \footnotesize :: mt rewind mt weof - + .. raw:: latex + + \normalsize The label command can fail for a number of reasons: @@ -1052,14 +1028,18 @@ label label. The brute force method is to write an end of file mark on the tape using the system **mt** program, something like the following: - + .. raw:: latex + + \footnotesize :: mt -f /dev/st0 rewind mt -f /dev/st0 weof - + .. raw:: latex + + \normalsize For a disk volume, you would manually delete the Volume. @@ -1068,81 +1048,76 @@ label The preferable method to relabel a Volume is to first purge the volume, either automatically, or explicitly with the - :command:`purge ` command, then use the - :command:`relabel ` command described below. + :raw-latex:`\bcommand{purge}{}` command, then use the + :raw-latex:`\bcommand{relabel}{}` command described below. If your autochanger has barcode labels, you can label all the Volumes in your autochanger one after another by using the - :command:`label barcodes` command. For each tape in + :raw-latex:`\bcommand{label}{barcodes}` command. For each tape in the changer containing a barcode, Bareos will mount the tape and then label it with the same name as the barcode. An appropriate Media record will also be created in the catalog. Any barcode that begins with the same characters as specified on the - “CleaningPrefix=xxx” (default is “CLN”) directive in the Director’s + "CleaningPrefix=xxx" (default is "CLN") directive in the Director’s Pool resource, will be treated as a cleaning tape, and will not be labeled. However, an entry for the cleaning tape will be created in the catalog. For example with: - .. raw:: latex + :: - \begin{bconfig}{Cleaning Tape} - Pool { - Name ... - Cleaning Prefix = "CLN" - } - \end{bconfig} + {Cleaning Tape} + Pool { + Name ... + Cleaning Prefix = "CLN" + } Any slot containing a barcode of CLNxxxx will be treated as a cleaning tape and will not be mounted. Note, the full form of the command is: - .. raw:: latex + :: - \begin{bconsole}{label} - label storage=xxx pool=yyy slots=1-5,10 barcodes - \end{bconsole} + {label} + label storage=xxx pool=yyy slots=1-5,10 barcodes list - -.. index:: - triple: General; Console!Command; list The list command + :raw-latex:`\index[general]{Console!Command!list}` The list command lists the requested contents of the Catalog. The various fields of each record are listed on a single line. The various forms of the list command are: - .. raw:: latex + :: - \begin{bconsole}{list} - list jobs - list jobid= (list jobid id) - list ujobid= (list job with unique name) - list job= (list all jobs with "job-name") - list jobname= (same as above) - In the above, you can add "limit=nn" to limit the output to nn jobs. - list joblog jobid= (list job output if recorded in the catalog) - list jobmedia - list jobmedia jobid= - list jobmedia job= - list files jobid= - list files job= - list pools - list clients - list jobtotals - list volumes - list volumes jobid= - list volumes pool= - list volumes job= - list volume= - list nextvolume job= - list nextvol job= - list nextvol job= days=nnn - \end{bconsole} + {list} + list jobs + list jobid= (list jobid id) + list ujobid= (list job with unique name) + list job= (list all jobs with "job-name") + list jobname= (same as above) + In the above, you can add "limit=nn" to limit the output to nn jobs. + list joblog jobid= (list job output if recorded in the catalog) + list jobmedia + list jobmedia jobid= + list jobmedia job= + list files jobid= + list files job= + list pools + list clients + list jobtotals + list volumes + list volumes jobid= + list volumes pool= + list volumes job= + list volume= + list nextvolume job= + list nextvol job= + list nextvol job= days=nnn What most of the above commands do should be more or less obvious. In general if you do not specify all the command line arguments, the command will prompt you for what is needed. - The :command:`list nextvol` command will print the + The :raw-latex:`\bcommand{list}{nextvol}` command will print the Volume name to be used by the specified job. You should be aware that exactly what Volume will be used depends on a lot of factors including the time and what a prior job will do. It may fill a tape @@ -1156,30 +1131,29 @@ list specification to specify up to 50 days. For example, if on Friday, you want to see what Volume will be needed on Monday, for job MyJob, you would use - :command:`list nextvol job=MyJob days=3`. + :raw-latex:`\bcommand{list}{nextvol job=MyJob days=3}`. If you wish to add specialized commands that list the contents of the catalog, you can do so by adding them to the - *query.sql* file. However, this takes some + :raw-latex:`\file{query.sql}` file. However, this takes some knowledge of programming SQL. Please see the - :command:`query ` command below for additional + :raw-latex:`\bcommand{query}{}` command below for additional information. See below for listing the full contents of a catalog - record with the :command:`llist ` command. + record with the :raw-latex:`\bcommand{llist}{}` command. As an example, the command **list pools** might produce the following output: - .. raw:: latex + :: - \begin{bconsole}{list pools} - *list pools - +------+---------+---------+---------+----------+-------------+ - | PoId | Name | NumVols | MaxVols | PoolType | LabelFormat | - +------+---------+---------+---------+----------+-------------+ - | 1 | Default | 0 | 0 | Backup | * | - | 2 | Recycle | 0 | 8 | Backup | File | - +------+---------+---------+---------+----------+-------------+ - \end{bconsole} + {list pools} + *list pools + +------+---------+---------+---------+----------+-------------+ + | PoId | Name | NumVols | MaxVols | PoolType | LabelFormat | + +------+---------+---------+---------+----------+-------------+ + | 1 | Default | 0 | 0 | Backup | * | + | 2 | Recycle | 0 | 8 | Backup | File | + +------+---------+---------+---------+----------+-------------+ As mentioned above, the **list** command lists what is in the database. Some things are put into the database immediately when @@ -1192,16 +1166,14 @@ list database record to be created. The client database record will be created whether or not the job fails, but it must at least start. When the Client is actually contacted, additional info from the - client will be added to the client record (a “uname -a” output). + client will be added to the client record (a "uname -a" output). If you want to see what Client resources you have available in your conf file, you use the Console command **show clients**. llist - -.. index:: - triple: General; Console!Command; llist The llist or - “long list” command takes all the same arguments that the list + :raw-latex:`\index[general]{Console!Command!llist}` The llist or + "long list" command takes all the same arguments that the list command described above does. The difference is that the llist command list the full contents of each database record selected. It does so by listing the various fields of the record vertically, with @@ -1211,111 +1183,98 @@ llist If instead of the **list pools** as in the example above, you enter **llist pools** you might get the following output: - .. raw:: latex + :: - \begin{bconsole}{llist pools} - *llist pools - PoolId: 1 - Name: Default - NumVols: 0 - MaxVols: 0 - UseOnce: 0 - UseCatalog: 1 - AcceptAnyVolume: 1 - VolRetention: 1,296,000 - VolUseDuration: 86,400 - MaxVolJobs: 0 - MaxVolBytes: 0 - AutoPrune: 0 - Recycle: 1 - PoolType: Backup - LabelFormat: * - - PoolId: 2 - Name: Recycle - NumVols: 0 - MaxVols: 8 - UseOnce: 0 - UseCatalog: 1 - AcceptAnyVolume: 1 - VolRetention: 3,600 - VolUseDuration: 3,600 - MaxVolJobs: 1 - MaxVolBytes: 0 - AutoPrune: 0 - Recycle: 1 - PoolType: Backup - LabelFormat: File - \end{bconsole} + {llist pools} + *llist pools + PoolId: 1 + Name: Default + NumVols: 0 + MaxVols: 0 + UseOnce: 0 + UseCatalog: 1 + AcceptAnyVolume: 1 + VolRetention: 1,296,000 + VolUseDuration: 86,400 + MaxVolJobs: 0 + MaxVolBytes: 0 + AutoPrune: 0 + Recycle: 1 + PoolType: Backup + LabelFormat: * + + PoolId: 2 + Name: Recycle + NumVols: 0 + MaxVols: 8 + UseOnce: 0 + UseCatalog: 1 + AcceptAnyVolume: 1 + VolRetention: 3,600 + VolUseDuration: 3,600 + MaxVolJobs: 1 + MaxVolBytes: 0 + AutoPrune: 0 + Recycle: 1 + PoolType: Backup + LabelFormat: File messages - -.. index:: - triple: General; Console!Command; messages This command + :raw-latex:`\index[general]{Console!Command!messages}` This command causes any pending console messages to be immediately displayed. memory - -.. index:: - triple: General; Console!Command; memory Print current + :raw-latex:`\index[general]{Console!Command!memory}` Print current memory usage. mount - -.. index:: - triple: General; Console!Command; mount The mount + :raw-latex:`\index[general]{Console!Command!mount}` The mount command is used to get Bareos to read a volume on a physical device. It is a way to tell Bareos that you have mounted a tape and that Bareos should examine the tape. This command is normally used only after there was no Volume in a drive and Bareos requests you to mount a new Volume or when you have specifically unmounted a Volume - with the :command:`unmount ` console command, which + with the :raw-latex:`\bcommand{unmount}{}` console command, which causes Bareos to close the drive. If you have an autoloader, the mount command will not cause Bareos to operate the autoloader unless you specify a **slot** and possibly a **drive**. The various forms of the mount command are: - .. raw:: latex + :: - \begin{bconsole}{mount} - mount storage= [slot=] [drive=] - mount [jobid= | job=] - \end{bconsole} + {mount} + mount storage= [slot=] [drive=] + mount [jobid= | job=] If you have specified - Automatic Mount = yes (Sd configuration, Device resource), + :raw-latex:`\linkResourceDirectiveValue{Sd}{Device}{Automatic Mount}{yes}`, under most circumstances, Bareos will automatically access the Volume unless you have explicitly - :command:`unmount `ed it in the Console program. + :raw-latex:`\bcommand{unmount}{}`ed it in the Console program. move - -.. index:: - triple: General; Console!Command; move The move command + :raw-latex:`\index[general]{Console!Command!move}` The move command allows to move volumes between slots in an autochanger without having to leave the bconsole. To move a volume from slot 32 to slots 33, use: - .. raw:: latex + :: - \begin{bconsole}{move} - *move storage=TandbergT40 srcslots=32 dstslots=33 - Connecting to Storage daemon TandbergT40 at bareos:9103 ... - 3306 Issuing autochanger "slots" command. - Device "Drive-1" has 39 slots. - Connecting to Storage daemon TandbergT40 at bareos:9103 ... - 3306 Issuing autochanger "listall" command. - Connecting to Storage daemon TandbergT40 at bareos:9103 ... - 3306 Issuing autochanger transfer command. - 3308 Successfully transfered volume from slot 32 to 33. - \end{bconsole} + {move} + *move storage=TandbergT40 srcslots=32 dstslots=33 + Connecting to Storage daemon TandbergT40 at bareos:9103 ... + 3306 Issuing autochanger "slots" command. + Device "Drive-1" has 39 slots. + Connecting to Storage daemon TandbergT40 at bareos:9103 ... + 3306 Issuing autochanger "listall" command. + Connecting to Storage daemon TandbergT40 at bareos:9103 ... + 3306 Issuing autochanger transfer command. + 3308 Successfully transfered volume from slot 32 to 33. prune - -.. index:: - triple: General; Console!Command; prune - .. _ManualPruning: The Prune command allows you to + :raw-latex:`\index[general]{Console!Command!prune}` + :raw-latex:`\label{ManualPruning}` The Prune command allows you to safely remove expired database records from Jobs, Volumes and Statistics. This command works only on the Catalog database and does not affect data written to Volumes. In all cases, the Prune command @@ -1324,96 +1283,86 @@ prune records from the database, and you can Prune both expired Job and File records from specified Volumes. - .. raw:: latex + :: - \begin{bconsole}{prune} - prune files [client=] [pool=] [yes] | - jobs [client=] [pool=] [jobtype=] [yes] | - volume [=volume] [pool=] [yes] | - stats [yes] - \end{bconsole} + {prune} + prune files [client=] [pool=] [yes] | + jobs [client=] [pool=] [jobtype=] [yes] | + volume [=volume] [pool=] [yes] | + stats [yes] For a Volume to be pruned, the volume status must be - **Full}`, :raw-latex:`\volumestatus{Used** - or **Append** otherwise the pruning will not + :raw-latex:`\volumestatus{Full}`, :raw-latex:`\volumestatus{Used}` + or :raw-latex:`\volumestatus{Append}` otherwise the pruning will not take place. purge - -.. index:: - triple: General; Console!Command; purge - .. _bcommandPurge: The Purge command will delete + :raw-latex:`\index[general]{Console!Command!purge}` + :raw-latex:`\label{bcommandPurge}` The Purge command will delete associated catalog database records from Jobs and Volumes without considering the retention period. This command can be dangerous because you can delete catalog records associated with current backups of files, and we recommend that you do not use it unless you know what you are doing. The permitted forms of - :command:`purge ` are: + :raw-latex:`\bcommand{purge}{}` are: - .. raw:: latex + :: - \begin{bconsole}{purge} - purge [files [job= | jobid= | client= | volume=]] | - [jobs [client= | volume=]] | - [volume [=] [storage=] [pool=] [devicetype=] [drive=] [action=]] | - [quota [client=]] - \end{bconsole} + {purge} + purge [files [job= | jobid= | client= | volume=]] | + [jobs [client= | volume=]] | + [volume [=] [storage=] [pool=] [devicetype=] [drive=] [action=]] | + [quota [client=]] - For the :command:`purge ` command to work on volume + For the :raw-latex:`\bcommand{purge}{}` command to work on volume catalog database records the volume status must be - **Append**, - **Full}`, :raw-latex:`\volumestatus{Used** - or **Error**. + :raw-latex:`\volumestatus{Append}`, + :raw-latex:`\volumestatus{Full}`, :raw-latex:`\volumestatus{Used}` + or :raw-latex:`\volumestatus{Error}`. The actual data written to the Volume will be unaffected by this command unless you are using the - Action On Purge = Truncate (Dir configuration, Pool resource) + :raw-latex:`\linkResourceDirectiveValue{Dir}{Pool}{Action On Purge}{Truncate}` option. - To ask Bareos to truncate your **Purged** + To ask Bareos to truncate your :raw-latex:`\volumestatus{Purged}` volumes, you need to use the following command in interactive mode: - .. raw:: latex + :: - \begin{bconsole}{purge example} - *purge volume action=truncate storage=File pool=Full - \end{bconsole} + {purge example} + *purge volume action=truncate storage=File pool=Full - However, normally you should use the :command:`purge ` + However, normally you should use the :raw-latex:`\bcommand{purge}{}` command only to purge a volume from the catalog and use the - :command:`truncate ` command to truncate the volume on - the |bareosSd| . + :raw-latex:`\bcommand{truncate}{}` command to truncate the volume on + the |bareosSd|. resolve - -.. index:: - triple: General; Console!Command; resolve In the + :raw-latex:`\index[general]{Console!Command!resolve}` In the configuration files, Addresses can (and normally should) be specified as DNS names. As the different components of Bareos will establish network connections to other Bareos components, it is important that DNS name resolution works on involved components and - delivers the same results. The :command:`resolve ` + delivers the same results. The :raw-latex:`\bcommand{resolve}{}` command can be used to test DNS resolution of a given hostname on director, storage daemon or client. - .. raw:: latex + :: - \begin{bconsole}{resolve example} - *resolve www.bareos.com - bareos-dir resolves www.bareos.com to host[ipv4:84.44.166.242] + {resolve example} + *resolve www.bareos.com + bareos-dir resolves www.bareos.com to host[ipv4:84.44.166.242] - *resolve client=client1-fd www.bareos.com - client1-fd resolves www.bareos.com to host[ipv4:84.44.166.242] + *resolve client=client1-fd www.bareos.com + client1-fd resolves www.bareos.com to host[ipv4:84.44.166.242] - *resolve storage=File www.bareos.com - bareos-sd resolves www.bareos.com to host[ipv4:84.44.166.242] - \end{bconsole} + *resolve storage=File www.bareos.com + bareos-sd resolves www.bareos.com to host[ipv4:84.44.166.242] query - -.. index:: - triple: General; Console!Command; query - .. _sec:bcommandQuery: This command reads a + :raw-latex:`\index[general]{Console!Command!query}` + :raw-latex:`\label{sec-bcommandQuery}` This command reads a predefined SQL query from the query file (the name and location of the query file is defined with the QueryFile resource record in the Director’s configuration file). You are prompted to select a query @@ -1421,7 +1370,7 @@ query command is submitted to the Catalog database SQL engine. quit - .. index:: General; quit This command terminates the + :raw-latex:`\index[general]{quit}` This command terminates the console program. The console program sends the **quit** request to the Director and waits for acknowledgment. If the Director is busy doing a previous command for you that has not terminated, it may @@ -1429,60 +1378,52 @@ quit command (i.e. quit preceded by a period). relabel - -.. index:: - triple: General; Console!Command; relabel This command + :raw-latex:`\index[general]{Console!Command!relabel}` This command is used to label physical volumes. The full form of this command is: - .. raw:: latex + :: - \begin{bconsole}{relabel} - relabel storage= oldvolume= volume= pool= [encrypt] - \end{bconsole} + {relabel} + relabel storage= oldvolume= volume= pool= [encrypt] If you leave out any part, you will be prompted for it. In order for the Volume (old-volume-name) to be relabeled, it must be in the catalog, and the volume status must be marked - **Purged** or - **Recycle**. This happens automatically as a + :raw-latex:`\volumestatus{Purged}` or + :raw-latex:`\volumestatus{Recycle}`. This happens automatically as a result of applying retention periods or you may explicitly purge the - volume using the :command:`purge ` command. + volume using the :raw-latex:`\bcommand{purge}{}` command. Once the volume is physically relabeled, the old data previously written on the Volume is lost and cannot be recovered. release - -.. index:: - triple: General; Console!Command; release This command + :raw-latex:`\index[general]{Console!Command!release}` This command is used to cause the Storage daemon to release (and rewind) the current tape in the drive, and to re-read the Volume label the next time the tape is used. - .. raw:: latex + :: - \begin{bconsole}{release} - release storage= - \end{bconsole} + {release} + release storage= After a release command, the device is still kept open by Bareos (unless - Always Open = no (Sd configuration, Device resource)) + :raw-latex:`\linkResourceDirectiveValue{Sd}{Device}{Always Open}{no}`) so it cannot be used by another program. However, with some tape drives, the operator can remove the current tape and to insert a different one, and when the next Job starts, Bareos will know to re-read the tape label to find out what tape is mounted. If you want to be able to use the drive with another program (e.g. - :command:`mt`), you must use the - :command:`unmount ` command to cause Bareos to + :raw-latex:`\command{mt}`), you must use the + :raw-latex:`\bcommand{unmount}{}` command to cause Bareos to completely release (close) the device. reload - -.. index:: - triple: General; Console!Command; reload The reload + :raw-latex:`\index[general]{Console!Command!reload}` The reload command causes the Director to re-read its configuration file and apply the new values. The new values will take effect immediately for all new jobs. However, if you change schedules, be aware that @@ -1506,9 +1447,7 @@ reload restart the Director at the next convenient opportunity. rerun - -.. index:: - triple: General; Console!Command; rerun The rerun + :raw-latex:`\index[general]{Console!Command!rerun}` The rerun command allows you to re-run a Job with exactly the same setting as the original Job. In Bareos, the job configuration is often altered by job overrides. These overrides alter the configuration of the job @@ -1522,11 +1461,10 @@ rerun as it was configured. You only have to specify the JobId of the failed job. - .. raw:: latex + :: - \begin{bconsole}{rerun} - rerun jobid= since_jobid= days= hours= yes - \end{bconsole} + {rerun} + rerun jobid= since_jobid= days= hours= yes You can select the jobid(s) to rerun by using one of the selection criteria. Using jobid= will automatically select all jobs failed @@ -1535,14 +1473,10 @@ rerun or number of hours respectively for rerunning. restore - .. index:: General; Restore - -.. index:: - triple: General; Console!Command; restore - -.. index:: - triple: General; Console; File Selection - .. _bcommandRestore: The restore command allows you + :raw-latex:`\index[general]{Restore}` + :raw-latex:`\index[general]{Console!Command!restore}` + :raw-latex:`\index[general]{Console!File Selection}` + :raw-latex:`\label{bcommandRestore}` The restore command allows you to select one or more Jobs (JobIds) to be restored using various methods. Once the JobIds are selected, the File records for those Jobs are placed in an internal Bareos directory tree, and the @@ -1551,15 +1485,14 @@ restore files to be restored. This mode is somewhat similar to the standard Unix **restore** program’s interactive file selection mode. - .. raw:: latex + :: - \begin{bconsole}{restore} - restore storage= client= - where= pool= fileset= - restoreclient= - restorejob= - select current all done - \end{bconsole} + {restore} + restore storage= client= + where= pool= fileset= + restoreclient= + restorejob= + select current all done Where **current**, if specified, tells the restore command to automatically select a restore to the most current backup. If not @@ -1567,7 +1500,7 @@ restore restore command to restore all files. If it is not specified, you will be prompted for the files to restore. For details of the **restore** command, please see the - :ref:`Restore Chapter RestoreChapter` of this manual. + :raw-latex:`\ilink{Restore Chapter}{RestoreChapter}` of this manual. The client keyword initially specifies the client from which the backup was made and the client to which the restore will be make. @@ -1581,29 +1514,26 @@ restore restorejob argument allows the selection of one of these jobs. For more details, see the - :ref:`Restore chapter RestoreChapter`. + :raw-latex:`\ilink{Restore chapter}{RestoreChapter}`. run - -.. index:: - triple: General; Console!Command; run This command + :raw-latex:`\index[general]{Console!Command!run}` This command allows you to schedule jobs to be run immediately. The full form of the command is: - .. raw:: latex + :: - \begin{bconsole}{run} - run job= client= fileset= - level= storage= where= - when= pool= - pluginoptions= accurate= - comment= spooldata= priority= - jobid= catalog= migrationjob= backupclient= - backupformat= nextpool= since= - verifyjob= verifylist= migrationjob= - yes - \end{bconsole} + {run} + run job= client= fileset= + level= storage= where= + when= pool= + pluginoptions= accurate= + comment= spooldata= priority= + jobid= catalog= migrationjob= backupclient= + backupformat= nextpool= since= + verifyjob= verifylist= migrationjob= + yes Any information that is needed but not specified will be listed for selection, and before starting the job, you will be prompted to @@ -1621,39 +1551,27 @@ run schedule flag is used. setbandwidth - -.. index:: - triple: General; Console!Command; setbandwidth This - command (12.4.1) + :raw-latex:`\index[general]{Console!Command!setbandwidth}` This + command (:raw-latex:`\sinceVersion{console}{setbandwidth}{12.4.1}`) is used to limit the bandwidth of a running job or a client. - .. raw:: latex + :: - \begin{bconsole}{setbandwidth} - setbandwidth limit= [jobid= | client=] - \end{bconsole} + {setbandwidth} + setbandwidth limit= [jobid= | client=] setdebug - .. _bcommandSetdebug: - -.. index:: - triple: General; Console!Command; setdebug - -.. index:: - triple: General; Debug; setdebug - -.. index:: - triple: General; Debug; Windows - -.. index:: - triple: General; Windows; Debug This command is used to + :raw-latex:`\label{bcommandSetdebug}` + :raw-latex:`\index[general]{Console!Command!setdebug}` + :raw-latex:`\index[general]{Debug!setdebug}` + :raw-latex:`\index[general]{Debug!Windows}` + :raw-latex:`\index[general]{Windows!Debug}` This command is used to set the debug level in each daemon. The form of this command is: - .. raw:: latex + :: - \begin{bconsole}{setdebug} - setdebug level=nnn [trace=0/1 client= | dir | director | storage= | all] - \end{bconsole} + {setdebug} + setdebug level=nnn [trace=0/1 client= | dir | director | storage= | all] Each of the daemons normally has debug compiled into the program, but disabled. There are two ways to enable the debug output. @@ -1666,7 +1584,7 @@ setdebug The second way of getting debug output is to dynamically turn it on using the Console using the - :command:`setdebug level=nnn` command. If none of the + :raw-latex:`\command{setdebug level=nnn}` command. If none of the options are given, the command will prompt you. You can selectively turn on/off debugging in any or all the daemons (i.e. it is not necessary to specify all the components of the above command). @@ -1678,18 +1596,15 @@ setdebug appended to the trace file. You must explicitly delete the file when you are done. - .. raw:: latex + :: - \begin{bconsole}{set Director debug level to 100 and get messages written to his trace file} - *setdebug level=100 trace=1 dir - level=100 trace=1 hangup=0 timestamp=0 tracefilename=/var/lib/bareos/bareos-dir.example.com.trace - \end{bconsole} + {set Director debug level to 100 and get messages written to his trace file} + *setdebug level=100 trace=1 dir + level=100 trace=1 hangup=0 timestamp=0 tracefilename=/var/lib/bareos/bareos-dir.example.com.trace setip - .. _bcommandSetIP: - -.. index:: - triple: General; Console!Command; setip Sets new client + :raw-latex:`\label{bcommandSetIP}` + :raw-latex:`\index[general]{Console!Command!setip}` Sets new client address – if authorized. A console is authorized to use the **SetIP** command only if it has @@ -1699,13 +1614,11 @@ setip console is permitted to use the **SetIP** command to change the Address directive in the Director’s client resource to the IP address of the Console. This permits portables or other machines - using DHCP (non-fixed IP addresses) to “notify” the Director of + using DHCP (non-fixed IP addresses) to "notify" the Director of their current IP address. show - -.. index:: - triple: General; Console!Command; show The show command + :raw-latex:`\index[general]{Console!Command!show}` The show command will list the Director’s resource records as defined in the Director’s configuration. This command is used mainly for debugging purposes by developers. The following keywords are accepted on the @@ -1715,9 +1628,7 @@ show the contents of the catalog. sqlquery - -.. index:: - triple: General; Console!Command; sqlquery The sqlquery + :raw-latex:`\index[general]{Console!Command!sqlquery}` The sqlquery command puts the Console program into SQL query mode where each line you enter is concatenated to the previous line until a semicolon (;) is seen. The semicolon terminates the command, which is then passed @@ -1737,9 +1648,7 @@ sqlquery or SQLite documentation. status - -.. index:: - triple: General; Console!Command; status + :raw-latex:`\index[general]{Console!Command!status}` This command will display the status of all components. For the director, it will display the next jobs that are scheduled during @@ -1749,12 +1658,11 @@ status jobs like average speed or file accounting. The full form of this command is: - .. raw:: latex + :: - \begin{bconsole}{status} - status [all | dir= | director | scheduler | schedule= | - client= | storage= slots | subscriptions] - \end{bconsole} + {status} + status [all | dir= | director | scheduler | schedule= | + client= | storage= slots | subscriptions] If you do a **status dir**, the console will list any currently running jobs, a summary of all jobs scheduled to be run in the next @@ -1771,24 +1679,23 @@ status In the Running Jobs listing, you may find the following types of information: - .. raw:: latex + :: - \begin{bconsole}{} - 2507 Catalog MatouVerify.2004-03-13_05.05.02 is waiting execution - 5349 Full CatalogBackup.2004-03-13_01.10.00 is waiting for higher - priority jobs to finish - 5348 Differe Minou.2004-03-13_01.05.09 is waiting on max Storage jobs - 5343 Full Rufus.2004-03-13_01.05.04 is running - \end{bconsole} + {} + 2507 Catalog MatouVerify.2004-03-13_05.05.02 is waiting execution + 5349 Full CatalogBackup.2004-03-13_01.10.00 is waiting for higher + priority jobs to finish + 5348 Differe Minou.2004-03-13_01.05.09 is waiting on max Storage jobs + 5343 Full Rufus.2004-03-13_01.05.04 is running Looking at the above listing from bottom to top, obviously JobId 5343 (Rufus) is running. JobId 5348 (Minou) is waiting for JobId 5343 to finish because it is using the Storage resource, hence the - “waiting on max Storage jobs”. JobId 5349 has a lower priority than + "waiting on max Storage jobs". JobId 5349 has a lower priority than all the other jobs so it is waiting for higher priority jobs to finish, and finally, JobId 2507 (MatouVerify) is waiting because - only one job can run at a time, hence it is simply “waiting - execution” + only one job can run at a time, hence it is simply "waiting + execution" If you do a **status dir**, it will by default list the first occurrence of all jobs that are scheduled today and tomorrow. If you @@ -1806,43 +1713,42 @@ status storage=xxx**. For example, on an idle test system, when I do **status storage=File**, I get: - .. raw:: latex + :: - \begin{bconsole}{status storage} - *status storage=File - Connecting to Storage daemon File at 192.168.68.112:8103 + {status storage} + *status storage=File + Connecting to Storage daemon File at 192.168.68.112:8103 - rufus-sd Version: 1.39.6 (24 March 2006) i686-pc-linux-gnu redhat (Stentz) - Daemon started 26-Mar-06 11:06, 0 Jobs run since started. + rufus-sd Version: 1.39.6 (24 March 2006) i686-pc-linux-gnu redhat (Stentz) + Daemon started 26-Mar-06 11:06, 0 Jobs run since started. - Running Jobs: - No Jobs running. - ==== + Running Jobs: + No Jobs running. + ==== - Jobs waiting to reserve a drive: - ==== + Jobs waiting to reserve a drive: + ==== - Terminated Jobs: - JobId Level Files Bytes Status Finished Name - ====================================================================== - 59 Full 234 4,417,599 OK 15-Jan-06 11:54 usersave - ==== + Terminated Jobs: + JobId Level Files Bytes Status Finished Name + ====================================================================== + 59 Full 234 4,417,599 OK 15-Jan-06 11:54 usersave + ==== - Device status: - Autochanger "DDS-4-changer" with devices: - "DDS-4" (/dev/nst0) - Device "DDS-4" (/dev/nst0) is mounted with Volume="TestVolume002" - Pool="*unknown*" - Slot 2 is loaded in drive 0. - Total Bytes Read=0 Blocks Read=0 Bytes/block=0 - Positioned at File=0 Block=0 + Device status: + Autochanger "DDS-4-changer" with devices: + "DDS-4" (/dev/nst0) + Device "DDS-4" (/dev/nst0) is mounted with Volume="TestVolume002" + Pool="*unknown*" + Slot 2 is loaded in drive 0. + Total Bytes Read=0 Blocks Read=0 Bytes/block=0 + Positioned at File=0 Block=0 - Device "File" (/tmp) is not open. - ==== + Device "File" (/tmp) is not open. + ==== - In Use Volume status: - ==== - \end{bconsole} + In Use Volume status: + ==== Now, what this tells me is that no jobs are running and that none of the devices are in use. Now, if I **unmount** the autochanger, which @@ -1850,88 +1756,86 @@ status File device, the job will block. When I re-issue the status storage command, I get for the Device status: - .. raw:: latex + :: - \begin{bconsole}{status storage} - *status storage=File - ... - Device status: - Autochanger "DDS-4-changer" with devices: - "DDS-4" (/dev/nst0) - Device "DDS-4" (/dev/nst0) is not open. - Device is BLOCKED. User unmounted. - Drive 0 is not loaded. - - Device "File" (/tmp) is not open. - Device is BLOCKED waiting for media. - ==== - ... - \end{bconsole} + {status storage} + *status storage=File + ... + Device status: + Autochanger "DDS-4-changer" with devices: + "DDS-4" (/dev/nst0) + Device "DDS-4" (/dev/nst0) is not open. + Device is BLOCKED. User unmounted. + Drive 0 is not loaded. + + Device "File" (/tmp) is not open. + Device is BLOCKED waiting for media. + ==== + ... Now, here it should be clear that if a job were running that wanted to use the Autochanger (with two devices), it would block because the user unmounted the device. The real problem for the Job I - started using the “File” device is that the device is blocked + started using the "File" device is that the device is blocked waiting for media – that is Bareos needs you to label a Volume. - The command :command:`status scheduler ` - (12.4.4) can + The command :raw-latex:`\bcommand{status scheduler}{}` + (:raw-latex:`\sinceVersion{console}{status scheduler}{12.4.4}`) can be used to check when a certain schedule will trigger. This gives - more information than :command:`status director `. + more information than :raw-latex:`\bcommand{status director}{}`. Called without parameters, - :command:`status scheduler ` shows a preview for all + :raw-latex:`\bcommand{status scheduler}{}` shows a preview for all schedules for the next 14 days. It first shows a list of the known schedules and the jobs that will be triggered by these jobs, and next, a table with date (including weekday), schedule name and applied overrides is displayed: - .. raw:: latex + :: - \begin{bconsole}{status scheduler} - *status scheduler - Scheduler Jobs: - - Schedule Jobs Triggered - =========================================================== - WeeklyCycle - BackupClient1 - - WeeklyCycleAfterBackup - BackupCatalog - - ==== - - Scheduler Preview for 14 days: - - Date Schedule Overrides - ============================================================== - Di 04-Jun-2013 21:00 WeeklyCycle Level=Incremental - Di 04-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full - Mi 05-Jun-2013 21:00 WeeklyCycle Level=Incremental - Mi 05-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full - Do 06-Jun-2013 21:00 WeeklyCycle Level=Incremental - Do 06-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full - Fr 07-Jun-2013 21:00 WeeklyCycle Level=Incremental - Fr 07-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full - Sa 08-Jun-2013 21:00 WeeklyCycle Level=Differential - Mo 10-Jun-2013 21:00 WeeklyCycle Level=Incremental - Mo 10-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full - Di 11-Jun-2013 21:00 WeeklyCycle Level=Incremental - Di 11-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full - Mi 12-Jun-2013 21:00 WeeklyCycle Level=Incremental - Mi 12-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full - Do 13-Jun-2013 21:00 WeeklyCycle Level=Incremental - Do 13-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full - Fr 14-Jun-2013 21:00 WeeklyCycle Level=Incremental - Fr 14-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full - Sa 15-Jun-2013 21:00 WeeklyCycle Level=Differential - Mo 17-Jun-2013 21:00 WeeklyCycle Level=Incremental - Mo 17-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full - ==== - \end{bconsole} - - :command:`status scheduler` accepts the following + {status scheduler} + *status scheduler + Scheduler Jobs: + + Schedule Jobs Triggered + =========================================================== + WeeklyCycle + BackupClient1 + + WeeklyCycleAfterBackup + BackupCatalog + + ==== + + Scheduler Preview for 14 days: + + Date Schedule Overrides + ============================================================== + Di 04-Jun-2013 21:00 WeeklyCycle Level=Incremental + Di 04-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full + Mi 05-Jun-2013 21:00 WeeklyCycle Level=Incremental + Mi 05-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full + Do 06-Jun-2013 21:00 WeeklyCycle Level=Incremental + Do 06-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full + Fr 07-Jun-2013 21:00 WeeklyCycle Level=Incremental + Fr 07-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full + Sa 08-Jun-2013 21:00 WeeklyCycle Level=Differential + Mo 10-Jun-2013 21:00 WeeklyCycle Level=Incremental + Mo 10-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full + Di 11-Jun-2013 21:00 WeeklyCycle Level=Incremental + Di 11-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full + Mi 12-Jun-2013 21:00 WeeklyCycle Level=Incremental + Mi 12-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full + Do 13-Jun-2013 21:00 WeeklyCycle Level=Incremental + Do 13-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full + Fr 14-Jun-2013 21:00 WeeklyCycle Level=Incremental + Fr 14-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full + Sa 15-Jun-2013 21:00 WeeklyCycle Level=Differential + Mo 17-Jun-2013 21:00 WeeklyCycle Level=Incremental + Mo 17-Jun-2013 21:10 WeeklyCycleAfterBackup Level=Full + ==== + + :raw-latex:`\bcommand{status}{scheduler}` accepts the following parameters: client=clientname @@ -1950,130 +1854,112 @@ status days= can be combined with the other selection criteria. In case you are running a maintained version of Bareos, the command - :command:`status subscriptions` - (12.4.4) + :raw-latex:`\bcommand{status}{subscriptions}` + (:raw-latex:`\sinceVersion{console}{status subscriptions}{12.4.4}`) can help you to keep the overview over the subscriptions that are used. To enable this functionality, just add the configuration - Subscriptions + :raw-latex:`\linkResourceDirective{Dir}{Director}{Subscriptions}` directive and specify the number of subscribed clients, for example: - .. raw:: latex + :: - \begin{bconfig}{enable subscription check} - Director { - ... - Subscriptions = 50 - } - \end{bconfig} + {enable subscription check} + Director { + ... + Subscriptions = 50 + } Using the console command - :command:`status subscriptions`, the status of the + :raw-latex:`\bcommand{status}{subscriptions}`, the status of the subscriptions can be checked any time interactively: - .. raw:: latex + :: - \begin{bconsole}{status subscriptions} - *status subscriptions - Ok: available subscriptions: 8 (42/50) (used/total) - \end{bconsole} + {status subscriptions} + *status subscriptions + Ok: available subscriptions: 8 (42/50) (used/total) Also, the number of subscriptions is checked after every job. If the number of clients is bigger than the configured limit, a Job warning is created a message like this: - .. raw:: latex + :: - \begin{bconsole}{subscriptions warning} - JobId 7: Warning: Subscriptions exceeded: (used/total) (51/50) - \end{bconsole} + {subscriptions warning} + JobId 7: Warning: Subscriptions exceeded: (used/total) (51/50) Please note: Nothing else than the warning is issued, no enforcement on backup, restore or any other operation will happen. Setting the value for - Subscriptions = 0 (Dir configuration, Director resource) + :raw-latex:`\linkResourceDirectiveValue{Dir}{Director}{Subscriptions}{0}` disables this functionality: - .. raw:: latex + :: - \begin{bconfig}{disable subscription check} - Director { - ... - Subscriptions = 0 - } - \end{bconfig} + {disable subscription check} + Director { + ... + Subscriptions = 0 + } Not configuring the directive at all also disables it, as the default value for the Subscriptions directive is zero. time - -.. index:: - triple: General; Console!Command; time The time command + :raw-latex:`\index[general]{Console!Command!time}` The time command shows the current date, time and weekday. trace - -.. index:: - triple: General; Console!Command; trace Turn on/off + :raw-latex:`\index[general]{Console!Command!trace}` Turn on/off trace to file. truncate - -.. index:: - triple: General; Console!Command; truncate - -.. index:: - triple: General; Disk; Freeing disk space - .. index:: SD; Disk!Freeing disk space - .. _bcommandTruncate: - - If the status of a volume is **Purged**, it + :raw-latex:`\index[general]{Console!Command!truncate}` + :raw-latex:`\index[general]{Disk!Freeing disk space}` + :raw-latex:`\index[sd]{Disk!Freeing disk space}` + :raw-latex:`\label{bcommandTruncate}` + + If the status of a volume is :raw-latex:`\volumestatus{Purged}`, it normally still contains data, even so it can not easily be accessed. - .. raw:: latex + :: - \begin{bconsole}{truncate} - truncate volstatus=Purged [storage=] [pool=] [volume=] [yes] - \end{bconsole} + {truncate} + truncate volstatus=Purged [storage=] [pool=] [volume=] [yes] When using a disk volume (and other volume types also) the volume - file still resides on the |bareosSd| . If you want to + file still resides on the |bareosSd|. If you want to reclaim disk space, you can use the - :command:`truncate volstatus=Purged` command. When + :raw-latex:`\bcommand{truncate}{volstatus=Purged}` command. When used on a volume, it rewrites the header and by this frees the rest of the disk space. If the volume you want to get rid of has not the - **Purged** status, you first have to use the - :command:`prune volume` or even the - :command:`purge volume` command to free the volume + :raw-latex:`\volumestatus{Purged}` status, you first have to use the + :raw-latex:`\bcommand{prune}{volume}` or even the + :raw-latex:`\bcommand{purge}{volume}` command to free the volume from all remaining jobs. This command is available since Bareos - 16.2.5. + :raw-latex:`\sinceVersion{dir}{truncate command}{16.2.5}`. umount - -.. index:: - triple: General; Console!Command; umount Alias for - :command:`unmount `. + :raw-latex:`\index[general]{Console!Command!umount}` Alias for + :raw-latex:`\bcommand{unmount}{}`. unmount - -.. index:: - triple: General; Console!Command; unmount This command + :raw-latex:`\index[general]{Console!Command!unmount}` This command causes the indicated Bareos Storage daemon to unmount the specified device. The forms of the command are the same as the mount command: - .. raw:: latex + :: - \begin{bconsole}{unmount} - unmount storage= [drive=] - unmount [jobid= | job=] - \end{bconsole} + {unmount} + unmount storage= [drive=] + unmount [jobid= | job=] Once you unmount a storage device, Bareos will no longer be able to use it until you issue a mount command for that device. If Bareos @@ -2085,13 +1971,11 @@ unmount specified, it will assume drive 1. In most cases, it is preferable to use the - :command:`release ` instead. + :raw-latex:`\bcommand{release}{}` instead. update - -.. index:: - triple: General; Console!Command; update - .. _UpdateCommand: This command will update the + :raw-latex:`\index[general]{Console!Command!update}` + :raw-latex:`\label{UpdateCommand}` This command will update the catalog for either a specific Pool record, a Volume record, or the Slots in an autochanger with barcode capability. In the case of updating a Pool record, the new information will be automatically @@ -2111,11 +1995,13 @@ update - stats In the case of updating a Volume - (:command:`update volume`), you will be prompted for + (:raw-latex:`\bcommand{update}{volume}`), you will be prompted for which value you wish to change. The following Volume parameters may be changed: - + .. raw:: latex + + \footnotesize :: @@ -2135,9 +2021,11 @@ update All Volumes from Pool All Volumes from all Pools - + .. raw:: latex + + \normalsize - For slots :command:`update slots`, Bareos will obtain + For slots :raw-latex:`\bcommand{update}{slots}`, Bareos will obtain a list of slots and their barcodes from the Storage daemon, and for each barcode found, it will automatically update the slot in the catalog Media record to correspond to the new value. This is very @@ -2150,11 +2038,11 @@ update in the autochanger. If you do not have barcodes, you can accomplish the same thing by - using the :command:`update slots scan` command. The - **scan** keyword tells Bareos to physically + using the :raw-latex:`\bcommand{update}{slots scan}` command. The + :raw-latex:`\parameter{scan}` keyword tells Bareos to physically mount each tape and to read its VolumeName. - For Pool :command:`update pool`, Bareos will move the + For Pool :raw-latex:`\bcommand{update}{pool}`, Bareos will move the Volume record from its existing pool to the pool specified. For **Volume from Pool**, **All Volumes from Pool** and **All @@ -2163,93 +2051,84 @@ update MaxVolJobs, MaxVolFiles, and MaxVolBytes. For updating the statistics, use - :command:`updates stats`, see - :ref:`sec:JobStatistics`. + :raw-latex:`\bcommand{updates}{stats}`, see + :raw-latex:`\nameref{sec-JobStatistics}`. The full form of the update command with all command line arguments is: - .. raw:: latex + :: - \begin{bconsole}{update} - update volume= [volstatus=] - [volretention=] [pool=] - [recycle=] [slot=] [inchanger=] | - pool= [maxvolbytes=] [maxvolfiles=] - [maxvoljobs=][enabled=] [recyclepool=] - [actiononpurge=] | - slots [storage=] [scan] | - jobid= [jobname=] [starttime=] - [client=] [filesetid=] - [jobtype=] | - stats [days=] - \end{bconsole} + {update} + update volume= [volstatus=] + [volretention=] [pool=] + [recycle=] [slot=] [inchanger=] | + pool= [maxvolbytes=] [maxvolfiles=] + [maxvoljobs=][enabled=] [recyclepool=] + [actiononpurge=] | + slots [storage=] [scan] | + jobid= [jobname=] [starttime=] + [client=] [filesetid=] + [jobtype=] | + stats [days=] use - -.. index:: - triple: General; Console!Command; use This command + :raw-latex:`\index[general]{Console!Command!use}` This command allows you to specify which Catalog database to use. Normally, you will be using only one database so this will be done automatically. In the case that you are using more than one database, you can use this command to switch from one to another. - .. raw:: latex + :: - \begin{bconsole}{use} - use [catalog=] - \end{bconsole} + {use} + use [catalog=] var - .. _var: - -.. index:: - triple: General; Console!Command; var This command takes + :raw-latex:`\label{var}` + :raw-latex:`\index[general]{Console!Command!var}` This command takes a string or quoted string and does variable expansion on it mostly the same way variable expansion is done on the - Label Format string. - The difference between the :command:`var ` command and + :raw-latex:`\linkResourceDirective{Dir}{Pool}{Label Format}` string. + The difference between the :raw-latex:`\bcommand{var}{}` command and the actual - Label Format process + :raw-latex:`\linkResourceDirective{Dir}{Pool}{Label Format}` process is that during the var command, no job is running so dummy values are used in place of Job specific variables. version - -.. index:: - triple: General; Console!Command; version The command + :raw-latex:`\index[general]{Console!Command!version}` The command prints the Director’s version. wait - -.. index:: - triple: General; Console!Command; wait The wait command + :raw-latex:`\index[general]{Console!Command!wait}` The wait command causes the Director to pause until there are no jobs running. This command is useful in a batch situation such as regression testing where you wish to start a job and wait until that job completes before continuing. This command now has the following options: - .. raw:: latex + :: - \begin{bconsole}{wait} - wait [jobid=] [jobuid=] [job=] - \end{bconsole} + {wait} + wait [jobid=] [jobuid=] [job=] If specified with a specific JobId, ... the wait command will wait for that particular job to terminate before continuing. +.. _dotcommands: + Special dot (.) Commands ~~~~~~~~~~~~~~~~~~~~~~~~ - -.. index:: - triple: General; Console!Command; . commands +:raw-latex:`\index[general]{Console!Command!. commands}` There is a list of commands that are prefixed with a period (.). These commands are intended to be used either by batch programs or graphical user interface front-ends. They are not normally used by interactive users. For details, see :raw-latex:`\bareosDeveloperGuideDotCommands`. +.. _atcommands: + Special At (@) Commands ~~~~~~~~~~~~~~~~~~~~~~~ @@ -2262,22 +2141,20 @@ these commands are implemented only in the TTY console program and not in the Bat Console. These commands are: @input - -.. index:: - triple: General; Console!Command; \at{}input {\textless}filename{\textgreater} + :raw-latex:`\index[general]{Console!Command!\at{}input {\textless}filename{\textgreater}}` Read and execute the commands contained in the file specified. -@output - -.. index:: - triple: General; Console!Command; \at{}output {\textless}filename{\textgreater} {\textless}w{\textbar}a{\textgreater} +@output + :raw-latex:`\index[general]{Console!Command!\at{}output {\textless}filename{\textgreater} {\textless}w{\textbar}a{\textgreater}}` Send all following output to the filename specified either overwriting the file (w) or appending to the file (a). To redirect the output to the terminal, simply enter **@output** without a filename specification. WARNING: be careful not to overwrite a valid file. A typical example during a regression test might be: - + .. raw:: latex + + \footnotesize :: @@ -2285,60 +2162,44 @@ in the Bat Console. These commands are: commands ... @output - + .. raw:: latex + + \normalsize -@tee - -.. index:: - triple: General; Console!Command; \at{}tee {\textless}filename{\textgreater} {\textless}w{\textbar}a{\textgreater} +@tee + :raw-latex:`\index[general]{Console!Command!\at{}tee {\textless}filename{\textgreater} {\textless}w{\textbar}a{\textgreater}}` Send all subsequent output to both the specified file and the terminal. It is turned off by specifying **@tee** or **@output** without a filename. @sleep - -.. index:: - triple: General; Console!Command; \at{}sleep {\textless}seconds{\textgreater} + :raw-latex:`\index[general]{Console!Command!\at{}sleep {\textless}seconds{\textgreater}}` Sleep the specified number of seconds. @time - -.. index:: - triple: General; Console!Command; \at{}time Print the + :raw-latex:`\index[general]{Console!Command!\at{}time}` Print the current time and date. @version - -.. index:: - triple: General; Console!Command; \at{}version Print the + :raw-latex:`\index[general]{Console!Command!\at{}version}` Print the console’s version. @quit - -.. index:: - triple: General; Console!Command; \at{}quit quit + :raw-latex:`\index[general]{Console!Command!\at{}quit}` quit @exit - -.. index:: - triple: General; Console!Command; \at{}exit quit + :raw-latex:`\index[general]{Console!Command!\at{}exit}` quit @# anything - -.. index:: - triple: General; Console!Command; \at{}\# anything + :raw-latex:`\index[general]{Console!Command!\at{}\# anything}` Comment @help - -.. index:: - triple: General; Console!Command; \at{}help Get the list + :raw-latex:`\index[general]{Console!Command!\at{}help}` Get the list of every special @ commands. @separator - -.. index:: - triple: General; Console!Command; \at{}separator When + :raw-latex:`\index[general]{Console!Command!\at{}separator}` When using bconsole with readline, you can set the command separator to one of those characters to write commands who require multiple input on one line, or to put multiple commands on a single line. @@ -2354,11 +2215,11 @@ in the Bat Console. These commands are: Adding Volumes to a Pool ------------------------ +:raw-latex:`\index[general]{Console!Adding a Volume to a Pool}` -.. index:: - triple: General; Console; Adding a Volume to a Pool +.. raw:: latex -:raw-latex:`\TODO{move to another chapter}` + \TODO{move to another chapter} If you have used the **label** command to label a Volume, it will be automatically added to the Pool, and you will not need to add any media @@ -2370,17 +2231,19 @@ without labeling them. At a later time when the Volume is requested by Before adding a volume, you must know the following information: -#. The name of the Pool (normally “Default”) +#. The name of the Pool (normally "Default") #. The Media Type as specified in the Storage Resource in the Director’s - configuration file (e.g. “DLT8000”) + configuration file (e.g. "DLT8000") #. The number and names of the Volumes you wish to create. For example, to add media to a Pool, you would issue the following commands to the console program: +.. raw:: latex + \footnotesize :: @@ -2393,11 +2256,15 @@ commands to the console program: 10 Volumes created in pool Default * +.. raw:: latex + \normalsize To see what you have added, enter: +.. raw:: latex + \footnotesize :: @@ -2418,10 +2285,12 @@ To see what you have added, enter: +-------+----------+---------+---------+-------+------------------+ * +.. raw:: latex + \normalsize Notice that the console program automatically appended a number to the base Volume name that you specify (Save in this case). If you don’t want it to append a number, you can simply answer 0 (zero) to the question -“Enter number of Media volumes to create. Max=1000:”, and in this case, +"Enter number of Media volumes to create. Max=1000:", and in this case, it will create a single Volume with the exact name you specify. diff --git a/docs/manuals/en/new_main_reference/source/bootstrap.rst b/docs/manuals/en/new_main_reference/source/bootstrap.rst index 7bf6be378f9..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/bootstrap.rst +++ b/docs/manuals/en/new_main_reference/source/bootstrap.rst @@ -1,584 +1 @@ -.. _BootstrapChapter: -The Bootstrap File -================== - -.. index:: - triple: General; File; Bootstrap -.. _`File`: - -.. index:: - triple: General; Bootstrap; File -.. _`Bootstrap`: - - -.. raw:: latex - - \TODO{This chapter is going to be rewritten (by Philipp).} - -The information in this chapter is provided so that you may either -create your own bootstrap files, or so that you can edit a bootstrap -file produced by Bareos. However, normally the bootstrap file will be -automatically created for you during the -:command:`restore ` in the Console program, or by using a -**Write Bootstrap** (Dir configuration, Job resource) record in -your Backup Jobs, and thus you will never need to know the details of -this file. - -The **bootstrap** file contains ASCII information that permits precise -specification of what files should be restored, what volume they are on, -and where they are on the volume. It is a relatively compact form of -specifying the information, is human readable, and can be edited with -any text editor. - -Bootstrap File Format ---------------------- - -.. index:: - triple: General; Bootstrap; File Format -.. _`Bootstrap`: - - -The general format of a **bootstrap** file is: - -**= ** - -Where each **keyword** and the **value** specify which files to restore. -More precisely the **keyword** and their **values** serve to limit which -files will be restored and thus act as a filter. The absence of a -keyword means that all records will be accepted. - -Blank lines and lines beginning with a pound sign (#) in the bootstrap -file are ignored. - -There are keywords which permit filtering by Volume, Client, Job, -FileIndex, Session Id, Session Time, ... - -The more keywords that are specified, the more selective the -specification of which files to restore will be. In fact, each keyword -is **AND**\ ed with other keywords that may be present. - -For example, - -.. raw:: latex - - \footnotesize - -:: - - Volume = Test-001 - VolSessionId = 1 - VolSessionTime = 108927638 - -.. raw:: latex - - \normalsize - -directs the Storage daemon (or the **bextract** program) to restore only -those files on Volume Test-001 **AND** having VolumeSessionId equal to -one **AND** having VolumeSession time equal to 108927638. - -The full set of permitted keywords presented in the order in which they -are matched against the Volume records are: - -Volume - .. index:: - triple: General; Bootstrap; Volume - .. _`Bootstrap`: - The value field - specifies what Volume the following commands apply to. Each Volume - specification becomes the current Volume, to which all the following - commands apply until a new current Volume (if any) is specified. If - the Volume name contains spaces, it should be enclosed in quotes. At - lease one Volume specification is required. - -Count - .. index:: - triple: General; Bootstrap; Count - .. _`Bootstrap`: - The value is the total - number of files that will be restored for this Volume. This allows - the Storage daemon to know when to stop reading the Volume. This - value is optional. - -VolFile - .. index:: - triple: General; Bootstrap; VolFile - .. _`Bootstrap`: - The value is a file - number, a list of file numbers, or a range of file numbers to match - on the current Volume. The file number represents the physical file - on the Volume where the data is stored. For a tape volume, this - record is used to position to the correct starting file, and once - the tape is past the last specified file, reading will stop. - -VolBlock - .. index:: - triple: General; Bootstrap; VolBlock - .. _`Bootstrap`: - The value is a - block number, a list of block numbers, or a range of block numbers - to match on the current Volume. The block number represents the - physical block within the file on the Volume where the data is - stored. - -VolSessionTime - .. index:: - triple: General; Bootstrap; VolSessionTime - .. _`Bootstrap`: - The value - specifies a Volume Session Time to be matched from the current - volume. - -VolSessionId - .. index:: - triple: General; Bootstrap; VolSessionId - .. _`Bootstrap`: - The value - specifies a VolSessionId, a list of volume session ids, or a range - of volume session ids to be matched from the current Volume. Each - VolSessionId and VolSessionTime pair corresponds to a unique Job - that is backed up on the Volume. - -JobId - .. index:: - triple: General; Bootstrap; JobId - .. _`Bootstrap`: - The value specifies a - JobId, list of JobIds, or range of JobIds to be selected from the - current Volume. Note, the JobId may not be unique if you have - multiple Directors, or if you have reinitialized your database. The - JobId filter works only if you do not run multiple simultaneous - jobs. This value is optional and not used by Bareos to restore - files. - -Job - .. index:: - triple: General; Bootstrap; Job - .. _`Bootstrap`: - The value specifies a - Job name or list of Job names to be matched on the current Volume. - The Job corresponds to a unique VolSessionId and VolSessionTime - pair. However, the Job is perhaps a bit more readable by humans. - Standard regular expressions (wildcards) may be used to match Job - names. The Job filter works only if you do not run multiple - simultaneous jobs. This value is optional and not used by Bareos to - restore files. - -Client - .. index:: - triple: General; Bootstrap; Client - .. _`Bootstrap`: - The value specifies a - Client name or list of Clients to will be matched on the current - Volume. Standard regular expressions (wildcards) may be used to - match Client names. The Client filter works only if you do not run - multiple simultaneous jobs. This value is optional and not used by - Bareos to restore files. - -FileIndex - .. index:: - triple: General; Bootstrap; FileIndex - .. _`Bootstrap`: - The value - specifies a FileIndex, list of FileIndexes, or range of FileIndexes - to be selected from the current Volume. Each file (data) stored on a - Volume within a Session has a unique FileIndex. For each Session, - the first file written is assigned FileIndex equal to one and - incremented for each file backed up. - - This for a given Volume, the triple VolSessionId, VolSessionTime, - and FileIndex uniquely identifies a file stored on the Volume. - Multiple copies of the same file may be stored on the same Volume, - but for each file, the triple VolSessionId, VolSessionTime, and - FileIndex will be unique. This triple is stored in the Catalog - database for each file. - - To restore a particular file, this value (or a range of FileIndexes) - is required. - -FileRegex - .. index:: - triple: General; Bootstrap; FileRegex - .. _`Bootstrap`: - The value is a - regular expression. When specified, only matching filenames will be - restored. - - :: - - FileRegex=^/etc/passwd(.old)? - -Slot - .. index:: - triple: General; Bootstrap; Slot - .. _`Bootstrap`: - The value specifies the - autochanger slot. There may be only a single **Slot** specification - for each Volume. - -Stream - .. index:: - triple: General; Bootstrap; Stream - .. _`Bootstrap`: - The value specifies a - Stream, a list of Streams, or a range of Streams to be selected from - the current Volume. Unless you really know what you are doing (the - internals of Bareos), you should avoid this specification. This - value is optional and not used by Bareos to restore files. - -The **Volume** record is a bit special in that it must be the first -record. The other keyword records may appear in any order and any number -following a Volume record. - -Multiple Volume records may be specified in the same bootstrap file, but -each one starts a new set of filter criteria for the Volume. - -In processing the bootstrap file within the current Volume, each filter -specified by a keyword is **AND**\ ed with the next. Thus, - -.. raw:: latex - - \footnotesize - -:: - - Volume = Test-01 - Client = "My machine" - FileIndex = 1 - -.. raw:: latex - - \normalsize - -will match records on Volume **Test-01** **AND** Client records for **My -machine** **AND** FileIndex equal to **one**. - -Multiple occurrences of the same record are **OR**\ ed together. Thus, - -.. raw:: latex - - \footnotesize - -:: - - Volume = Test-01 - Client = "My machine" - Client = "Backup machine" - FileIndex = 1 - -.. raw:: latex - - \normalsize - -will match records on Volume **Test-01** **AND** (Client records for -**My machine** **OR** **Backup machine**) **AND** FileIndex equal to -**one**. - -For integer values, you may supply a range or a list, and for all other -values except Volumes, you may specify a list. A list is equivalent to -multiple records of the same keyword. For example, - -.. raw:: latex - - \footnotesize - -:: - - Volume = Test-01 - Client = "My machine", "Backup machine" - FileIndex = 1-20, 35 - -.. raw:: latex - - \normalsize - -will match records on Volume **Test-01** **AND** **(**\ Client records -for **My machine** **OR** **Backup machine**\ **)** **AND** -**(**FileIndex 1 **OR** 2 **OR** 3 ... **OR** 20 **OR** 35\ **)**. - -As previously mentioned above, there may be multiple Volume records in -the same bootstrap file. Each new Volume definition begins a new set of -filter conditions that apply to that Volume and will be **OR**\ ed with -any other Volume definitions. - -As an example, suppose we query for the current set of tapes to restore -all files on Client **Rufus** using the **query** command in the console -program: - -.. raw:: latex - - \footnotesize - -:: - - Using default Catalog name=MySQL DB=bareos - *query - Available queries: - 1: List Job totals: - 2: List where a file is saved: - 3: List where the most recent copies of a file are saved: - 4: List total files/bytes by Job: - 5: List total files/bytes by Volume: - 6: List last 10 Full Backups for a Client: - 7: List Volumes used by selected JobId: - 8: List Volumes to Restore All Files: - Choose a query (1-8): 8 - Enter Client Name: Rufus - +-------+------------------+------------+-----------+----------+------------+ - | JobId | StartTime | VolumeName | StartFile | VolSesId | VolSesTime | - +-------+------------------+------------+-----------+----------+------------+ - | 154 | 2002-05-30 12:08 | test-02 | 0 | 1 | 1022753312 | - | 202 | 2002-06-15 10:16 | test-02 | 0 | 2 | 1024128917 | - | 203 | 2002-06-15 11:12 | test-02 | 3 | 1 | 1024132350 | - | 204 | 2002-06-18 08:11 | test-02 | 4 | 1 | 1024380678 | - +-------+------------------+------------+-----------+----------+------------+ - -.. raw:: latex - - \normalsize - -The output shows us that there are four Jobs that must be restored. The -first one is a Full backup, and the following three are all Incremental -backups. - -The following bootstrap file will restore those files: - -.. raw:: latex - - \footnotesize - -:: - - Volume=test-02 - VolSessionId=1 - VolSessionTime=1022753312 - Volume=test-02 - VolSessionId=2 - VolSessionTime=1024128917 - Volume=test-02 - VolSessionId=1 - VolSessionTime=1024132350 - Volume=test-02 - VolSessionId=1 - VolSessionTime=1024380678 - -.. raw:: latex - - \normalsize - -As a final example, assume that the initial Full save spanned two -Volumes. The output from **query** might look like: - -.. raw:: latex - - \footnotesize - -:: - - +-------+------------------+------------+-----------+----------+------------+ - | JobId | StartTime | VolumeName | StartFile | VolSesId | VolSesTime | - +-------+------------------+------------+-----------+----------+------------+ - | 242 | 2002-06-25 16:50 | File0003 | 0 | 1 | 1025016612 | - | 242 | 2002-06-25 16:50 | File0004 | 0 | 1 | 1025016612 | - | 243 | 2002-06-25 16:52 | File0005 | 0 | 2 | 1025016612 | - | 246 | 2002-06-25 19:19 | File0006 | 0 | 2 | 1025025494 | - +-------+------------------+------------+-----------+----------+------------+ - -.. raw:: latex - - \normalsize - -and the following bootstrap file would restore those files: - -.. raw:: latex - - \footnotesize - -:: - - Volume=File0003 - VolSessionId=1 - VolSessionTime=1025016612 - Volume=File0004 - VolSessionId=1 - VolSessionTime=1025016612 - Volume=File0005 - VolSessionId=2 - VolSessionTime=1025016612 - Volume=File0006 - VolSessionId=2 - VolSessionTime=1025025494 - -.. raw:: latex - - \normalsize - -Automatic Generation of Bootstrap Files ---------------------------------------- - -.. index:: - triple: General; Files; Automatic Generation of Bootstrap -.. _`Files`: - -.. index:: - triple: General; Bootstrap; Automatic Generation -.. _`Bootstrap`: - - -One thing that is probably worth knowing: the bootstrap files that are -generated automatically at the end of the job are not as optimized as -those generated by the restore command. This is because during -Incremental and Differential jobs, the records pertaining to the files -written for the Job are appended to the end of the bootstrap file. As -consequence, all the files saved to an Incremental or Differential job -will be restored first by the Full save, then by any Incremental or -Differential saves. - -When the bootstrap file is generated for the restore command, only one -copy (the most recent) of each file is restored. - -So if you have spare cycles on your machine, you could optimize the -bootstrap files by doing the following: - -.. raw:: latex - - \footnotesize - -:: - - bconsole - restore client=xxx select all - done - no - quit - Backup bootstrap file. - -.. raw:: latex - - \normalsize - -The above will not work if you have multiple FileSets because that will -be an extra prompt. However, the **restore client=xxx select all** -builds the in-memory tree, selecting everything and creates the -bootstrap file. - -The **no** answers the **Do you want to run this (yes/mod/no)** -question. - -Bootstrap for bscan -------------------- - -.. index:: General; bscan -.. _`bscan`: - -.. index:: - triple: General; bscan; bootstrap -.. _`bscan`: - -.. index:: - triple: General; Bootstrap; bscan -.. _`Bootstrap`: - -.. index:: - triple: General; Command; bscan -.. _`Command`: - - - -.. _`bscanBootstrap`: bscanBootstrap - -If you have a very large number of Volumes to scan with **bscan**, you -may exceed the command line limit (511 characters). In that case, you -can create a simple bootstrap file that consists of only the volume -names. An example might be: - -.. raw:: latex - - \footnotesize - -:: - - Volume="Vol001" - Volume="Vol002" - Volume="Vol003" - Volume="Vol004" - Volume="Vol005" - -.. raw:: latex - - \normalsize - -Bootstrap Example ------------------ - -.. index:: - triple: General; Example; Bootstrap -.. _`Example`: - -.. index:: - triple: General; Bootstrap; Example -.. _`Bootstrap`: - - -If you want to extract or copy a single Job, you can do it by selecting -by JobId (code not tested) or better yet, if you know the VolSessionTime -and the VolSessionId (printed on Job report and in Catalog), specifying -this is by far the best. Using the VolSessionTime and VolSessionId is -the way Bareos does restores. A bsr file might look like the following: - -.. raw:: latex - - \footnotesize - -:: - - Volume="Vol001" - VolSessionId=10 - VolSessionTime=1080847820 - -.. raw:: latex - - \normalsize - -If you know how many files are backed up (on the job report), you can -enormously speed up the selection by adding (let’s assume there are 157 -files): - -.. raw:: latex - - \footnotesize - -:: - - FileIndex=1-157 - Count=157 - -.. raw:: latex - - \normalsize - -Finally, if you know the File number where the Job starts, you can also -cause bcopy to forward space to the right file without reading every -record: - -.. raw:: latex - - \footnotesize - -:: - - VolFile=20 - -.. raw:: latex - - \normalsize - -There is nothing magic or complicated about a BSR file. Parsing it and -properly applying it within Bareos \*is\* magic, but you don’t need to -worry about that. - -If you want to see a \*real\* bsr file, simply fire up the **restore** -command in the console program, select something, then answer no when it -prompts to run the job. Then look at the file **restore.bsr** in your -working directory. diff --git a/docs/manuals/en/new_main_reference/source/catmaintenance.rst b/docs/manuals/en/new_main_reference/source/catmaintenance.rst index 8feb7932fdd..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/catmaintenance.rst +++ b/docs/manuals/en/new_main_reference/source/catmaintenance.rst @@ -1,1618 +1 @@ -Catalog Maintenance -=================== - -.. index:: - triple: General; Maintenance; Catalog -.. index:: General; Catalog Maintenance - -Catalog Database ----------------- - -Bareos stores its catalog in a database. Different database backends are -offered: - -- PostgreSQL (recommended) - -- MariaDB/MySQL (see :ref:`sec:MysqlSupport`) - -- Sqlite (only for testing) - -What database will be used, can be configured in the - |bareosDir| configuration, see the -:ref:`DirectorResourceCatalog`. - -The database often runs on the same server as the - |bareosDir| . However, it is also possible to run it on a -different system. This might require some more manual configuration. - -dbconfig-common (Debian) -~~~~~~~~~~~~~~~~~~~~~~~~ - - -.. index:: - triple: General; Platform!Debian; dbconfig-common - -.. index:: - triple: General; Platform!Ubuntu; dbconfig-common -.. _sec:dbconfig: - -Since Bareos -14.2.0 the -Debian (and Ubuntu) based packages support the -**dbconfig-common** mechanism to create and update -the Bareos database, according to the user choices. - -The first choice is, if **dbconfig-common** should be -used at all. If you decide against it, the database must be configured -manually, see :ref:`CatMaintenanceManualConfiguration`. - -If you decided to use **dbconfig-common**, the next -question will only be asked, if more than one Bareos database backend -(**bareos-database-***) is installed. If this is the -case, select the database backend you want to use. - -|image| |image| - -Depending on the selected database backend, more questions about how to -access the database will be asked. Often, the default values are -suitable. - -The **dbconfig-common** configuration (and -credentials) is done by the -**bareos-database-common** package. Settings are -stored in the file -*/etc/dbconfig-common/bareos-database-common.conf*. - -The Bareos database backend will get automatically configured in -*/etc/bareos/bareos-dir.conf*. A later reconfiguration -might require manual adapt changes. - - -.. warning:: - When using the PostgreSQL backend and updating to Bareos $<$ 14.2.3, it is necessary to manually grant database permissions (\command{grant_bareos_privileges}), normally by - -.. raw:: latex - - \begin{commands}{} - su - postgres -c /usr/lib/bareos/scripts/grant_bareos_privileges - \end{commands} - -For details see chapter -:ref:`CatMaintenanceManualConfiguration`. - -Manual Configuration -~~~~~~~~~~~~~~~~~~~~ - -Bareos comes with a number of scripts to prepare and update the -databases. All these scripts are located in the Bareos script directory, -normally at */usr/lib/bareos/scripts/*. - -+-------------------------------------------------+------------------+-------------------------------------------------------+ -| **Script** | **Stage** | **Description** | -+=================================================+==================+=======================================================+ -| *create_bareos_database* | installation | create Bareos database | -+-------------------------------------------------+------------------+-------------------------------------------------------+ -| *make_bareos_tables* | installation | create Bareos tables | -+-------------------------------------------------+------------------+-------------------------------------------------------+ -| *grant_bareos_privileges* | installation | grant database access privileges | -+-------------------------------------------------+------------------+-------------------------------------------------------+ -| *update_bareos_tables* [-f] | update | update the database schema | -+-------------------------------------------------+------------------+-------------------------------------------------------+ -| *drop_bareos_tables* | deinstallation | remove Bareos database tables | -+-------------------------------------------------+------------------+-------------------------------------------------------+ -| *drop_bareos_database* | deinstallation | remove Bareos database | -+-------------------------------------------------+------------------+-------------------------------------------------------+ -| *make_catalog_backup.pl* | backup | backup the Bareos database, default on Linux | -+-------------------------------------------------+------------------+-------------------------------------------------------+ -| *make_catalog_backup* | backup | backup the Bareos database for systems without Perl | -+-------------------------------------------------+------------------+-------------------------------------------------------+ -| *delete_catalog_backup* | backup helper | remove the temporary Bareos database backup file | -+-------------------------------------------------+------------------+-------------------------------------------------------+ - -The database preparation scripts have following configuration options: - -db\_type - - - - command line parameter $1 - - - DB Driver from - the configuration - - - installed database backends - - - fallback: postgresql - -db\_name - - - - environment variable **db_name** - - - DB Name from - the configuration - - - default: bareos - -db\_user - - - - environment variable **db_user** - - - DB User from - the configuration - - - default: bareos - -db\_password - - - - environment variable **db_password** - - - DB Password - from the configuration - - - default: *none* - -Reading the settings from the configuration require read permission for -the current user. The normal PostgreSQL administrator user -(**postgres**) don’t have these permissions. So if you -plan to use non-default database settings, you might add the user -**postgres}` to the group :raw-latex:`\group{bareos**. - -The database preparation scripts need to have password-less -administrator access to the database. Depending on the distribution -you’re using, this require additional configuration. See the following -section about howto achieve this for the different database systems. - -To view and test the currently configured settings, use following -commands: - -.. raw:: latex - - \begin{commands}{Show current database configuration} - /usr/sbin/bareos-dbcheck -B - catalog=MyCatalog - db_name=bareos - db_driver=mysql - db_user=bareos - db_password=YourPassword - db_address= - db_port=0 - db_socket= - db_type=MySQL - working_dir=/var/lib/bareos - \end{commands} - -.. raw:: latex - - \begin{commands}{Test the database connection. Example: wrong password} - /usr/sbin/bareos-dir -t -f -d 500 - [...] - bareos-dir: mysql.c:204-0 Error 1045 (28000): Access denied for user 'bareos'@'localhost' (using password: YES) - bareos-dir: dird.c:1114-0 Could not open Catalog "MyCatalog", database "bareos". - bareos-dir: dird.c:1119-0 mysql.c:200 Unable to connect to MySQL server. - Database=bareos User=bareos - MySQL connect failed either server not running or your authorization is incorrect. - bareos-dir: mysql.c:239-0 closedb ref=0 connected=0 db=0 - 25-Apr 16:25 bareos-dir ERROR TERMINATION - Please correct the configuration in /etc/bareos/bareos-dir.d/*/*.conf - \end{commands} - -PostgreSQL -^^^^^^^^^^ - -On most distributions, PostgreSQL uses ident to allow access to the -database system. The database administrator account is the Unix user -**postgres**. Normally, this user can access the -database without password, as the ident mechanism is used to identify -the user. - -If this works on your system can be verified by - -.. raw:: latex - - \begin{commands}{Access the local PostgreSQL database} - su - postgres - psql - \end{commands} - -If your database is configured to to require a password, this must be -definied in the file -http://www.postgresql.org/docs/8.2/static/libpq-pgpass.html -in the following syntax: -**HOST:PORT:DATABASE:USER:PASSWORD**, e.g. - -.. raw:: latex - - \begin{config}{PostgreSQL access credentials} - localhost:*:bareos:bareos:secret - \end{config} - -The permission of this file must be 0600 -(:command:`chmod 0600 ~/.pgpass`). - -Again, verify that you have specified the correct settings by calling -the :command:`psql` command. If this connects you to the -database, your credentials are good. Exit the PostgreSQL client and run -the Bareos database preparation scripts: - -.. raw:: latex - - \begin{commands}{Setup Bareos catalog database} - su - postgres - /usr/lib/bareos/scripts/create_bareos_database - /usr/lib/bareos/scripts/make_bareos_tables - /usr/lib/bareos/scripts/grant_bareos_privileges - \end{commands} - -The encoding of the bareos database must be -**SQL_ASCII**. The command -:command:`create_bareos_database` automatically creates the -database with this encoding. This can be verified by the command -:command:`psql -l`, which shows information about existing -databases: - -.. raw:: latex - - \begin{commands}{List existing databases} - psql -l - List of databases - Name | Owner | Encoding - -----------+----------+----------- - bareos | postgres | SQL_ASCII - postgres | postgres | UTF8 - template0 | postgres | UTF8 - template1 | postgres | UTF8 - (4 rows) - \end{commands} - -The owner of the database may vary. The Bareos database maintance -scripts don’t change the default owner of the Bareos database, so it -stays at the PostgreSQL administration user. The -:command:`grant_bareos_privileges` script grant the required -permissions to the Bareos database user. In contrast, when installing -(not updating) using :ref:`dbconfig sec:dbconfig`, the -database owner will be identical with the Bareos database user. - -By default, using PostgreSQL ident, a Unix user can access a database of -the same name. Therefore the user **bareos** can access -the database *bareos* - -.. raw:: latex - - \begin{commands}{Verify Bareos database on PostgreSQL as Unix user bareos (bareos-13.2.3)} - root@linux:~# su - bareos -s /bin/sh - bareos@linux:~# psql - Welcome to psql 8.3.23, the PostgreSQL interactive terminal. - - Type: \copyright for distribution terms - \h for help with SQL commands - \? for help with psql commands - \g or terminate with semicolon to execute query - \q to quit - - bareos=> \dt - List of relations - Schema | Name | Type | Owner - --------+------------------------+-------+---------- - public | basefiles | table | postgres - public | cdimages | table | postgres - public | client | table | postgres - public | counters | table | postgres - public | device | table | postgres - public | devicestats | table | postgres - public | file | table | postgres - public | filename | table | postgres - public | fileset | table | postgres - public | job | table | postgres - public | jobhisto | table | postgres - public | jobmedia | table | postgres - public | jobstats | table | postgres - public | location | table | postgres - public | locationlog | table | postgres - public | log | table | postgres - public | media | table | postgres - public | mediatype | table | postgres - public | ndmpjobenvironment | table | postgres - public | ndmplevelmap | table | postgres - public | path | table | postgres - public | pathhierarchy | table | postgres - public | pathvisibility | table | postgres - public | pool | table | postgres - public | quota | table | postgres - public | restoreobject | table | postgres - public | status | table | postgres - public | storage | table | postgres - public | unsavedfiles | table | postgres - public | version | table | postgres - (30 rows) - - bareos=> select * from Version; - versionid - ----------- - 2002 - (1 row) - - bareos=> \du - List of roles - Role name | Superuser | Create role | Create DB | Connections | Member of - ---------------+-----------+-------------+-----------+-------------+----------- - bareos | no | no | no | no limit | {} - postgres | yes | yes | yes | no limit | {} - (2 rows) - - bareos=> \dp - Access privileges for database "bareos" - Schema | Name | Type | Access privileges - --------+-----------------------------------+----------+-------------------------------------- - public | basefiles | table | {root=arwdxt/root,bareos=arwdxt/root} - public | basefiles_baseid_seq | sequence | {root=rwU/root,bareos=rw/root} - ... - - bareos=> - \end{commands} - -MySQL -^^^^^ - -MySQL user authentication is username, password and host-based. The -database administrator is the user **root**. - -On some distributions access to the MySQL database is allowed -password-less as database user **root**, on other -distributions, a password is required. On productive systems you -normally want to have password secured access. - -The bareos database preparation scripts require password-less access to -the database. To guarantee this, create a MySQL credentials file -http://dev.mysql.com/doc/refman/4.1/en/password-security.html -with the credentials of the database administrator: - -.. raw:: latex - - \begin{config}{MySQL credentials file .my.cnf} - [client] - host=localhost - user=root - password=YourPasswordForAccessingMysqlAsRoot - \end{config} - -Alternatively you can specifiy your database password by adding it to -the file */etc/my.cnf*. - -Verify that you have specified the correct settings by calling the -:command:`mysql` command. If this connects you to the -database, your credentials are good. Exit the MySQL client. - -For the Bareos database connection, you should specify a database -password. Otherwise the Bareos database user gets the permission to -connect without password. This is not recommended. Choose a database -password and add it into the Bareos Director configuration file -*/etc/bareos/bareos-dir.conf*: - -.. raw:: latex - - \begin{bconfig}{Bareos catalog configuration} - ... - # - # Generic catalog service - # - Catalog { - Name = MyCatalog - dbdriver = "mysql" - dbname = "bareos" - dbuser = "bareos" - dbpassword = "YourSecretPassword" - } - ... - \end{bconfig} - -After this, run the Bareos database preparation scripts. For Bareos -:math:`<=` 13.2.2, the database password must be specified as -environment variable **db_password**. From -13.2.3 -the database password is read from the configuration, if no environment -variable is given. - -.. raw:: latex - - \begin{commands}{Setup Bareos catalog database} - export db_password=YourSecretPassword - /usr/lib/bareos/scripts/create_bareos_database - /usr/lib/bareos/scripts/make_bareos_tables - /usr/lib/bareos/scripts/grant_bareos_privileges - \end{commands} - -After this, you can use the :command:`mysql` command to -verify that your database setup is okay and works with your the Bareos -database user. The result should look similar as this (here Bareos 13.2 -is used on SLES11): - -.. raw:: latex - - \begin{commands}{Verify Bareos database on MySQL} - root@linux:~# mysql --user=bareos --password=YourSecretPassword bareos - Welcome to the MySQL monitor. Commands end with ; or \g. - Your MySQL connection id is 162 - Server version: 5.5.32 SUSE MySQL package - - Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. - - Oracle is a registered trademark of Oracle Corporation and/or its - affiliates. Other names may be trademarks of their respective - owners. - - Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. - - mysql> show tables; - +--------------------+ - | Tables_in_bareos | - +--------------------+ - | BaseFiles | - | CDImages | - | Client | - | Counters | - | Device | - | DeviceStats | - | File | - | FileSet | - | Filename | - | Job | - | JobHisto | - | JobMedia | - | JobStats | - | Location | - | LocationLog | - | Log | - | Media | - | MediaType | - | NDMPJobEnvironment | - | NDMPLevelMap | - | Path | - | PathHierarchy | - | PathVisibility | - | Pool | - | Quota | - | RestoreObject | - | Status | - | Storage | - | UnsavedFiles | - | Version | - +--------------------+ - 30 rows in set (0.00 sec) - - mysql> describe Job; - +-----------------+---------------------+------+-----+---------+----------------+ - | Field | Type | Null | Key | Default | Extra | - +-----------------+---------------------+------+-----+---------+----------------+ - | JobId | int(10) unsigned | NO | PRI | NULL | auto_increment | - | Job | tinyblob | NO | | NULL | | - | Name | tinyblob | NO | MUL | NULL | | - | Type | binary(1) | NO | | NULL | | - | Level | binary(1) | NO | | NULL | | - | ClientId | int(11) | YES | | 0 | | - | JobStatus | binary(1) | NO | | NULL | | - | SchedTime | datetime | YES | | NULL | | - | StartTime | datetime | YES | | NULL | | - | EndTime | datetime | YES | | NULL | | - | RealEndTime | datetime | YES | | NULL | | - | JobTDate | bigint(20) unsigned | YES | | 0 | | - | VolSessionId | int(10) unsigned | YES | | 0 | | - | VolSessionTime | int(10) unsigned | YES | | 0 | | - | JobFiles | int(10) unsigned | YES | | 0 | | - | JobBytes | bigint(20) unsigned | YES | | 0 | | - | ReadBytes | bigint(20) unsigned | YES | | 0 | | - | JobErrors | int(10) unsigned | YES | | 0 | | - | JobMissingFiles | int(10) unsigned | YES | | 0 | | - | PoolId | int(10) unsigned | YES | | 0 | | - | FileSetId | int(10) unsigned | YES | | 0 | | - | PriorJobId | int(10) unsigned | YES | | 0 | | - | PurgedFiles | tinyint(4) | YES | | 0 | | - | HasBase | tinyint(4) | YES | | 0 | | - | HasCache | tinyint(4) | YES | | 0 | | - | Reviewed | tinyint(4) | YES | | 0 | | - | Comment | blob | YES | | NULL | | - +-----------------+---------------------+------+-----+---------+----------------+ - 27 rows in set (0,00 sec) - - mysql> select * from Version; - +-----------+ - | VersionId | - +-----------+ - | 2002 | - +-----------+ - 1 row in set (0.00 sec) - - mysql> exit - Bye - \end{commands} - -Modify database credentials -''''''''''''''''''''''''''' - -If you want to change the Bareos database credentials, do the following: - -- stop the Bareos director - -- modify the configuration - -- rerun the grant script :command:`grant_bareos_privileges` - (or modify database user directly) - -- start the Bareos director - -Modify the configuration, set a new password: - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-dir}{Catalog}{MyCatalog} - Catalog { - Name = MyCatalog - dbdriver = "mysql" - dbname = "bareos" - dbuser = "bareos" - dbpassword = "MyNewSecretPassword" - } - \end{bareosConfigResource} - -Rerun the Bareos grant script -:command:`grant_bareos_privileges` ... - -.. raw:: latex - - \begin{commands}{Modify database privileges} - export db_password=MyNewSecretPassword - /usr/lib/bareos/scripts/grant_bareos_privileges - \end{commands} - -:raw-latex:`\hide{ -% table and commands have changed in MySQL 5.7.6. -% As things now get more complicated (different command for different version) -% we skip this topic here. -... or modify the database users directly: - -\begin{commands}{Show Bareos database users} -mysql -mysql> SELECT user,host,password FROM mysql.user WHERE user='bareos'; -+--------+-----------+-------------------------------------------+ -| user | host | password | -+--------+-----------+-------------------------------------------+ -| bareos | 127.0.0.1 | *CD8C42695AC221807E2BA599FC392C650155C16C | -| bareos | localhost | *CD8C42695AC221807E2BA599FC392C650155C16C | -| bareos | ::1 | *CD8C42695AC221807E2BA599FC392C650155C16C | -+--------+-----------+-------------------------------------------+ -3 rows in set (0.00 sec) - -mysql> UPDATE mysql.user SET Password=PASSWORD('MyNewSecretPassword') where User='bareos'; -Query OK, 3 rows affected (0.00 sec) -Rows matched: 3 Changed: 3 Warnings: 0 - -mysql> FLUSH PRIVILEGES; -Query OK, 0 rows affected (0.00 sec) - -mysql> SELECT user,host,password FROM mysql.user WHERE user='bareos'; -+--------+-----------+-------------------------------------------+ -| user | host | password | -+--------+-----------+-------------------------------------------+ -| bareos | 127.0.0.1 | *2119D34B0C0F7452E952EE3A73A7CAA30C1B1852 | -| bareos | localhost | *2119D34B0C0F7452E952EE3A73A7CAA30C1B1852 | -| bareos | ::1 | *2119D34B0C0F7452E952EE3A73A7CAA30C1B1852 | -+--------+-----------+-------------------------------------------+ -3 rows in set (0.00 sec) - -mysql> -\end{commands} -}` - -Sqlite -^^^^^^ - -There are different versions of Sqlite available. When we use the term -Sqlite, we will always refer to Sqlite3. - -Sqlite is a file based database. Access via network connection is not -supported. Because its setup is easy, it is a good database for testing. -However please don’t use it in a production environment. - -Sqlite stores a database in a single file. Bareos creates this file at -*/var/lib/bareos/bareos.db*. - -Sqlite does not offer access permissions. The only permissions that do -apply are the Unix file permissions. - -The database is accessable by following command: - -.. raw:: latex - - \begin{commands}{Verify Bareos database on Sqlite3 (bareos-13.2.3)} - sqlite3 /var/lib/bareos/bareos.db - SQLite version 3.7.6.3 - Enter ".help" for instructions - Enter SQL statements terminated with a ";" - sqlite> .tables - BaseFiles Filename Media Pool - CDImages Job MediaType Quota - Client JobHisto NDMPJobEnvironment RestoreObject - Counters JobMedia NDMPLevelMap Status - Device JobStats NextId Storage - DeviceStats Location Path UnsavedFiles - File LocationLog PathHierarchy Version - FileSet Log PathVisibility - sqlite> select * from Version; - 2002 - sqlite> - \end{commands} - -Retention Periods ------------------ - -Database Size -~~~~~~~~~~~~~ - - -.. index:: - triple: General; Size; Database -.. index:: General; Database Size - -As mentioned above, if you do not do automatic pruning, your Catalog -will grow each time you run a Job. Normally, you should decide how long -you want File records to be maintained in the Catalog and set the **File -Retention** period to that time. Then you can either wait and see how -big your Catalog gets or make a calculation assuming approximately 154 -bytes for each File saved and knowing the number of Files that are saved -during each backup and the number of Clients you backup. - -For example, suppose you do a backup of two systems, each with 100,000 -files. Suppose further that you do a Full backup weekly and an -Incremental every day, and that the Incremental backup typically saves -4,000 files. The size of your database after a month can roughly be -calculated as: - - - -:: - - Size = 154 * No. Systems * (100,000 * 4 + 10,000 * 26) - - - -where we have assumed four weeks in a month and 26 incremental backups -per month. This would give the following: - - - -:: - - Size = 154 * 2 * (100,000 * 4 + 10,000 * 26) = 203,280,000 bytes - - - -So for the above two systems, we should expect to have a database size -of approximately 200 Megabytes. Of course, this will vary according to -how many files are actually backed up. - -You will note that the File table (containing the file attributes) make -up the large bulk of the number of records as well as the space used. As -a consequence, the most important Retention period will be the **File -Retention** period. - -Without proper setup and maintenance, your Catalog may continue to grow -indefinitely as you run Jobs and backup Files, and/or it may become very -inefficient and slow. How fast the size of your Catalog grows depends on -the number of Jobs you run and how many files they backup. By deleting -records within the database, you can make space available for the new -records that will be added during the next Job. By constantly deleting -old expired records (dates older than the Retention period), your -database size will remain constant. - -Setting Retention Periods -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. index:: General; Setting Retention Periods - -.. index:: - triple: General; Periods; Setting Retention -.. _Retention: - -Bareos uses three Retention periods: the **File Retention** period, the -**Job Retention** period, and the **Volume Retention** period. Of these -three, the File Retention period is by far the most important in -determining how large your database will become. - -The **File Retention** and the **Job Retention** are specified in each -Client resource as is shown below. The **Volume Retention** period is -specified in the Pool resource, and the details are given in the next -chapter of this manual. - -.. raw:: latex - - \begin{description} - - \item [File Retention = {\textless}time-period-specification{\textgreater}] - \index[general]{File Retention} - \index[general]{Retention!File} - The File Retention record defines the length of time that Bareos will keep - File records in the Catalog database. When this time period expires, and if - {\bf AutoPrune} is set to {\bf yes}, Bareos will prune (remove) File records - that are older than the specified File Retention period. The pruning will - occur at the end of a backup Job for the given Client. Note that the Client - database record contains a copy of the File and Job retention periods, but - Bareos uses the current values found in the Director's Client resource to do - the pruning. - - Since File records in the database account for probably 80 percent of the - size of the database, you should carefully determine exactly what File - Retention period you need. Once the File records have been removed from - the database, you will no longer be able to restore individual files - in a Job. However, as long as the - Job record still exists, you will be able to restore all files in the - job. - - Retention periods are specified in seconds, but as a convenience, there are - a number of modifiers that permit easy specification in terms of minutes, - hours, days, weeks, months, quarters, or years on the record. See the - \ilink{Configuration chapter}{Time} of this manual for additional details - of modifier specification. - - The default File retention period is 60 days. - - \item [Job Retention = {\textless}time-period-specification{\textgreater}] - \index[general]{Job!Retention} - \index[general]{Retention!Job} - The Job Retention record defines the length of time that {\bf Bareos} - will keep Job records in the Catalog database. When this time period - expires, and if {\bf AutoPrune} is set to {\bf yes} Bareos will prune - (remove) Job records that are older than the specified Job Retention - period. Note, if a Job record is selected for pruning, all associated File - and JobMedia records will also be pruned regardless of the File Retention - period set. As a consequence, you normally will set the File retention - period to be less than the Job retention period. - - As mentioned above, once the File records are removed from the database, - you will no longer be able to restore individual files from the Job. - However, as long as the Job record remains in the database, you will be - able to restore all the files backuped for the Job. - As a consequence, it is generally a good idea to retain the Job - records much longer than the File records. - - The retention period is specified in seconds, but as a convenience, there - are a number of modifiers that permit easy specification in terms of - minutes, hours, days, weeks, months, quarters, or years. - See the \ilink{Configuration chapter}{Time} of this manual for additional details of - modifier specification. - - The default Job Retention period is 180 days. - - \item \linkResourceDirective{Dir}{Client}{Auto Prune} - \index[general]{AutoPrune} - \index[general]{Job!Retention!AutoPrune} - If set to {\bf yes}, - Bareos will automatically apply - the File retention period and the Job retention period for the Client at the - end of the Job. - If you turn this off by setting it to {\bf no}, your Catalog will grow each - time you run a Job. - \end{description} - -Job Statistics -^^^^^^^^^^^^^^ - -.. index:: General; Statistics - -.. index:: - triple: General; Job; Statistics - -Bareos catalog contains lot of information about your IT infrastructure, -how many files, their size, the number of video or music files etc. -Using Bareos catalog during the day to get them permit to save resources -on your servers. - -In this chapter, you will find tips and information to measure Bareos -efficiency and report statistics. - -If you want to have statistics on your backups to provide some Service -Level Agreement indicators, you could use a few SQL queries on the Job -table to report how many: - -- jobs have run - -- jobs have been successful - -- files have been backed up - -- ... - -However, these statistics are accurate only if your job retention is -greater than your statistics period. Ie, if jobs are purged from the -catalog, you won’t be able to use them. - -Now, you can use the :command:`update stats [days=num]` -console command to fill the JobHistory table with new Job records. If -you want to be sure to take in account only good jobs, ie if one of your -important job has failed but you have fixed the problem and restarted it -on time, you probably want to delete the first bad job record and keep -only the successful one. For that simply let your staff do the job, and -update JobHistory table after two or three days depending on your -organization using the **[days=num]** option. - -These statistics records aren’t used for restoring, but mainly for -capacity planning, billings, etc. - -The -Statistics Retention -defines the length of time that Bareos will keep statistics job records -in the Catalog database after the Job End time. This information is -stored in the ``JobHistory`` table. When this time period expires, and -if user runs :command:`prune stats` command, Bareos will -prune (remove) Job records that are older than the specified period. - -You can use the following Job resource in your nightly -**BackupCatalog** job to maintain statistics. - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-dir}{Job}{BackupCatalog} - Job { - Name = BackupCatalog - ... - RunScript { - Console = "update stats days=3" - Console = "prune stats yes" - RunsWhen = After - RunsOnClient = no - } - } - \end{bareosConfigResource} - -PostgreSQL ----------- - - -.. index:: - triple: General; Database; PostgreSQL -.. index:: General; PostgreSQL - -Compacting Your PostgreSQL Database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -.. index:: - triple: General; Database!PostgreSQL; Compacting -.. _CompactingPostgres: - -Over time, as noted above, your database will tend to grow until Bareos -starts deleting old expired records based on retention periods. After -that starts, it is expected that the database size remains constant, -provided that the amount of clients and files being backed up is -constant. - -Note that PostgreSQL uses multiversion concurrency control (MVCC), so -that an UPDATE or DELETE of a row does not immediately remove the old -version of the row. Space occupied by outdated or deleted row versions -is only reclaimed for reuse by new rows when running **VACUUM**. Such -outdated or deleted row versions are also referred to as *dead tuples*. - -Since PostgreSQL Version 8.3, autovacuum is enabled by default, so that -setting up a cron job to run VACUUM is not necesary in most of the -cases. Note that there are two variants of VACUUM: standard VACUUM and -VACUUM FULL. Standard VACUUM only marks old row versions for reuse, it -does not free any allocated disk space to the operating system. Only -VACUUM FULL can free up disk space, but it requires exclusive table -locks so that it can not be used in parallel with production database -operations and temporarily requires up to as much additional disk space -that the table being processed occupies. - -All database programs have some means of writing the database out in -ASCII format and then reloading it. Doing so will re-create the database -from scratch producing a compacted result, so below, we show you how you -can do this for PostgreSQL. - -For a PostgreSQL database, you could write the Bareos database as an -ASCII file (*bareos.sql*) then reload it by doing the -following: - -.. raw:: latex - - \begin{commands}{} - pg_dump -c bareos > bareos.sql - cat bareos.sql | psql bareos - rm -f bareos.sql - \end{commands} - -Depending on the size of your database, this will take more or less time -and a fair amount of disk space. For example, you can -:command:`cd` to the location of the Bareos database -(typically */var/lib/pgsql/data* or possible -*/usr/local/pgsql/data*) and check the size. - -Except from special cases PostgreSQL does not need to be dumped/restored -to keep the database efficient. A normal process of vacuuming will -prevent the database from getting too large. If you want to fine-tweak -the database storage, commands such as VACUUM, VACUUM FULL, REINDEX, and -CLUSTER exist specifically to keep you from having to do a dump/restore. - -More details on this subject can be found in the PostgreSQL -documentation. The page http://www.postgresql.org/docs/ contains links -to the documentation for all PostgreSQL versions. The section *Routine -Vacuuming* explains how VACUUM works and why it is required, see -http://www.postgresql.org/docs/current/static/routine-vacuuming.html for -the current PostgreSQL version. - -What To Do When The Database Keeps Growing -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Especially when a high number of files are beeing backed up or when -working with high retention periods, it is probable that autovacuuming -will not work. When starting to use Bareos with an empty Database, it is -normal that the file table and other tables grow, but the growth rate -should drop as soon as jobs are deleted by retention or pruning. The -file table is usually the largest table in Bareos. - -The reason for autovacuuming not beeing triggered is then probably the -default setting of ``autovacuum_vacuum_scale_factor = 0.2``, the current -value can be shown with the following query or looked up in -``postgresql.conf``: - -.. raw:: latex - - \begin{commands}{SQL statement to show the autovacuum\_vacuum\_scale\_factor parameter} - bareos=# show autovacuum_vacuum_scale_factor; - autovacuum_vacuum_scale_factor - -------------------------------- - 0.2 - (1 row) - \end{commands} - -In essence, this means that a VACUUM is only triggered when 20% of table -size are obsolete. Consequently, the larger the table is, the less -frequently VACUUM will be triggered by autovacuum. This make sense -because vacuuming has a performance impact. While it is possible to -override the autovacuum parameters on a table-by-table basis, it can -then still be triggered at any time. - -To learn more details about autovacuum see -http://www.postgresql.org/docs/current/static/routine-vacuuming.html#AUTOVACUUM - -The following example shows how to configure running VACUUM on the file -table by using an admin-job in Bareos. The job will be scheduled to run -at a time that should not run in parallel with normal backup jobs, here -by scheduling it to run after the BackupCatalog job. - -First step is to check the amount of dead tuples and if autovacuum -triggers VACUUM: - -.. raw:: latex - - \begin{commands}{Check dead tuples and vacuuming on PostgreSQL} - bareos=# SELECT relname, n_dead_tup, last_vacuum, last_autovacuum, last_analyze, last_autoanalyze - FROM pg_stat_user_tables WHERE n_dead_tup > 0 ORDER BY n_dead_tup DESC; - -[ RECORD 1 ]----+------------------------------ - relname | file - n_dead_tup | 2955116 - last_vacuum | - last_autovacuum | - last_analyze | - last_autoanalyze | - -[ RECORD 2 ]----+------------------------------ - relname | log - n_dead_tup | 111298 - last_vacuum | - last_autovacuum | - last_analyze | - last_autoanalyze | - -[ RECORD 3 ]----+------------------------------ - relname | job - n_dead_tup | 1785 - last_vacuum | - last_autovacuum | 2015-01-08 01:13:20.70894+01 - last_analyze | - last_autoanalyze | 2014-12-27 18:00:58.639319+01 - ... - \end{commands} - -In the above example, the file table has a high number of dead tuples -and it has not been vacuumed. Same for the log table, but the dead tuple -count is not very high. On the job table autovacuum has been triggered. - -Note that the statistics views in PostgreSQL are not persistent, their -values are reset on restart of the PostgreSQL service. - -To setup a scheduled admin job for vacuuming the file table, the -following must be done: - -#. | Create a file with the SQL statements for example - | ``/usr/local/lib/bareos/scripts/postgresql_file_table_maintenance.sql`` - | with the following content: - - .. raw:: latex - - \begin{commands}{SQL Script for vacuuming the file table on PostgreSQL} - \t \x - SELECT relname, n_dead_tup, last_vacuum, last_autovacuum, last_analyze, last_autoanalyze - FROM pg_stat_user_tables WHERE relname='file'; - VACUUM VERBOSE ANALYZE file; - SELECT relname, n_dead_tup, last_vacuum, last_autovacuum, last_analyze, last_autoanalyze - FROM pg_stat_user_tables WHERE relname='file'; - \t \x - SELECT table_name, - pg_size_pretty(pg_total_relation_size(table_name)) AS total_sz, - pg_size_pretty(pg_total_relation_size(table_name) - pg_relation_size(table_name)) AS idx_sz - FROM ( SELECT ('"' || relname || '"' ) AS table_name - FROM pg_stat_user_tables WHERE relname != 'batch' ) AS all_tables - ORDER BY pg_total_relation_size(table_name) DESC LIMIT 5; - \end{commands} - - The SELECT statements are for informational purposes only, the final - statement shows the total and index disk usage of the 5 largest - tables. - -#. | Create a shell script that runs the SQL statements, for example - | ``/usr/local/lib/bareos/scripts/postgresql_file_table_maintenance.sh`` - | with the following content: - - .. raw:: latex - - \begin{commands}{SQL Script for vacuuming the file table on PostgreSQL} - #!/bin/sh - psql bareos < /usr/local/lib/bareos/scripts/postgresql_file_table_maintenance.sql - \end{commands} - -#. As in PostgreSQL only the database owner or a database superuser is - allowed to run VACUUM, the script will be run as the ``postgres`` - user. To permit the ``bareos`` user to run the script via ``sudo``, - write the following sudo rule to a file by executing - ``visudo -f /etc/sudoers.d/bareos_postgres_vacuum``: - - .. raw:: latex - - \begin{commands}{sudo rule for allowing bareos to run a script as postgres} - bareos ALL = (postgres) NOPASSWD: /usr/local/lib/bareos/scripts/postgresql_file_table_maintenance.sh - \end{commands} - - and make sure that ``/etc/sudoers`` includes it, usually by the line - - - :: - - #includedir /etc/sudoers.d - - - -#. Create the following admin job in the director configuration - - .. raw:: latex - - \begin{commands}{SQL Script for vacuuming the file table on PostgreSQL} - # PostgreSQL file table maintenance job - Job { - Name = FileTableMaintJob - JobDefs = DefaultJob - Schedule = "WeeklyCycleAfterBackup" - Type = Admin - Priority = 20 - - RunScript { - RunsWhen = Before - RunsOnClient = no - Fail Job On Error = yes - Command = "sudo -u postgres /usr/local/lib/bareos/scripts/postgresql_file_table_maintenance.sh" - } - } - \end{commands} - - In this example the job will be run by the schedule - WeeklyCycleAfterBackup, the ``Priority`` should be set to a higher - value than ``Priority`` in the BackupCatalog job. - -Repairing Your PostgreSQL Database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -.. index:: - triple: General; Database; Repairing Your PostgreSQL -.. index:: General; Repairing Your PostgreSQL Database - -The same considerations apply as for -:ref:`RepairingMySQL`. Consult the PostgreSQL documents -for how to repair the database. - -For Bareos specific problems, consider using -:ref:`bareos-dbcheck` program. - -MySQL/MariaDB -------------- - - -.. index:: - triple: General; Database; MySQL -.. index:: General; MySQL - -MySQL/MariaDB Support -~~~~~~~~~~~~~~~~~~~~~ - -.. index:: General; MariaDB|see{MySQL} -.. _sec:MysqlSupport: - -As MariaDB is a fork of MySQL, we use MySQL as synonym for MariaDB and -fully support it. We test our packages against the preferred MySQL fork -that a distribution provides. - -:raw-latex:`\hide{ -supporting MySQL >= 5.7 since bareos-17.2.4 -\limitation{MySQL}{MySQL $\geq$ 5.7 not supported}{% -MySQL 5.7 did change it behavior in some respects. The result is, that the Bareos database creation scripts do not work any more. -For the time being, we advise to use MariaDB instead, which is also the default on most Linux distributions. -See \ticket{705}. -} -}` - -Compacting Your MySQL Database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -.. index:: - triple: General; Database!MySQL; Compacting -.. _CompactingMySQL: - -Over time, as noted above, your database will tend to grow. Even though -Bareos regularly prunes files, **MySQL** does not automatically reuse -the space, and instead continues growing. - -It is assumed that you are using the **InnoDB** database engine (which -is the default since MySQL Version 5.5). - -It is recommended that you use the **OPTIMIZE TABLE** and **ANALYZE -TABLE** statements regularly. This is to make sure that all indices are -up to date and to recycle space inside the database files. - -You can do this via the **mysqlcheck** command: - - -:: - - mysqlcheck -a -o -A - - - -Please note that the database files are never shrunk by **MySQL**. If -you really need to shrink the database files, you need to recreate the -database. This only works if you use per-table tablespaces by setting -the **innodb\_file\_per\_table** configuration option. See -:raw-latex:`\elink{http://dev.mysql.com/doc/refman/5.5/en/innodb-multiple-tablespaces.html} -{http://dev.mysql.com/doc/refman/5.5/en/innodb-multiple-tablespaces.html}` -for details. - -:raw-latex:`\hide{ -\footnotesize -\begin{verbatim} -mysqldump -f --opt bareos > bareos.sql -mysql bareos < bareos.sql -rm -f bareos.sql -\end{verbatim} -\normalsize - -Depending on the size of your database, this will take more or less time and a -fair amount of disk space. -}` - -Repairing Your MySQL Database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -.. index:: - triple: General; Database; Repairing Your MySQL -.. index:: General; Repairing Your MySQL Database -.. _RepairingMySQL: - -If you find that you are getting errors writing to your MySQL database, -or Bareos hangs each time it tries to access the database, you should -consider running MySQL’s database check and repair routines. - -This can be done by running the :command:`mysqlcheck` -command: - -:: - - mysqlcheck --all-databases - - - -If the errors you are getting are simply SQL warnings, then you might -try running :command:`bareos-dbcheck` before (or possibly -after) using the MySQL database repair program. It can clean up many of -the orphaned record problems, and certain other inconsistencies in the -Bareos database. - -A typical cause of MySQL database problems is if your partition fills. -In such a case, you will need to create additional space on the -partition. - -MySQL Table is Full -~~~~~~~~~~~~~~~~~~~ - - -.. index:: - triple: General; Database; MySQL Table is Full -.. index:: General; MySQL Table is Full - -If you are running into the error **The table ’File’ is full ...**, it -is probably because on version 4.x MySQL, the table is limited by -default to a maximum size of 4 GB and you have probably run into the -limit. The solution can be found at: -:raw-latex:`\elink{http://dev.mysql.com/doc/refman/5.0/en/full-table.html} -{http://dev.mysql.com/doc/refman/5.0/en/full-table.html}` - -You can display the maximum length of your table with: - - - -:: - - mysql bareos - SHOW TABLE STATUS FROM bareos like "File"; - - - -If the column labeled “Max\_data\_length” is around 4Gb, this is likely -to be the source of your problem, and you can modify it with: - - - -:: - - mysql bareos - ALTER TABLE File MAX_ROWS=281474976710656; - - - -MySQL Server Has Gone Away -~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -.. index:: - triple: General; Database; MySQL Server Has Gone Away -.. index:: General; MySQL Server Has Gone Away If you are -having problems with the MySQL server disconnecting or with messages -saying that your MySQL server has gone away, then please read the MySQL -documentation, which can be found at: - -:raw-latex:`\elink{http://dev.mysql.com/doc/refman/5.0/en/gone-away.html} -{http://dev.mysql.com/doc/refman/5.0/en/gone-away.html}` - -MySQL Temporary Tables -~~~~~~~~~~~~~~~~~~~~~~ - -When doing backups with large numbers of files, MySQL creates some -temporary tables. When these tables are small they can be held in system -memory, but as they approach some size, they spool off to disk. The -default location for these temp tables is /tmp. Once that space fills -up, Bareos daemons such as the Storage daemon doing spooling can get -strange errors. E.g. - - - -:: - - Fatal error: spool.c:402 Spool data read error. - Fatal error: backup.c:892 Network send error to SD. ERR=Connection reset by - peer - - - -What you need to do is setup MySQL to use a different (larger) temp -directory, which can be set in the /etc/my.cnf with these variables set: - - - -:: - - tmpdir=/path/to/larger/tmpdir - bdb_tmpdir=/path/to/larger/tmpdir - - - -MySQL: Lock Wait Timeout -~~~~~~~~~~~~~~~~~~~~~~~~ - -In large environments, the Bareos |mysql| backend may run in -a lock wait timeout. This can be seen as Bareos message, e.g.: - -.. raw:: latex - - \begin{bmessage}{Bareos error message because of \mysql lock time timeout} - Fatal error: sql_create.c:899 Fill File table Query failed: INSERT INTO File (FileIndex, JobId, PathId, FilenameId, LStat, MD5, DeltaSeq) SELECT batch.FileIndex, batch.JobId, Path.PathId, Filename.FilenameId,batch.LStat, batch.MD5, batch.DeltaSeq FROM batch JOIN Path ON (batch.Path = Path.Path) JOIN Filename ON (batch.Name = Filename.Name): ERR=Lock wait timeout exceeded; try restarting transaction - \end{bmessage} - -In this case the - |mysql| :raw-latex:`\configline{innodb_lock_wait_timeout}` -must be increased. A value of 300 should be sufficient. - -.. raw:: latex - - \begin{config}{/etc/my.cnf.d/server.cnf} - ... - [mysqld] - innodb_lock_wait_timeout = 300 - ... - \end{config} - -:raw-latex:`\hide{ -\label{DatabasePerformance} -\section{Database Performance Issues} -\index[general]{Database Performance Issues} -\index[general]{Performance!Database} - -There are a considerable number of ways each of the databases can be -tuned to improve the performance. Going from an untuned database to one -that is properly tuned can make a difference of a factor of 100 or more -in the time to insert or search for records. - -For each of the databases, you may get significant improvements by adding -additional indexes. The comments in the Bareos make\_xxx\_tables give some -indications as to what indexes may be appropriate. Please see below -for specific instructions on checking indexes. - -For MySQL, what is very important is to use the examine the -my.cnf file (usually in /etc/my.cnf). -You may obtain significant performances by switching to -the my-large.cnf or my-huge.cnf files that come with the MySQL source -code. - -For SQLite3, one significant factor in improving the performance is -to ensure that there is a "PRAGMA synchronous = NORMAL;" statement. -This reduces the number of times that the database flushes the in memory -cache to disk. There are other settings for this PRAGMA that can -give even further performance improvements at the risk of a database -corruption if your system crashes. - -For PostgreSQL, you might want to consider turning fsync off. Of course -doing so can cause corrupted databases in the event of a machine crash. -There are many different ways that you can tune PostgreSQL, the -following document discusses a few of them: -\elink{ -http://www.varlena.com/varlena/GeneralBits/Tidbits/perf.html} -{http://www.varlena.com/varlena/GeneralBits/Tidbits/perf.html}. - -There is also a PostgreSQL FAQ question number 3.3 that may -answer some of your questions about how to improve performance -of the PostgreSQL engine: -\elink{ -http://www.postgresql.org/docs/faqs.FAQ.html\#3.3} -{http://www.postgresql.org/docs/faqs.FAQ.html\#3.3}. -% TODO: verify above is correct. is this okay for book? - -Also for PostgreSQL, look at what "effective\_cache\_size". For a 2GB memory -machine, you probably want to set it at 131072, but don't set it too high. -In addition, for a 2GB system, work\_mem = 256000 and -maintenance\_work\_mem = 256000 seem to be reasonable values. Make -sure your checkpoint\_segments is set to at least 8. -}` - -:raw-latex:`\hide{ -\section{Performance Issues Indexes} -\index[general]{Database Performance Issues Indexes} -\index[general]{Performance!Database} - -\TODO{This chapter needs verification/updating.} - -One of the most important considerations for improving performance on -the Bareos database is to ensure that it has all the appropriate indexes. -Several users have reported finding that their database did not have -all the indexes in the default configuration. In addition, you may -find that because of your own usage patterns, you need additional indexes. - -The most important indexes for performance are the two indexes on the -{\bf File} table. The first index is on {\bf FileId} and is automatically -made because it is the unique key used to access the table. The other -one is the (JobId, PathId, Filename) index. If these Indexes -are not present, your performance may suffer a lot. - -\subsection{PostgreSQL Indexes} -On PostgreSQL, you can check to see if you have the proper indexes using -the following commands: - -\footnotesize -\begin{verbatim} -psql bareos -select * from pg_indexes where tablename='file'; -\end{verbatim} -\normalsize - -If the indexes are not present, especially the JobId index, you can -create them with the following commands: - -\footnotesize -\begin{verbatim} -psql bareos -CREATE INDEX file_jobid_idx on file (jobid); -\end{verbatim} -\normalsize - -Make sure that you doesn't have an index on File (filenameid, pathid). - -\subsection{MySQL Indexes} -On MySQL, you can check if you have the proper indexes by: - -\footnotesize -\begin{verbatim} -mysql bareos -show index from File; -\end{verbatim} -\normalsize - -If the indexes are not present, especially the JobId index, you can -create them with the following commands: - -\footnotesize -\begin{verbatim} -mysql bareos -CREATE INDEX file_jobid_idx on File (JobId); -\end{verbatim} -\normalsize - -Though normally not a problem, you should ensure that the indexes -defined for Filename and Path are both set to 255 characters. Some users -reported performance problems when their indexes were set to 50 characters. -To check, do: - -\footnotesize -\begin{verbatim} -mysql bareos -show index from Filename; -show index from Path; -\end{verbatim} -\normalsize - -and what is important is that for Filename, you have an index with -Key\_name "Name" and Sub\_part "255". For Path, you should have a Key\_name -"Path" and Sub\_part "255". If one or the other does not exist or the -Sub\_part is less that 255, you can drop and recreate the appropriate -index with: - -\footnotesize -\begin{verbatim} -mysql bareos -DROP INDEX Path on Path; -CREATE INDEX Path on Path (Path(255)); - -DROP INDEX Name on Filename; -CREATE INDEX Name on Filename (Name(255)); -\end{verbatim} -\normalsize - - -\subsection{SQLite Indexes} -On SQLite, you can check if you have the proper indexes by: - -\footnotesize -\begin{verbatim} -sqlite /bareos.db -select * from sqlite_master where type='index' and tbl_name='File'; -\end{verbatim} -\normalsize - -If the indexes are not present, especially the JobId index, you can -create them with the following commands: - -\footnotesize -\begin{verbatim} -sqlite /bareos.db -CREATE INDEX file_jobid_idx on File (JobId); -\end{verbatim} -\normalsize -}` - -Backing Up Your Bareos Database -------------------------------- - - -.. index:: - triple: General; Backup; Bareos database - -.. index:: - triple: General; Backup; Catalog - -.. index:: - triple: General; Database; Backup Bareos database -.. _BackingUpBareos: - -If ever the machine on which your Bareos database crashes, and you need -to restore from backup tapes, one of your first priorities will probably -be to recover the database. Although Bareos will happily backup your -catalog database if it is specified in the FileSet, this is not a very -good way to do it, because the database will be saved while Bareos is -modifying it. Thus the database may be in an instable state. Worse yet, -you will backup the database before all the Bareos updates have been -applied. - -To resolve these problems, you need to backup the database after all the -backup jobs have been run. In addition, you will want to make a copy -while Bareos is not modifying it. To do so, you can use two scripts -provided in the release **make\_catalog\_backup** and -**delete\_catalog\_backup**. These files will be automatically generated -along with all the other Bareos scripts. The first script will make an -ASCII copy of your Bareos database into **bareos.sql** in the working -directory you specified in your configuration, and the second will -delete the **bareos.sql** file. - -The basic sequence of events to make this work correctly is as follows: - -- Run all your nightly backups - -- After running your nightly backups, run a Catalog backup Job - -- The Catalog backup job must be scheduled after your last nightly - backup - -- You use Run Before Job - to create the ASCII backup file and - Run After Job to clean - up - -Assuming that you start all your nightly backup jobs at 1:05 am (and -that they run one after another), you can do the catalog backup with the -following additional Director configuration statements: - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-dir}{Job}{BackupCatalog} - # Backup the catalog database (after the nightly save) - Job { - Name = "BackupCatalog" - Type = Backup - Client=rufus-fd - FileSet="Catalog" - Schedule = "WeeklyCycleAfterBackup" - Storage = DLTDrive - Messages = Standard - Pool = Default - # This creates an ASCII copy of the catalog - # Arguments to make_catalog_backup.pl are: - # make_catalog_backup.pl - RunBeforeJob = "/usr/lib/bareos/scripts/make_catalog_backup.pl MyCatalog" - # This deletes the copy of the catalog - RunAfterJob = "/usr/lib/bareos/scripts/delete_catalog_backup" - # This sends the bootstrap via mail for disaster recovery. - # Should be sent to another system, please change recipient accordingly - Write Bootstrap = "|/usr/sbin/bsmtp -h localhost -f \"\(Bareos\) \" -s \"Bootstrap for Job %j\" root@localhost" - } - \end{bareosConfigResource} - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-dir}{Schedule}{WeeklyCycleAfterBackup} - # This schedule does the catalog. It starts after the WeeklyCycle - Schedule { - Name = "WeeklyCycleAfterBackup" - Run = Level=Full sun-sat at 1:10 - } - \end{bareosConfigResource} - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-dir}{FileSet}{Catalog} - # This is the backup of the catalog - FileSet { - Name = "Catalog" - Include { - Options { - signature=MD5 - } - File = "/var/lib/bareos/bareos.sql" # database dump - File = "/etc/bareos" # configuration - } - } - \end{bareosConfigResource} - -It is preferable to write/send the -:ref:`bootstrap BootstrapChapter` file to another -computer. It will allow you to quickly recover the database backup -should that be necessary. If you do not have a bootstrap file, it is -still possible to recover your database backup, but it will be more work -and take longer. - -.. |image| image:: \idir dbconfig-1-enable - :width: 45.0% -.. |image| image:: \idir dbconfig-2-select-database-type - :width: 45.0% diff --git a/docs/manuals/en/new_main_reference/source/client-initiated-connection.rst b/docs/manuals/en/new_main_reference/source/client-initiated-connection.rst index 4bfa6afe84f..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/client-initiated-connection.rst +++ b/docs/manuals/en/new_main_reference/source/client-initiated-connection.rst @@ -1,117 +1 @@ -.. _sec:ClientInitiatedConnection: -Client Initiated Connection -=========================== - -The |bareosDir| knows, when it is required to talk to a -client (|bareosFd|). Therefore, by defaults, the -|bareosDir| connects to the clients. - -However, there are setups where this can cause problems, as this means -that: - -- The client must be reachable by its configured - **Address** (Dir configuration, Client resource). Address - can be the DNS name or the IP address. (For completeness: there are - potential workarounds by using the - :ref:`bcommandSetIP setip` command.) - -- The |bareosDir| must be able to connect to the - |bareosFd| over the network. - -To circumvent these problems, since Bareos -16.2.2 it -is possible to let the |bareosFd| initiate the network -connection to the |bareosDir|. - -Which address the client connects to reach the -|bareosDir| is configured in the -**Address** (Fd configuration, Director resource) directive. - -To additional allow this connection direction use: - -- **Connection From Client To Director** (Dir configuration, Client resource) - = yes - -- **Heartbeat Interval** (Dir configuration, Client resource) - = 60 ``#`` to keep the network connection established - -- **Connection From Client To Director** (Fd configuration, Director resource) - = yes - -To only allow Connection From the Client to the Director use: - -- **Connection From Director To Client** (Dir configuration, Client resource) - = no - -- **Connection From Client To Director** (Dir configuration, Client resource) - = yes - -- **Heartbeat Interval** (Dir configuration, Client resource) - = 60 ``#`` to keep the network connection established - -- **Connection From Director To Client** (Fd configuration, Director resource) - = no - -- **Connection From Client To Director** (Fd configuration, Director resource) - = yes - -Using Client Initiated Connections has disadvantages. Without Client -Initiated Connections the |bareosDir| only establishes a -network connection when this is required. With Client Initiated -Connections, the |bareosFd| connects to the -|bareosDir| and the |bareosDir| keeps these -connections open. The command :command:`status dir` will -show all waiting connections: - -.. raw:: latex - - \begin{bconsole}{show waiting client connections} - *status dir - ... - Client Initiated Connections (waiting for jobs): - Connect time Protocol Authenticated Name - ==================================================================================================== - 19-Apr-16 21:50 54 1 client1.example.com - ... - ==== - \end{bconsole} - -When both connection directions are allowed, the -|bareosDir| - -#. checks, if there is a waiting connection from this client. - -#. tries to connect to the client (using the usual timeouts). - -#. waits for a client connection to appear (using the same timeout as - when trying to connect to a client). - -If none of this worked, the job fails. - -When a waiting connection is used for a job, the -|bareosFd| will detect this and creates an additional -connection. This is required, to keep the client responsive for -additional commands, like :command:`cancel `. - -To get feedback in case the |bareosFd| fails to connect to -the |bareosDir|, consider configuring -|bareosFd| to log in a local file. This can be archived by -adding the line - -.. raw:: latex - - \configline{Append = "/var/log/bareos/bareos-fd.log" = all, !skipped, !restored} - -to the default message resource -:raw-latex:`\resourcename{Fd}{Messages}{Standard}`: - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-fd}{messages}{Standard} - Messages { - Name = Standard - Director = bareos-dir = all, !skipped, !restored - Append = "/var/log/bareos/bareos-fd.log" = all, !skipped, !restored - } - \end{bareosConfigResource} diff --git a/docs/manuals/en/new_main_reference/source/configure.rst b/docs/manuals/en/new_main_reference/source/configure.rst index 309dff7ca33..79deba29555 100644 --- a/docs/manuals/en/new_main_reference/source/configure.rst +++ b/docs/manuals/en/new_main_reference/source/configure.rst @@ -1,56 +1,1319 @@ +.. _ConfigureChapter: +Customizing the Configuration +============================= +:raw-latex:`\index[general]{Customizing the Configuration}` +Each Bareos component (Director, Client, Storage, Console) has its own +configuration containing a set of resource definitions. These resources +are very similar from one service to another, but may contain different +directives (records) depending on the component. For example, in the +Director configuration, the +:raw-latex:`\nameref{DirectorResourceDirector}` defines the name of the +Director, a number of global Director parameters and his password. In +the File daemon configuration, the +:raw-latex:`\nameref{ClientResourceDirector}` specifies which Directors +are permitted to use the File daemon. +If you install all Bareos daemons (Director, Storage and File Daemon) +onto one system, the Bareos package tries its best to generate a working +configuration as a basis for your individual configuration. +The details of each resource and the directives permitted therein are +described in the following chapters. +The following configuration files must be present: +- :raw-latex:`\nameref{DirectorChapter}` – to define the resources + necessary for the Director. You define all the Clients and Storage + daemons that you use in this configuration file. +- :raw-latex:`\nameref{StoredConfChapter}` – to define the resources to + be used by each Storage daemon. Normally, you will have a single + Storage daemon that controls your disk storage or tape drives. + However, if you have tape drives on several machines, you will have + at least one Storage daemon per machine. +- :raw-latex:`\nameref{FiledConfChapter}` – to define the resources for + each client to be backed up. That is, you will have a separate Client + resource file on each machine that runs a File daemon. +- :raw-latex:`\nameref{ConsoleConfChapter}` – to define the resources + for the Console program (user interface to the Director). It defines + which Directors are available so that you may interact with them. +.. _sec-ConfigurationPathLayout: +Configuration Path Layout +------------------------- +:raw-latex:`\index[general]{Configuration!Directories}` +:raw-latex:`\index[general]{Configuration!Subdirectories}` +When a Bareos component starts, it reads its configuration. In Bareos +:math:`<` 16.2.2 only configuration files (which optionally can include +other files) are supported. Since Bareos +:raw-latex:`\sinceVersion{}{Subdirectory Configuration Scheme}{16.2.2}` +also configuration subdirectories are supported. +Naming +^^^^^^ +In this section, the following naming is used: +- :raw-latex:`\path`\|CONFIGDIR\| refers to the base configuration + directory. Bareos Linux packages use :raw-latex:`\configPathUnix`. +- A component is one of the following Bareos programs: + - bareos-dir + - bareos-sd + - bareos-fd + - bareos-traymonitor + - bconsole + - bat (only legacy config file: bat.conf) + - Bareos tools, like + :raw-latex:`\nameref{sec-VolumeUtilityCommands}` and others. +- :raw-latex:`\path`\|COMPONENT\| refers to one of the listed + components. +.. _sec-ConfigurationFileOrConfigurationSubDirectories: +What configuration will be used? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +When starting a Bareos component, it will look for its configuration. +Bareos components allow the configuration file/directory to be specified +as a command line parameter :raw-latex:`\path`\|-c PATH|. +- configuration path parameter is not given (default) + - :raw-latex:`\path`\|CONFIGDIR/COMPONENT.conf\| is a file + - the configuration is read from the file + :raw-latex:`\path`\|CONFIGDIR/COMPONENT.conf\| + - :raw-latex:`\path`\|CONFIGDIR/COMPONENT.d/\| is a directory + - the configuration is read from + :raw-latex:`\path`\|CONFIGDIR/COMPONENT.d/*/*.conf\| + (subdirectory configuration) +- configuration path parameter is given (:raw-latex:`\path`\|-c PATH|) + - :raw-latex:`\path`\|PATH\| is a file + - the configuration is read from the file specified in + :raw-latex:`\path`\|PATH\| + - :raw-latex:`\path`\|PATH\| is a directory + - the configuration is read from + :raw-latex:`\path`\|PATH/COMPONENT.d/*/*.conf\| (subdirectory + configuration) +As the :raw-latex:`\path`\|CONFIGDIR\| differs between platforms or is +overwritten by the path parameter, the documentation will often refer to +the configuration without the leading path (e.g. +:raw-latex:`\path`\|COMPONENT.d/*/*.conf\| instead of +:raw-latex:`\path`\|CONFIGDIR/COMPONENT.d/*/*.conf|). +|image| +When subdirectory configuration is used, all files matching +:raw-latex:`\path`\|PATH/COMPONENT.d/*/*.conf\| will be read, see +:raw-latex:`\nameref{sec-ConfigurationSubdirectories}`. +Relation between Bareos components and configuration +'''''''''''''''''''''''''''''''''''''''''''''''''''' ++-----------------------+-----------------------+-----------------------+ +| Bareos component | | | ++-----------------------+-----------------------+-----------------------+ +| (default path on | | | +| Unix) | | | ++-----------------------+-----------------------+-----------------------+ +| (default path on | | | +| Unix) | | | ++-----------------------+-----------------------+-----------------------+ +| since Bareos | | | +| :math:`>=` 16.2.2 | | | ++-----------------------+-----------------------+-----------------------+ +| bareos-dir | :raw-latex:`\file{bar | :raw-latex:`\file{bar | +| | eos-dir.conf}` | eos-dir.d}` | ++-----------------------+-----------------------+-----------------------+ +| :raw-latex:`\nameref{ | (:raw-latex:`\configF | (:raw-latex:`\configD | +| DirectorChapter}` | ileDirUnix`) | irectoryDirUnix`) | ++-----------------------+-----------------------+-----------------------+ +| bareos-sd | :raw-latex:`\file{bar | :raw-latex:`\file{bar | +| | eos-sd.conf}` | eos-sd.d}` | ++-----------------------+-----------------------+-----------------------+ +| :raw-latex:`\nameref{ | (:raw-latex:`\configF | (:raw-latex:`\configD | +| StoredConfChapter}` | ileSdUnix`) | irectorySdUnix`) | ++-----------------------+-----------------------+-----------------------+ +| bareos-fd | :raw-latex:`\file{bar | :raw-latex:`\file{bar | +| | eos-fd.conf}` | eos-fd.d}` | ++-----------------------+-----------------------+-----------------------+ +| :raw-latex:`\nameref{ | (:raw-latex:`\configF | (:raw-latex:`\configD | +| FiledConfChapter}` | ileFdUnix`) | irectoryFdUnix`) | ++-----------------------+-----------------------+-----------------------+ +| bconsole | :raw-latex:`\file{bco | :raw-latex:`\file{bco | +| | nsole.conf}` | nsole.d}` | ++-----------------------+-----------------------+-----------------------+ +| :raw-latex:`\nameref{ | (:raw-latex:`\configF | (:raw-latex:`\configD | +| ConsoleConfChapter}` | ileBconsoleUnix`) | irectoryBconsoleUnix` | +| | | ) | ++-----------------------+-----------------------+-----------------------+ +| bareos-traymonitor | :raw-latex:`\file{tra | :raw-latex:`\file{tra | +| | y-monitor.conf}` | y-monitor.d}` | ++-----------------------+-----------------------+-----------------------+ +| :raw-latex:`\nameref{ | (:raw-latex:`\configF | (:raw-latex:`\configD | +| sec-MonitorConfig}` | ileTrayMonitorUnix`) | irectoryTrayMonitorUn | +| | | ix`) | ++-----------------------+-----------------------+-----------------------+ +| bat | :raw-latex:`\file{bat | (not supported) | +| | .conf}` | | ++-----------------------+-----------------------+-----------------------+ +| | (:raw-latex:`\configF | | +| | ileBatUnix`) | | ++-----------------------+-----------------------+-----------------------+ +| :raw-latex:`\nameref{ | :raw-latex:`\file{bar | :raw-latex:`\file{bar | +| sec-VolumeUtilityComm | eos-sd.conf}` | eos-sd.d}` | +| ands}` | | | ++-----------------------+-----------------------+-----------------------+ +| (use the bareos-sd | (:raw-latex:`\configF | (:raw-latex:`\configD | +| configuration) | ileSdUnix`) | irectorySdUnix`) | ++-----------------------+-----------------------+-----------------------+ +.. _sec-SubdirectoryConfigurationScheme: +Subdirectory Configuration Scheme +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:raw-latex:`\label{sec-ConfigurationSubdirectories}` +:raw-latex:`\label{ConfigurationIncludeDirectory}` +If the subdirectory configuration is used, instead of a single +configuration file, all files matching +:raw-latex:`\path`\|COMPONENT.d/*/*.conf\| are read as a configuration, +see +:raw-latex:`\nameref{sec-ConfigurationFileOrConfigurationSubDirectories}`. +Reason for the Subdirectory Configuration Scheme +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In Bareos :math:`<` 16.2.2, Bareos uses one configuration file per +component. +Most larger Bareos environments split their configuration into separate +files, making it easier to manage the configuration. +Also some extra packages (bareos-webui, plugins, ...) require a +configuration, which must be included into the +:raw-latex:`\bareosDir `or :raw-latex:`\bareosSd `configuration. The +subdirectory approach makes it easier to add or modify the configuration +resources of different Bareos packages. +The Bareos :raw-latex:`\ilink{configure}{sec-bcommandConfigure}` command +requires a configuration directory structure, as provided by the +subdirectory approach. +From Bareos +:raw-latex:`\sinceVersion{}{Subdirectory Configuration Scheme used as Default}{16.2.4}` +on, new installations will use configuration subdirectories by default. +.. _sec-ConfigurationResourceFileConventions: + +Resource file conventions +^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Each configuration resource has to use its own configuration file. + +- The path of a resource file is + :raw-latex:`\path`\|COMPONENT.d/RESOURCETYPE/RESOURCENAME.conf|. + +- The name of the configuration file is identical with the resource + name: + + - e.g. + + - :raw-latex:`\path`\|bareos-dir.d/director/bareos-dir.conf\| + + - :raw-latex:`\path`\|bareos-dir.d/pool/Full.conf\| + + - Exceptions: + + - The resource file + :raw-latex:`\path`\|bareos-fd.d/client/myself.conf\| always has + the file name :raw-latex:`\path`\|myself.conf|, while the name + is normally set to the hostname of the system. + +- Example resource files: + + - Additional packages can contain configuration files that are + automatically included. However, most additional configuration + resources require configuration. When a resource file requires + configuration, it has to be included as an example file: + + - :raw-latex:`\path`\|CONFIGDIR/COMPONENT.d/RESOURCE/NAME.conf.example\| + + - For example, the :raw-latex:`\bareosWebui `entails one config + resource and one config resource example for the + :raw-latex:`\bareosDir`: + + - :raw-latex:`\path`\|CONFIGDIR/bareos-director.d/profile/webui-admin.conf\| + + - :raw-latex:`\path`\|CONFIGDIR/bareos-director.d/console/admin.conf.example\| + +- extbfsec-deleteConfigurationResourceFilesDisable/remove configuration + resource files: + + - Normally you should not remove resources that are already in use + (jobs, clients, ...). Instead you should disable them by adding + the directive :raw-latex:`\configline{Enable = no}`. Otherwise you + take the risk that orphaned entries are kept in the Bareos + catalog. However, if a resource has not been used or all + references have been cleared from the database, they can also be + removed from the configuration. + :raw-latex:`\warning{If you want to remove a configuration resource that is part of a Bareos package, + replace the resource configuration file by an empty file. + This prevents the resource from reappearing in the course of a package update.}` + +Using Subdirectories Configuration Scheme +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +New installation +'''''''''''''''' + +- The Subdirectories Configuration Scheme is used by default from + Bareos + :raw-latex:`\sinceVersion{}{Subdirectory Configuration Scheme used as Default}{16.2.4}` + onwards. + +- They will be usable immediately after installing a Bareos component. + +- If additional packages entail example configuration files + (:raw-latex:`\path`\|NAME.conf.example|), copy them to + :raw-latex:`\path`\|NAME.conf|, modify it as required and reload or + restart the component. + +.. _sec-UpdateToConfigurationSubdirectories: + +Updates from Bareos :math:`<` 16.2.4 +'''''''''''''''''''''''''''''''''''' + +- When updating to a Bareos version containing the Subdirectories + Configuration, the existing configuration will not be touched and is + still the default configuration. + + - + + .. raw:: latex + + \warning{Problems can occur if you have implemented an own wildcard mechanism to load your configuration + from the same subdirectories as used by the new packages (\path|CONFIGDIR/COMPONENT.d/*/*.conf|). + In this case, newly installed configuration resource files can alter + your current configuration by adding resources.} + + Best create a copy of your configuration directory before updating + Bareos and modify your existing configuration file to use that + other directory. + +- As long as the old configuration file + (:raw-latex:`\path`\|CONFIGDIR/COMPONENT.conf|) exists, it will be + used. + +- The correct way of migrating to the new configuration scheme would be + to split the configuration file into resources, store them in the + resource directories and then remove the original configuration file. + + - For migrating the :raw-latex:`\bareosDir `configuration, the + script :raw-latex:`\bareosMigrateConfigSh `exists. Being called, + it connects via :raw-latex:`\command{verbatim}` to a running + :raw-latex:`\bareosDir `and creates subdirectories with the + resource configuration files. + + :: + + {\bareosMigrateConfigSh} + # prepare temporary directory + mkdir /tmp/baroes-dir.d + cd /tmp/baroes-dir.d + + # download migration script + wget https://raw.githubusercontent.com/bareos/bareos-contrib/master/misc/bareos-migrate-config/bareos-migrate-config.sh + + # execute the script + bash bareos-migrate-config.sh + + # backup old configuration + mv /etc/bareos/bareos-dir.conf /etc/bareos/bareos-dir.conf.bak + mv /etc/bareos/bareos-dir.d /etc/bareos/bareos-dir.d.bak + + # make sure, that all packaged configuration resources exists, + # otherwise they will be added when updating Bareos. + for i in `find /etc/bareos/bareos-dir.d.bak/ -name *.conf -type f -printf "%P\n"`; do touch "$i"; done + + # install newly generated configuration + cp -a /tmp/bareos-dir.d /etc/bareos/ + + + Restart the :raw-latex:`\bareosDir `and verify your configuration. + Also make sure, that all resource configuration files coming from + Bareos packages exists, in doubt as empty files, see `remove + configuration resource + files <#sec-deleteConfigurationResourceFiles>`__. + + - Another way, without splitting the configuration into resource + files is: + + - :: + + {move configuration to subdirectory} + mkdir CONFIGDIR/COMPONENT.d/migrate && mv CONFIGDIR/COMPONENT.conf CONFIGDIR/COMPONENT.d/migrate + + + - Resources defined in both, the new configuration directory + scheme and the old configuration file, must be removed from one + of the places, best from the old configuration file, after + verifying that the settings are identical with the new + settings. + +Configuration File Format +------------------------- + +A configuration file consists of one or more resources (see +:raw-latex:`\nameref{sec-ConfigurationResourceFormat}`). + +Bareos programs can work with + +- all resources defined in one configuration file + +- configuration files that include other configuration files (see + :raw-latex:`\nameref{Includes}`) + +- :raw-latex:`\nameref{sec-ConfigurationSubdirectories}`, where each + configuration file contains exactly one resource definition + +Character Sets +~~~~~~~~~~~~~~ + +:raw-latex:`\index[general]{Character Sets}` Bareos is designed to +handle most character sets of the world, US ASCII, German, French, +Chinese, ... However, it does this by encoding everything in UTF-8, and +it expects all configuration files (including those read on Win32 +machines) to be in UTF-8 format. UTF-8 is typically the default on Linux +machines, but not on all Unix machines, nor on Windows, so you must take +some care to ensure that your locale is set properly before starting +Bareos. + +:raw-latex:`\index[general]{Windows!Configuration Files!UTF-8}` To +ensure that Bareos configuration files can be correctly read including +foreign characters, the **LANG** environment variable must end in +**.UTF-8**. A full example is **en_US.UTF-8**. The exact syntax may vary +a bit from OS to OS, so that the way you have to define it will differ +from the example. On most newer Win32 machines you can use +:raw-latex:`\command{notepad}` to edit the conf files, then choose +output encoding UTF-8. + +Bareos assumes that all filenames are in UTF-8 format on Linux and Unix +machines. On Win32 they are in Unicode (UTF-16) and will hence be +automatically converted to UTF-8 format. + +.. _Comments: + +Comments +~~~~~~~~ + +:raw-latex:`\index[general]{Configuration!Comments}` + +When reading a configuration, blank lines are ignored and everything +after a hash sign (#) until the end of the line is taken to be a +comment. + +Semicolons +~~~~~~~~~~ + +A semicolon (;) is a logical end of line and anything after the +semicolon is considered as the next statement. If a statement appears on +a line by itself, a semicolon is not necessary to terminate it, so +generally in the examples in this manual, you will not see many +semicolons. + +.. _Includes: + +Including other Configuration Files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:raw-latex:`\index[general]{Including other Configuration Files}` +:raw-latex:`\index[general]{Files!Including other Configuration}` +:raw-latex:`\index[general]{Configuration!Including Files}` + +If you wish to break your configuration file into smaller pieces, you +can do so by including other files using the syntax +:raw-latex:`\configdirective{@filename}` where +:raw-latex:`\file{filename}` is the full path and filename of another +file. The :raw-latex:`\configdirective{@filename}` specification can be +given anywhere a primitive token would appear. + +:: + + {include a configuration file} + @/etc/bareos/extra/clients.conf + +Since Bareos +:raw-latex:`\sinceVersion{}{Including configuration files by wildcard}{16.2.1}` +wildcards in pathes are supported: + +:: + + {include multiple configuration files} + @/etc/bareos/extra/*.conf + +By using :raw-latex:`\configdirective{@|command}` it is also possible to +include the output of a script as a configuration: + +:: + + {use the output of a script as configuration} + @|"/etc/bareos/generate_configuration_to_stdout.sh" + +or if a parameter should be used: + +:: + + {use the output of a script with parameter as a configuration} + @|"sh -c '/etc/bareos/generate_client_configuration_to_stdout.sh clientname=client1.example.com'" + +The scripts are called at the start of the daemon. You should use this +with care. + +.. _sec-ConfigurationResourceFormat: + +Resource +-------- + +:raw-latex:`\index[general]{Configuration!Resource}` + +A resource is defined as the resource type (see +:raw-latex:`\nameref{ResTypes}`), followed by an open brace +(:raw-latex:`\path`\|\|), a number of +:raw-latex:`\nameref{sec-ConfigurationResourceDirective}`s, and ended by +a closing brace (:raw-latex:`\path`\|\|) + +.. raw:: latex + + \hide{ + \begin{verbatim}{Resource} + RESOURCETYPE { + Name = RESOURCENAME + $KEY1 = $VALUE1 + $KEY2 = $VALUE2 + } + \end{verbatim} + } + +Each resource definition MUST contain a +:raw-latex:`\configdirective{Name}` directive. It can contain a +:raw-latex:`\configdirective{Description}` directive. The +:raw-latex:`\configdirective{Name}` directive is used to uniquely +identify the resource. The :raw-latex:`\configdirective{Description}` +directive can be used during the display of the Resource to provide +easier human recognition. For example: + +:: + + {Resource example} + Director { + Name = "bareos-dir" + Description = "Main Bareos Director" + Query File = "/usr/lib/bareos/scripts/query.sql" + } + +defines the Director resource with the name +:raw-latex:`\parameter{bareos-dir}` and a query file +:raw-latex:`\file{/usr/lib/bareos/scripts/query.sql}`. + +:raw-latex:`\index[general]{Configuration!Naming Convention}` + +When naming resources, for some resource types naming conventions should +be applied: + +Client + names should be postfixed with :raw-latex:`\name{-fd}` + +Storage + names should be postfixed with :raw-latex:`\name{-sd}` + +Director + names should be postfixed with :raw-latex:`\name{-dir}` + +These conventions helps a lot when reading log messages. + +.. _sec-ConfigurationResourceDirective: + +Resource Directive +~~~~~~~~~~~~~~~~~~ + +Each directive contained within the resource (within the curly braces +:raw-latex:`\path`\||) is composed of a +:raw-latex:`\nameref{sec-ConfigurationResourceDirectiveKeyword}` +followed by an equal sign (=) followed by a +:raw-latex:`\nameref{sec-ConfigurationResourceDirectiveValue}`. The +keywords must be one of the known Bareos resource record keywords. + +.. _sec-ConfigurationResourceDirectiveKeyword: + +Resource Directive Keyword +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A resource directive keyword is the part before the equal sign +(:raw-latex:`\path`\|=|) in a +:raw-latex:`\nameref{sec-ConfigurationResourceDirective}`. The following +sections will list all available directives by Bareos component +resources. + +Upper and Lower Case and Spaces +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Case (upper/lower) and spaces are ignored in the resource directive +keywords. + +Within the keyword (i.e. before the equal sign), spaces are not +significant. Thus the keywords: **name**, **Name**, and **N a m e** are +all identical. + +.. _sec-ConfigurationResourceDirectiveValue: + +Resource Directive Value +~~~~~~~~~~~~~~~~~~~~~~~~ + +A resource directive value is the part after the equal sign +(:raw-latex:`\path`\|=|) in a +:raw-latex:`\nameref{sec-ConfigurationResourceDirective}`. + +Spaces +^^^^^^ + +Spaces after the equal sign and before the first character of the value +are ignored. Other spaces within a value may be significant (not +ignored) and may require quoting. + +.. _sec-Quotes: + +Quotes +^^^^^^ + +In general, if you want spaces in a name to the right of the first equal +sign (=), you must enclose that name within double quotes. Otherwise +quotes are not generally necessary because once defined, quoted strings +and unquoted strings are all equal. + +Within a quoted string, any character following a backslash (\) is taken +as itself (handy for inserting backslashes and double quotes (")). + +:raw-latex:`\warning{If the configure directive is used to define a number, the number is never to be put between surrounding quotes. +This is even true if the number is specified together with its unit, like \parameter{365 days}}`. + +Numbers +^^^^^^^ + +Numbers are not to be quoted, see :raw-latex:`\nameref{sec-Quotes}`. +Also do not prepend numbers by zeros (0), as these are not parsed in the +expected manner (write 1 instead of 01). + +Data Types +^^^^^^^^^^ + +:raw-latex:`\index[general]{Configuration!Data Types}` +:raw-latex:`\index[general]{Data Type}` :raw-latex:`\label{DataTypes}` + +When parsing the resource directives, Bareos classifies the data +according to the types listed below. + +acl + :raw-latex:`\index[general]{Data Type!acl}` + :raw-latex:`\label{DataTypeAcl}` This directive defines what is + permitted to be accessed. It does this by using a list of regular + expressions, separated by commas (:raw-latex:`\argument{,}`) or + using multiple directives. If :raw-latex:`\argument{!}` is + prepended, the expression is negated. The special keyword + :raw-latex:`\parameter{*all*}` allows unrestricted access. + + Depending on the type of the ACL, the regular expressions can be + either resource names, paths or console commands. + + Since Bareos + :raw-latex:`\sinceVersion{dir}{ACL: strict regular expression handling}{16.2.4}` + regular expression are handled more strictly. Before also substring + matches has been accepted. + + :raw-latex:`\label{sec-CommandAclExample}` For clarification, we + demonstrate the usage of ACLs by some examples for + :raw-latex:`\linkResourceDirective{Dir}{Console}{Command ACL}`: + + :: + + {Allow only the help command} + Command ACL = help + + :: + + {Allow the help and the list command} + Command ACL = help, list + + :: + + {Allow the help and the (not existing) iDoNotExist command} + Command ACL = help, iDoNotExist + + :: + + {Allow all commands (special keyword)} + Command ACL = *all* + + :: + + {Allow all commands except sqlquery and commands starting with u} + Command ACL = !sqlquery, !u.*, *all* + + Same: + + :: + + {Some as above. Specifying it in multiple lines doesn't change the meaning} + Command ACL = !sqlquery, !u.* + Command ACL = *all* + + :: + + {Additional deny the setip and setdebug commands} + Command ACL = !sqlquery + Command ACL = !u.* + Comamnd ACL = !set(ip|debug) + Comamnd ACL = *all* + + .. raw:: latex + + \warning{ + ACL checking stops at the first match. So the following definition allows all commands, which might not be what you expected: + } + + :: + + {Wrong: Allows all commands} + # WARNING: this configuration ignores !sqlquery, as *all* is matched before. + Command ACL = *all*, !sqlquery + +auth-type + :raw-latex:`\index[general]{Data Type!auth-type}` + :raw-latex:`\label{DataTypeAuthType}` Specifies the authentication + type that must be supplied when connecting to a backup protocol that + uses a specific authentication type. Currently only used for + :raw-latex:`\nameref{NDMPResource}`. + + The following values are allowed: + + None + - Use no password + + Clear + - Use clear text password + + MD5 + - Use MD5 hashing + +integer + :raw-latex:`\index[general]{Data Type!integer}` + :raw-latex:`\label{DataTypeInteger}` A 32 bit integer value. It may + be positive or negative. + + Don’t use quotes around the number, see + :raw-latex:`\nameref{sec-Quotes}`. + +long integer + :raw-latex:`\index[general]{Data Type!long integer}` + :raw-latex:`\label{DataTypeLongInteger}` A 64 bit integer value. + Typically these are values such as bytes that can exceed 4 billion + and thus require a 64 bit value. + + Don’t use quotes around the number, see + :raw-latex:`\nameref{sec-Quotes}`. + +job protocol + :raw-latex:`\index[general]{Data Type!job protocol}` + :raw-latex:`\label{DataTypeJobProtocol}` + + The protocol to run a the job. Following protocols are available: + + Native + Native Bareos job protocol. + + NDMP + Deprecated. Alias for :raw-latex:`\NdmpBareos`. + + NDMP_BAREOS + Since Bareos + :raw-latex:`\sinceVersion{dir}{NDMP BAREOS}{17.2.3}`. See + :raw-latex:`\nameref{sec-NdmpBareos}`. + + NDMP_NATIVE + Since Bareos + :raw-latex:`\sinceVersion{dir}{NDMP NATIVE}{17.2.3}`. See + :raw-latex:`\nameref{sec-NdmpNative}`. + +name + :raw-latex:`\index[general]{Data Type!name}` + :raw-latex:`\label{DataTypeName}` A keyword or name consisting of + alphanumeric characters, including the hyphen, underscore, and + dollar characters. The first character of a **name** must be a + letter. A name has a maximum length currently set to 127 bytes. + + Please note that Bareos resource names as well as certain other + names (e.g. Volume names) must contain only letters (including ISO + accented letters), numbers, and a few special characters (space, + underscore, ...). All other characters and punctuation are invalid. + +password + :raw-latex:`\index[general]{Data Type!password}` + :raw-latex:`\label{DataTypePassword}` This is a Bareos password and + it is stored internally in MD5 hashed format. + +path + :raw-latex:`\index[general]{Data Type!path}` + :raw-latex:`\label{DataTypeDirectory}` A path is either a quoted or + non-quoted string. A path will be passed to your standard shell for + expansion when it is scanned. Thus constructs such as **$HOME** are + interpreted to be their correct values. The path can either + reference to a file or a directory. + +positive integer + :raw-latex:`\index[general]{Data Type!positive integer}` + :raw-latex:`\label{DataTypePositiveInteger}` A 32 bit positive + integer value. + + Don’t use quotes around the number, see + :raw-latex:`\nameref{sec-Quotes}`. + +speed + :raw-latex:`\index[general]{Data Type!speed}` + :raw-latex:`\label{DataTypeSpeed}` The speed parameter can be + specified as k/s, kb/s, m/s or mb/s. + + Don’t use quotes around the parameter, see + :raw-latex:`\nameref{sec-Quotes}`. + +string + :raw-latex:`\index[general]{Data Type!string}` + :raw-latex:`\label{DataTypeString}` A quoted string containing + virtually any character including spaces, or a non-quoted string. A + string may be of any length. Strings are typically values that + correspond to filenames, directories, or system command names. A + backslash (\) turns the next character into itself, so to include a + double quote in a string, you precede the double quote with a + backslash. Likewise to include a backslash. + +string-list + :raw-latex:`\index[general]{Data Type!string list}` + :raw-latex:`\label{DataTypeStringList}` Multiple strings, specified + in multiple directives, or in a single directive, separated by + commas (**,**). + +strname + :raw-latex:`\index[general]{Data Type!strname}` + :raw-latex:`\label{DataTypeStrname}` is similar to a + :raw-latex:`\dtName`, except that the name may be quoted and can + thus contain additional characters including spaces. + +net-address + :raw-latex:`\index[general]{Data Type!net-address}` + :raw-latex:`\label{DataTypeNetAddress}` is either a domain name or + an IP address specified as a dotted quadruple in string or quoted + string format. This directive only permits a single address to be + specified. The :raw-latex:`\dtNetPort` must be specificly separated. + If multiple net-addresses are needed, please assess if it is also + possible to specify :raw-latex:`\dtNetAddresses` (plural). + +net-addresses + :raw-latex:`\index[general]{Data Type!net-addresses}` + :raw-latex:`\label{DataTypeNetAddresses}` Specify a set of + net-addresses and net-ports. Probably the simplest way to explain + this is to show an example: + + :: + + {net-addresses} + Addresses = { + ip = { addr = 1.2.3.4; port = 1205;} + ipv4 = { + addr = 1.2.3.4; port = http;} + ipv6 = { + addr = 1.2.3.4; + port = 1205; + } + ip = { + addr = 1.2.3.4 + port = 1205 + } + ip = { addr = 1.2.3.4 } + ip = { addr = 201:220:222::2 } + ip = { + addr = server.example.com + } + } + + where ip, ip4, ip6, addr, and port are all keywords. Note, that the + address can be specified as either a dotted quadruple, or in IPv6 + colon notation, or as a symbolic name (only in the ip + specification). Also, the port can be specified as a number or as + the mnemonic value from the :raw-latex:`\file{/etc/services}` file. + If a port is not specified, the default one will be used. If an ip + section is specified, the resolution can be made either by IPv4 or + IPv6. If ip4 is specified, then only IPv4 resolutions will be + permitted, and likewise with ip6. + +net-port + :raw-latex:`\index[general]{Data Type!net-port}` + :raw-latex:`\label{DataTypeNetPort}` Specify a network port (a + positive integer). + + Don’t use quotes around the parameter, see + :raw-latex:`\nameref{sec-Quotes}`. + +resource + :raw-latex:`\index[general]{Data Type!resource}` + :raw-latex:`\label{DataTypeRes}` A resource defines a relation to + the name of another resource. + +size + :raw-latex:`\index[general]{Data Type!size}` + :raw-latex:`\label{DataTypeSize}` :raw-latex:`\label{Size1}` A size + specified as bytes. Typically, this is a floating point scientific + input format followed by an optional modifier. The floating point + input is stored as a 64 bit integer value. If a modifier is present, + it must immediately follow the value with no intervening spaces. The + following modifiers are permitted: + + k + 1,024 (kilobytes) + + kb + 1,000 (kilobytes) + + m + 1,048,576 (megabytes) + + mb + 1,000,000 (megabytes) + + g + 1,073,741,824 (gigabytes) + + gb + 1,000,000,000 (gigabytes) + + Don’t use quotes around the parameter, see + :raw-latex:`\nameref{sec-Quotes}`. + +time + :raw-latex:`\index[general]{Data Type!time}` + :raw-latex:`\label{DataTypeTime}` :raw-latex:`\label{Time}` A time + or duration specified in seconds. The time is stored internally as a + 64 bit integer value, but it is specified in two parts: a number + part and a modifier part. The number can be an integer or a floating + point number. If it is entered in floating point notation, it will + be rounded to the nearest integer. The modifier is mandatory and + follows the number part, either with or without intervening spaces. + The following modifiers are permitted: + + seconds + :raw-latex:`\index[dir]{seconds}` + + minutes + :raw-latex:`\index[dir]{minutes}` (60 seconds) + + hours + :raw-latex:`\index[dir]{hours}` (3600 seconds) + + days + :raw-latex:`\index[dir]{days}` (3600*24 seconds) + + weeks + :raw-latex:`\index[dir]{weeks}` (3600*24*7 seconds) + + months + :raw-latex:`\index[dir]{months}` (3600*24*30 seconds) + + quarters + :raw-latex:`\index[dir]{quarters}` (3600*24*91 seconds) + + years + :raw-latex:`\index[dir]{years}` (3600*24*365 seconds) + + Any abbreviation of these modifiers is also permitted (i.e. + **seconds** may be specified as **sec** or **s**). A specification + of **m** will be taken as months. + + The specification of a time may have as many number/modifier parts + as you wish. For example: + + .. raw:: latex + + \footnotesize + + :: + + 1 week 2 days 3 hours 10 mins + 1 month 2 days 30 sec + + .. raw:: latex + + \normalsize + + are valid date specifications. + + Don’t use quotes around the parameter, see + :raw-latex:`\nameref{sec-Quotes}`. + +audit-command-list + :raw-latex:`\index[general]{Data Type!audit command list}` + :raw-latex:`\label{DataTypeAuditCommandList}` Specifies the commands + that should be logged on execution (audited). E.g. + + :: + + {} + Audit Events = label + Audit Events = restore + + Based on the type :raw-latex:`\dtStringList`. + +:raw-latex:`\yesno` + :raw-latex:`\index[general]{Data Type!\yesno}` + :raw-latex:`\index[general]{Data Type!boolean}` + :raw-latex:`\label{DataTypeYesNo}` Either a + :raw-latex:`\parameter{yes}` or a :raw-latex:`\parameter{no}` (or + :raw-latex:`\parameter{true}` or :raw-latex:`\parameter{false}`). + +.. _VarsChapter: + +Variable Expansion +^^^^^^^^^^^^^^^^^^ + +Depending on the directive, Bareos will expand to the following +variables: + +.. _sec-VariableExpansionVolumeLabels: + +Variable Expansion on Volume Labels +''''''''''''''''''''''''''''''''''' + +When labeling a new volume (see +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Label Format}`), following +Bareos internal variables can be used: + ++-----------------------+------------------------------------------+ +| **Internal Variable** | **Description** | ++-----------------------+------------------------------------------+ +| **$Year** | Year | ++-----------------------+------------------------------------------+ +| **$Month** | Month: 1-12 | ++-----------------------+------------------------------------------+ +| **$Day** | Day: 1-31 | ++-----------------------+------------------------------------------+ +| **$Hour** | Hour: 0-24 | ++-----------------------+------------------------------------------+ +| **$Minute** | Minute: 0-59 | ++-----------------------+------------------------------------------+ +| **$Second** | Second: 0-59 | ++-----------------------+------------------------------------------+ +| **$WeekDay** | Day of the week: 0-6, using 0 for Sunday | ++-----------------------+------------------------------------------+ +| **$Job** | Name of the Job | ++-----------------------+------------------------------------------+ +| **$Dir** | Name of the Director | ++-----------------------+------------------------------------------+ +| **$Level** | Job Level | ++-----------------------+------------------------------------------+ +| **$Type** | Job Type | ++-----------------------+------------------------------------------+ +| **$JobId** | JobId | ++-----------------------+------------------------------------------+ +| **$JobName** | unique name of a job | ++-----------------------+------------------------------------------+ +| **$Storage** | Name of the Storage Daemon | ++-----------------------+------------------------------------------+ +| **$Client** | Name of the Clients | ++-----------------------+------------------------------------------+ +| **$NumVols** | Numbers of volumes in the pool | ++-----------------------+------------------------------------------+ +| **$Pool** | Name of the Pool | ++-----------------------+------------------------------------------+ +| **$Catalog** | Name of the Catalog | ++-----------------------+------------------------------------------+ +| **$MediaType** | Type of the media | ++-----------------------+------------------------------------------+ + +Additional, normal environment variables can be used, e.g. **$HOME** +oder **$HOSTNAME**. + +With the exception of Job specific variables, you can trigger the +variable expansion by using the :raw-latex:`\ilink{var command}{var}`. + +Variable Expansion in Autochanger Commands +'''''''''''''''''''''''''''''''''''''''''' + +At the configuration of autochanger commands the following variables can +be used: + ++------------------------------+---------------------+ +| **Variable** | **Description** | ++------------------------------+---------------------+ +| :raw-latex:`\parameter{\%a}` | Archive Device Name | ++------------------------------+---------------------+ +| :raw-latex:`\parameter{\%c}` | Changer Device Name | ++------------------------------+---------------------+ +| :raw-latex:`\parameter{\%d}` | Changer Drive Index | ++------------------------------+---------------------+ +| :raw-latex:`\parameter{\%f}` | Client’s Name | ++------------------------------+---------------------+ +| :raw-latex:`\parameter{\%j}` | Job Name | ++------------------------------+---------------------+ +| :raw-latex:`\parameter{\%o}` | Command | ++------------------------------+---------------------+ +| :raw-latex:`\parameter{\%s}` | Slot Base 0 | ++------------------------------+---------------------+ +| :raw-latex:`\parameter{\%S}` | Slot Base 1 | ++------------------------------+---------------------+ +| :raw-latex:`\parameter{\%v}` | Volume Name | ++------------------------------+---------------------+ + +Variable Expansion in Mount Commands +'''''''''''''''''''''''''''''''''''' + +At the configuration of mount commands the following variables can be +used: + ++------------------------------+---------------------+ +| **Variable** | **Description** | ++------------------------------+---------------------+ +| :raw-latex:`\parameter{\%a}` | Archive Device Name | ++------------------------------+---------------------+ +| :raw-latex:`\parameter{\%e}` | Erase | ++------------------------------+---------------------+ +| :raw-latex:`\parameter{\%n}` | Part Number | ++------------------------------+---------------------+ +| :raw-latex:`\parameter{\%m}` | Mount Point | ++------------------------------+---------------------+ +| :raw-latex:`\parameter{\%v}` | Last Part Name | ++------------------------------+---------------------+ + +Variable Expansion on RunScripts +'''''''''''''''''''''''''''''''' + +Variable Expansion on RunScripts is described at +:raw-latex:`\linkResourceDirective{Dir}{Job}{Run Script}`. + +Variable Expansion in Mail and Operator Commands +'''''''''''''''''''''''''''''''''''''''''''''''' + +At the configuration of mail and operator commands the following +variables can be used: + ++------------------------------+------------------------------------+ +| **Variable** | **Description** | ++------------------------------+------------------------------------+ +| :raw-latex:`\parameter{\%c}` | Client’s Name | ++------------------------------+------------------------------------+ +| :raw-latex:`\parameter{\%d}` | Director’s Name | ++------------------------------+------------------------------------+ +| :raw-latex:`\parameter{\%e}` | Job Exit Code | ++------------------------------+------------------------------------+ +| :raw-latex:`\parameter{\%i}` | JobId | ++------------------------------+------------------------------------+ +| :raw-latex:`\parameter{\%j}` | Unique Job Id | ++------------------------------+------------------------------------+ +| :raw-latex:`\parameter{\%l}` | Job Level | ++------------------------------+------------------------------------+ +| :raw-latex:`\parameter{\%n}` | Unadorned Job Name | ++------------------------------+------------------------------------+ +| :raw-latex:`\parameter{\%s}` | Since Time | ++------------------------------+------------------------------------+ +| :raw-latex:`\parameter{\%t}` | Job Type (Backup, ...) | ++------------------------------+------------------------------------+ +| :raw-latex:`\parameter{\%r}` | Recipients | ++------------------------------+------------------------------------+ +| :raw-latex:`\parameter{\%v}` | Read Volume Name | ++------------------------------+------------------------------------+ +| :raw-latex:`\parameter{\%V}` | Write Volume Name | ++------------------------------+------------------------------------+ +| :raw-latex:`\parameter{\%b}` | Job Bytes | ++------------------------------+------------------------------------+ +| :raw-latex:`\parameter{\%B}` | Job Bytes in human readable format | ++------------------------------+------------------------------------+ +| :raw-latex:`\parameter{\%F}` | Job Files | ++------------------------------+------------------------------------+ + +Resource Types +~~~~~~~~~~~~~~ + +:raw-latex:`\index[general]{Types!Resource}` +:raw-latex:`\index[general]{Resource Types}` +:raw-latex:`\label{ResTypes}` + +The following table lists all current Bareos resource types. It shows +what resources must be defined for each service (daemon). The default +configuration files will already contain at least one example of each +permitted resource. + +.. raw:: latex + + \addcontentsline{lot}{table}{Resource Types} + ++-------------+-------------+-------------+-------------+-------------+ +| :raw-latex: | :raw-latex: | :raw-latex: | :raw-latex: | :raw-latex: | +| `\multicolu | `\multicolu | `\multicolu | `\multicolu | `\multicolu | +| mn{1}{|c|| | mn{1}{c| }{ | mn{1}{c| }{ | mn{1}{c| }{ | mn{1}{c| }{ | +| }{\bf Resou | \ilink{Dir | \ilink{Cli | \ilink{Sto | \ilink{Con | +| rce }` | ector}{Dire | ent}{FiledC | rage}{Store | sole}{Conso | +| | ctorConfCha | onfChapter} | dConfChapte | leConfChapt | +| | pter} }` | }` | r} }` | er} }` | ++=============+=============+=============+=============+=============+ +| Autochanger | | | :raw-latex: | | +| | | | `\cmlink{St | | +| | | | orageResour | | +| | | | ceAutochang | | +| | | | er}` | | ++-------------+-------------+-------------+-------------+-------------+ +| Catalog | :raw-latex: | | | | +| | `\cmlink{Di | | | | +| | rectorResou | | | | +| | rceCatalog} | | | | +| | ` | | | | ++-------------+-------------+-------------+-------------+-------------+ +| Client | :raw-latex: | :raw-latex: | | | +| | `\cmlink{Di | `\cmlink{Cl | | | +| | rectorResou | ientResourc | | | +| | rceClient}` | eClient}` | | | ++-------------+-------------+-------------+-------------+-------------+ +| Console | :raw-latex: | | | :raw-latex: | +| | `\cmlink{Di | | | `\cmlink{Co | +| | rectorResou | | | nsoleResour | +| | rceConsole} | | | ceConsole}` | +| | ` | | | | ++-------------+-------------+-------------+-------------+-------------+ +| Device | | | :raw-latex: | | +| | | | `\cmlink{St | | +| | | | orageResour | | +| | | | ceDevice}` | | ++-------------+-------------+-------------+-------------+-------------+ +| Director | :raw-latex: | :raw-latex: | :raw-latex: | :raw-latex: | +| | `\cmlink{Di | `\cmlink{Cl | `\cmlink{St | `\cmlink{Co | +| | rectorResou | ientResourc | orageResour | nsoleResour | +| | rceDirector | eDirector}` | ceDirector} | ceDirector} | +| | }` | | ` | ` | ++-------------+-------------+-------------+-------------+-------------+ +| FileSet | :raw-latex: | | | | +| | `\cmlink{Di | | | | +| | rectorResou | | | | +| | rceFileSet} | | | | +| | ` | | | | ++-------------+-------------+-------------+-------------+-------------+ +| Job | :raw-latex: | | | | +| | `\cmlink{Di | | | | +| | rectorResou | | | | +| | rceJob}` | | | | ++-------------+-------------+-------------+-------------+-------------+ +| JobDefs | :raw-latex: | | | | +| | `\cmlink{Di | | | | +| | rectorResou | | | | +| | rceJobDefs} | | | | +| | ` | | | | ++-------------+-------------+-------------+-------------+-------------+ +| Message | :raw-latex: | :raw-latex: | :raw-latex: | | +| | `\cmlink{Re | `\cmlink{Re | `\cmlink{Re | | +| | sourceMessa | sourceMessa | sourceMessa | | +| | ges}` | ges}` | ges}` | | ++-------------+-------------+-------------+-------------+-------------+ +| NDMP | | | :raw-latex: | | +| | | | `\cmlink{St | | +| | | | orageResour | | +| | | | ceNDMP}` | | ++-------------+-------------+-------------+-------------+-------------+ +| Pool | :raw-latex: | | | | +| | `\cmlink{Di | | | | +| | rectorResou | | | | +| | rcePool}` | | | | ++-------------+-------------+-------------+-------------+-------------+ +| Profile | :raw-latex: | | | | +| | `\cmlink{Di | | | | +| | rectorResou | | | | +| | rceProfile} | | | | +| | ` | | | | ++-------------+-------------+-------------+-------------+-------------+ +| Schedule | :raw-latex: | | | | +| | `\cmlink{Di | | | | +| | rectorResou | | | | +| | rceSchedule | | | | +| | }` | | | | ++-------------+-------------+-------------+-------------+-------------+ +| Storage | :raw-latex: | | :raw-latex: | | +| | `\cmlink{Di | | `\cmlink{St | | +| | rectorResou | | orageResour | | +| | rceStorage} | | ceStorage}` | | +| | ` | | | | ++-------------+-------------+-------------+-------------+-------------+ + +.. _Names: + +Names, Passwords and Authorization +---------------------------------- + +:raw-latex:`\index[general]{Authorization!Names and Passwords}` +:raw-latex:`\index[general]{Passwords}` + +In order for one daemon to contact another daemon, it must authorize +itself with a password. In most cases, the password corresponds to a +particular name, so both the name and the password must match to be +authorized. Passwords are plain text, any text. They are not generated +by any special process; just use random text. + +The default configuration files are automatically defined for correct +authorization with random passwords. If you add to or modify these +files, you will need to take care to keep them consistent. + +:raw-latex:`\label{sec-resource-relation}` + +.. figure:: \idir Conf-Diagram + :alt: Relation between resource names and passwords + :width: 80.0% + + Relation between resource names and passwords + +In the left column, you can see the Director, Storage, and Client +resources and their corresponding names and passwords – these are all in +:raw-latex:`\file{bareos-dir.conf}`. In the right column the +corresponding values in the Console, Storage daemon (SD), and File +daemon (FD) configuration files are shown. + +Please note that the address :raw-latex:`\host{fw-sd}`, that appears in +the Storage resource of the Director, is passed to the File daemon in +symbolic form. The File daemon then resolves it to an IP address. For +this reason you must use either an IP address or a resolvable fully +qualified name. A name such as :raw-latex:`\host{localhost}`, not being +a fully qualified name, will resolve in the File daemon to the +:raw-latex:`\host{localhost}` of the File daemon, which is most likely +not what is desired. The password used for the File daemon to authorize +with the Storage daemon is a temporary password unique to each Job +created by the daemons and is not specified in any .conf file. + +.. |image| image:: \idir bareos-read-configuration diff --git a/docs/manuals/en/new_main_reference/source/consoleconf.rst b/docs/manuals/en/new_main_reference/source/consoleconf.rst index 1c0348ea845..6fab84538ca 100644 --- a/docs/manuals/en/new_main_reference/source/consoleconf.rst +++ b/docs/manuals/en/new_main_reference/source/consoleconf.rst @@ -3,13 +3,8 @@ Console Configuration ===================== -.. index:: - triple: General; Configuration; Console -.. _`Configuration`: - -.. index:: General; Console Configuration -.. _`Console Configuration`: - +:raw-latex:`\index[general]{Configuration!Console}` +:raw-latex:`\index[general]{Console Configuration}` The Console configuration file is the simplest of all the configuration files, and in general, you should not need to change it except for the @@ -18,7 +13,7 @@ Director or Directors. For a general discussion of the syntax of configuration files and their resources including the data types recognized by **Bareos**, please see -the :ref:`ConfigureChapter Configuration` chapter of this +the :raw-latex:`\ilink{Configuration}{ConfigureChapter}` chapter of this manual. The following Console Resource definition must be defined: @@ -28,13 +23,8 @@ The following Console Resource definition must be defined: Director Resource ----------------- -.. index:: General; Director Resource -.. _`Director Resource`: - -.. index:: - triple: General; Resource; Director -.. _`Resource`: - +:raw-latex:`\index[general]{Director Resource}` +:raw-latex:`\index[general]{Resource!Director}` The Director resource defines the attributes of the Director running on the network. You may have multiple Director resource specifications in a @@ -112,20 +102,15 @@ An actual example might be: Console Resource ---------------- -.. index:: General; Console Resource -.. _`Console Resource`: - -.. index:: - triple: General; Resource; Console -.. _`Resource`: - +:raw-latex:`\index[general]{Console Resource}` +:raw-latex:`\index[general]{Resource!Console}` There are three different kinds of consoles, which the administrator or user can use to interact with the Director. These three kinds of consoles comprise three different security levels. -- The first console type is an **admin** or - **anonymous}` or :raw-latex:`\name{default** console, +- The first console type is an :raw-latex:`\name{admin}` or + :raw-latex:`\name{anonymous}` or :raw-latex:`\name{default}` console, which has full privileges. There is no console resource necessary for this type since the password is specified in the Director resource. Typically you would use this console only for administrators. @@ -180,76 +165,70 @@ consoles as noted above. Example Console Configuration File ---------------------------------- -.. index:: - triple: General; Configuration; bconsole -.. _`Configuration`: - +:raw-latex:`\index[general]{Configuration!bconsole}` A Console configuration file might look like this: -.. raw:: latex +:: - \begin{bconfig}{bconsole configuration} - Director { - Name = "bareos.example.com-dir" - address = "bareos.example.com" - Password = "PASSWORD" - } - \end{bconfig} + {bconsole configuration} + Director { + Name = "bareos.example.com-dir" + address = "bareos.example.com" + Password = "PASSWORD" + } With this configuration, the console program (e.g. -:command:`bconsole`) will try to connect to a -|bareosDir| named **bareos.example.com-dir** -at the network address **bareos.example.com** and +:raw-latex:`\command{verbatim}`) will try to connect to a +|bareosDir| named :raw-latex:`\name{bareos.example.com-dir}` +at the network address :raw-latex:`\host{bareos.example.com}` and authenticate to the admin console using the password -**PASSWORD**. +:raw-latex:`\name{PASSWORD}`. -.. _sec:ConsoleAccessExample: +.. _sec-ConsoleAccessExample: Using Named Consoles ~~~~~~~~~~~~~~~~~~~~ The following configuration files were supplied by Phil Stracchino. -To use named consoles from :command:`bconsole`, use a -*bconsole.conf* configuration file like this: +To use named consoles from :raw-latex:`\command{verbatim}`, use a +:raw-latex:`\file{bconsole.conf}` configuration file like this: -.. raw:: latex +:: - \begin{bconfig}{bconsole: restricted-user} - Director { - Name = bareos-dir - Address = myserver - Password = "XXXXXXXXXXX" - } + {bconsole: restricted-user} + Director { + Name = bareos-dir + Address = myserver + Password = "XXXXXXXXXXX" + } - Console { - Name = restricted-user - Password = "RUPASSWORD" - } - \end{bconfig} + Console { + Name = restricted-user + Password = "RUPASSWORD" + } Where the Password in the Director section is deliberately incorrect and the Console resource is given a name, in this case -**restricted-user**. Then in the Director +:raw-latex:`\argument{restricted-user}`. Then in the Director configuration (not directly accessible by the user), we define: -.. raw:: latex +:: - \begin{bareosConfigResource}{bareos-dir}{console}{restricted-user} - Console { - Name = restricted-user - Password = "RUPASSWORD" - JobACL = "Restricted Client Save" - ClientACL = restricted-client - StorageACL = main-storage - ScheduleACL = *all* - PoolACL = *all* - FileSetACL = "Restricted Client's FileSet" - CatalogACL = MyCatalog - CommandACL = run - } - \end{bareosConfigResource} + {bareos-dir}{console}{restricted-user} + Console { + Name = restricted-user + Password = "RUPASSWORD" + JobACL = "Restricted Client Save" + ClientACL = restricted-client + StorageACL = main-storage + ScheduleACL = *all* + PoolACL = *all* + FileSetACL = "Restricted Client's FileSet" + CatalogACL = MyCatalog + CommandACL = run + } The user login into the Director from his Console will get logged in as :raw-latex:`\resourcename{Dir}{Console}{restricted-user}` and he will @@ -262,60 +241,58 @@ Schedule or Pool, a FileSet named :raw-latex:`\resourcename*{Dir}{FileSet}{Restricted Client's FileSet}`, a Catalog named :raw-latex:`\resourcename*{Dir}{Catalog}{MyCatalog}` and the only command he can use in the Console is the -:command:`run ` command. In other words, this user is +:raw-latex:`\bcommand{run}{}` command. In other words, this user is rather limited in what he can see and do with Bareos. For details how to configure ACLs, see the :raw-latex:`\dt{Acl}` data type description. -The following is an example of a *bconsole.conf* file +The following is an example of a :raw-latex:`\file{bconsole.conf}` file that can access several Directors and has different Consoles depending on the Director: -.. raw:: latex +:: - \begin{bconfig}{bconsole: multiple consoles} - Director { - Name = bareos-dir - Address = myserver - Password = "XXXXXXXXXXX" # no, really. this is not obfuscation. - } + {bconsole: multiple consoles} + Director { + Name = bareos-dir + Address = myserver + Password = "XXXXXXXXXXX" # no, really. this is not obfuscation. + } - Director { - Name = SecondDirector - Address = secondserver - Password = "XXXXXXXXXXX" # no, really. this is not obfuscation. - } + Director { + Name = SecondDirector + Address = secondserver + Password = "XXXXXXXXXXX" # no, really. this is not obfuscation. + } - Console { - Name = restricted-user - Password = "RUPASSWORD" - Director = MyDirector - } + Console { + Name = restricted-user + Password = "RUPASSWORD" + Director = MyDirector + } - Console { - Name = restricted-user2 - Password = "OTHERPASSWORD" - Director = SecondDirector - } - \end{bconfig} + Console { + Name = restricted-user2 + Password = "OTHERPASSWORD" + Director = SecondDirector + } The second Director referenced at :raw-latex:`\resourcename{Dir}{Director}{secondserver}` might look like the following: -.. raw:: latex +:: - \begin{bareosConfigResource}{bareos-dir}{console}{restricted-user2} - Console { - Name = restricted-user2 - Password = "OTHERPASSWORD" - JobACL = "Restricted Client Save" - ClientACL = restricted-client - StorageACL = second-storage - ScheduleACL = *all* - PoolACL = *all* - FileSetACL = "Restricted Client's FileSet" - CatalogACL = RestrictedCatalog - CommandACL = run, restore - WhereACL = "/" - } - \end{bareosConfigResource} + {bareos-dir}{console}{restricted-user2} + Console { + Name = restricted-user2 + Password = "OTHERPASSWORD" + JobACL = "Restricted Client Save" + ClientACL = restricted-client + StorageACL = second-storage + ScheduleACL = *all* + PoolACL = *all* + FileSetACL = "Restricted Client's FileSet" + CatalogACL = RestrictedCatalog + CommandACL = run, restore + WhereACL = "/" + } diff --git a/docs/manuals/en/new_main_reference/source/critical.rst b/docs/manuals/en/new_main_reference/source/critical.rst index b2f02088f73..341149e5658 100644 --- a/docs/manuals/en/new_main_reference/source/critical.rst +++ b/docs/manuals/en/new_main_reference/source/critical.rst @@ -3,13 +3,8 @@ Critical Items to Implement Before Production ============================================= -.. index:: - triple: General; Production; Critical Items to Implement Before -.. _`Production`: - -.. index:: General; Critical Items to Implement Before Production -.. _`Critical Items to Implement Before Production`: - +:raw-latex:`\index[general]{Production!Critical Items to Implement Before}` +:raw-latex:`\index[general]{Critical Items to Implement Before Production}` We recommend you take your time before implementing a production on a Bareos backup system since Bareos is a rather complex program, and if @@ -22,16 +17,12 @@ most of the major problems that can occur. It goes without saying that if you ever find that we have left out an important point, please inform us, so that we can document it to the benefit of everyone. - - -.. _`Critical`: Critical +:raw-latex:`\label{Critical}` Critical Items -------------- -.. index:: General; Critical Items -.. _`Critical Items`: - +:raw-latex:`\index[general]{Critical Items}` The following assumes that you have installed Bareos, you more or less understand it, you have at least worked through the tutorial or have @@ -44,22 +35,22 @@ order you would use in setting up a production system (if you already are in production, use the checklist anyway). - Test your tape drive for compatibility with Bareos by using the test - command of the :ref:`btape btape` program. + command of the :raw-latex:`\ilink{btape}{btape}` program. - Test the end of tape handling of your tape drive by using the fill - command in the :ref:`btape btape` program. + command in the :raw-latex:`\ilink{btape}{btape}` program. - Do at least one restore of files. If you backup multiple OS types (Linux, Solaris, HP, MacOS, FreeBSD, Win32, ...), restore files from each system type. The - :ref:`RestoreChapter Restoring Files` chapter shows + :raw-latex:`\ilink{Restoring Files}{RestoreChapter}` chapter shows you how. - Write a bootstrap file to a separate system for each backup job. See - **Write Bootstrap** (Dir configuration, Job resource) + :raw-latex:`\linkResourceDirective{Dir}{Job}{Write Bootstrap}` directive and more details are available in the - :ref:`BootstrapChapter` chapter. Also, the default - *bareos-dir.conf* comes with a Write Bootstrap + :raw-latex:`\nameref{BootstrapChapter}` chapter. Also, the default + :raw-latex:`\file{bareos-dir.conf}` comes with a Write Bootstrap directive defined. This allows you to recover the state of your system as of the last backup. @@ -67,7 +58,7 @@ are in production, use the checklist anyway). bareos-dir.conf file. The backup script is installed by default and should handle any database, though you may want to make your own local modifications. See also - :ref:`BackingUpBareos Backing Up Your Bareos Database` + :raw-latex:`\ilink{Backing Up Your Bareos Database}{BackingUpBareos}` for more information. - Write a bootstrap file for the catalog. An example of this is found @@ -95,26 +86,24 @@ are in production, use the checklist anyway). Recommended Items ----------------- -.. index:: General; Recommended Items -.. _`Recommended Items`: - +:raw-latex:`\index[general]{Recommended Items}` Although these items may not be critical, they are recommended and will help you avoid problems. -- Read the :ref:`QuickStartChapter` chapter +- Read the :raw-latex:`\nameref{QuickStartChapter}` chapter - After installing and experimenting with Bareos, read and work carefully through the examples in the - :ref:`TutorialChapter` chapter of this manual. + :raw-latex:`\nameref{TutorialChapter}` chapter of this manual. -- Learn what each of the :ref:`sec:Utilities` does. +- Learn what each of the :raw-latex:`\nameref{sec-Utilities}` does. - | Set up reasonable retention periods so that your catalog does not grow to be too big. See the following three chapters: - | :ref:`RecyclingChapter`, - | :ref:`DiskChapter`, - | :ref:`PoolsChapter`. + | :raw-latex:`\nameref{RecyclingChapter}`, + | :raw-latex:`\nameref{DiskChapter}`, + | :raw-latex:`\nameref{PoolsChapter}`. If you absolutely must implement a system where you write a different tape each night and take it offsite in the morning. We recommend that diff --git a/docs/manuals/en/new_main_reference/source/dataencryption.rst b/docs/manuals/en/new_main_reference/source/dataencryption.rst index 00250c14494..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/dataencryption.rst +++ b/docs/manuals/en/new_main_reference/source/dataencryption.rst @@ -1,203 +1 @@ -.. _DataEncryption: -Data Encryption -=============== - -.. index:: General; Data Encryption -.. _`Data Encryption`: - -.. index:: - triple: General; Encryption; Data -.. _`Encryption`: - - -Bareos permits file data encryption and signing within the File Daemon -(or Client) prior to sending data to the Storage Daemon. Upon -restoration, file signatures are validated and any mismatches are -reported. At no time does the Director or the Storage Daemon have access -to unencrypted file contents. - -.. raw:: latex - - \warning{These feature is only available, if Bareos is build against OpenSSL.} - -It is very important to specify what this implementation does NOT do: - -- The implementation does not encrypt file metadata such as file path - names, permissions, ownership and extended attributes. However, Mac - OS X resource forks are encrypted. - -Encryption and signing are implemented using RSA private keys coupled -with self-signed x509 public certificates. This is also sometimes known -as PKI or Public Key Infrastructure. - -Each File Daemon should be given its own unique private/public key pair. -In addition to this key pair, any number of "Master Keys" may be -specified – these are key pairs that may be used to decrypt any backups -should the File Daemon key be lost. Only the Master Key’s public -certificate should be made available to the File Daemon. Under no -circumstances should the Master Private Key be shared or stored on the -Client machine. - -The Master Keys should be backed up to a secure location, such as a CD -placed in a in a fire-proof safe or bank safety deposit box. The Master -Keys should never be kept on the same machine as the Storage Daemon or -Director if you are worried about an unauthorized party compromising -either machine and accessing your encrypted backups. - -While less critical than the Master Keys, File Daemon Keys are also a -prime candidate for off-site backups; burn the key pair to a CD and send -the CD home with the owner of the machine. - -.. raw:: latex - - \warning{If you lose your encryption keys, backups will be unrecoverable. - {\bf always} store a copy of your master keys in a secure, off-site location.} - -The basic algorithm used for each backup session (Job) is: - -#. The File daemon generates a session key. - -#. The FD encrypts that session key via PKE for all recipients (the file - daemon, any master keys). - -#. The FD uses that session key to perform symmetric encryption on the - data. - -Encryption Technical Details ----------------------------- - -.. index:: - triple: General; Encryption; Technical Details -.. _`Encryption`: - - -The implementation uses 128bit AES-CBC, with RSA encrypted symmetric -session keys. The RSA key is user supplied. If you are running OpenSSL -:math:`>=` 0.9.8, the signed file hash uses SHA-256, otherwise SHA-1 is -used. - -End-user configuration settings for the algorithms are not currently -exposed, only the algorithms listed above are used. However, the data -written to Volume supports arbitrary symmetric, asymmetric, and digest -algorithms for future extensibility, and the back-end implementation -currently supports: - -:: - - Symmetric Encryption: - - 128, 192, and 256-bit AES-CBC - - Blowfish-CBC - - Asymmetric Encryption (used to encrypt symmetric session keys): - - RSA - - Digest Algorithms: - - MD5 - - SHA1 - - SHA256 - - SHA512 - -The various algorithms are exposed via an entirely re-usable, -OpenSSL-agnostic API (ie, it is possible to drop in a new encryption -backend). The Volume format is DER-encoded ASN.1, modeled after the -Cryptographic Message Syntax from RFC 3852. Unfortunately, using CMS -directly was not possible, as at the time of coding a free software -streaming DER decoder/encoder was not available. - -Generating Private/Public Encryption Keys ------------------------------------------ - -.. index:: - triple: General; Encryption; Generating Private/Public Encryption Keypairs -.. _`Encryption`: - - -Generate a Master Key Pair with: - -.. raw:: latex - - \footnotesize - -:: - - openssl genrsa -out master.key 2048 - openssl req -new -key master.key -x509 -out master.cert - -.. raw:: latex - - \normalsize - -Generate a File Daemon Key Pair for each FD: - -.. raw:: latex - - \footnotesize - -:: - - openssl genrsa -out fd-example.key 2048 - openssl req -new -key fd-example.key -x509 -out fd-example.cert - cat fd-example.key fd-example.cert >fd-example.pem - -.. raw:: latex - - \normalsize - -Note, there seems to be a lot of confusion around the file extensions -given to these keys. For example, a .pem file can contain all the -following: private keys (RSA and DSA), public keys (RSA and DSA) and -(x509) certificates. It is the default format for OpenSSL. It stores -data Base64 encoded DER format, surrounded by ASCII headers, so is -suitable for text mode transfers between systems. A .pem file may -contain any number of keys either public or private. We use it in cases -where there is both a public and a private key. - -Above we have used the .cert extension to refer to X509 certificate -encoding that contains only a single public key. - -Example Data Encryption Configurations (bareos-fd.conf) -------------------------------------------------------- - -.. index:: - triple: General; Example; Data Encryption Configuration File -.. _`Example`: - - -.. raw:: latex - - \bconfigInput{config/FdClientPki.conf} - -Decrypting with a Master Key ----------------------------- - -.. index:: General; Decrypting with a Master Key -.. _`Decrypting with a Master Key`: - -.. index:: - triple: General; Encryption; Decrypting with a Master Key -.. _`Encryption`: - - -It is preferable to retain a secure, non-encrypted copy of the client’s -own encryption keypair. However, should you lose the client’s keypair, -recovery with the master keypair is possible. - -You must: - -- Concatenate the master private and public key into a single keypair - file, ie: - - :: - - cat master.key master.cert > master.keypair - - -- Set the PKI Keypair statement in your bareos configuration file: - - :: - - PKI Keypair = master.keypair - -- Start the restore. The master keypair will be used to decrypt the - file data. diff --git a/docs/manuals/en/new_main_reference/source/debug.rst b/docs/manuals/en/new_main_reference/source/debug.rst index ebfb7848c78..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/debug.rst +++ b/docs/manuals/en/new_main_reference/source/debug.rst @@ -1,175 +1 @@ -.. index:: General; Crash -.. index:: - triple: General; Debug; crash - -This chapter describes, how to debug Bareos, when the program crashes. -If you are just interested about how to get more information about a -running Bareos daemon, please read -:ref:`sec:debug-messages`. - -If you are running on a Linux system, and you have a set of working -configuration files, it is very unlikely that **Bareos** will crash. As -with all software, however, it is inevitable that someday, it may crash. - -This chapter explains what you should do if one of the three **Bareos** -daemons (Director, File, Storage) crashes. When we speak of crashing, we -mean that the daemon terminates abnormally because of an error. There -are many cases where Bareos detects errors (such as PIPE errors) and -will fail a job. These are not considered crashes. In addition, under -certain conditions, Bareos will detect a fatal in the configuration, -such as lack of permission to read/write the working directory. In that -case, Bareos will force itself to crash with a SEGFAULT. However, before -crashing, Bareos will normally display a message indicating why. For -more details, please read on. - -Traceback -========= - -.. index:: General; Traceback - -Each of the three Bareos daemons has a built-in exception handler which, -in case of an error, will attempt to produce a traceback. If successful -the traceback will be emailed to you. - -For this to work, you need to ensure that a few things are setup -correctly on your system: - -#. You must have a version of Bareos with debug information and not - stripped of debugging symbols. When using a packaged version of - Bareos, this requires to install the Bareos debug packages - (**bareos-debug** on RPM based systems, - **bareos-dbg** on Debian based systems). - -#. On Linux, :command:`gdb` (the GNU debugger) must be - installed. On some systems such as Solaris, - :command:`gdb` may be replaced by - :command:`dbx`. - -#. By default, btraceback uses :command:`bsmtp` to send the - traceback via email. Therefore it expects a local mail transfer - daemon running. It send the traceback to - **root@localhost** via - **localhost**. - -#. Some Linux distributions, e.g. - Ubuntu -.. index:: - triple: General; Platform!Ubuntu; Debug, disable - the possibility to examine the memory of other processes. While this - is a good idea for hardening a system, our debug mechanismen will - fail. To disable this feature, run (as root): - - .. raw:: latex - - \begin{commands}{disable ptrace protection to enable debugging (required on Ubuntu Linux)} - test -e /proc/sys/kernel/yama/ptrace_scope && echo 0 > /proc/sys/kernel/yama/ptrace_scope - \end{commands} - -If all the above conditions are met, the daemon that crashes will -produce a traceback report and email it. If the above conditions are not -true, you can run the debugger by hand as described below. - -Testing The Traceback -===================== - - -.. index:: - triple: General; Traceback; Test - -To “manually” test the traceback feature, you simply start **Bareos** -then obtain the **PID** of the main daemon thread (there are multiple -threads). The output produced here will look different depending on what -OS and what version of the kernel you are running. - -.. raw:: latex - - \begin{commands}{get the process ID of a running Bareos daemon} - ps fax | grep bareos-dir - 2103 ? S 0:00 /usr/sbin/bareos-dir - \end{commands} - -which in this case is 2103. Then while Bareos is running, you call the -program giving it the path to the Bareos executable and the **PID**. In -this case, it is: - -.. raw:: latex - - \begin{commands}{get traceback of running Bareos director daemon} - btraceback /usr/sbin/bareos-dir 2103 - \end{commands} - -It should produce an email showing you the current state of the daemon -(in this case the Director), and then exit leaving **Bareos** running as -if nothing happened. If this is not the case, you will need to correct -the problem by modifying the :command:`btraceback` script. - -Getting A Traceback On Other Systems ------------------------------------- - -It should be possible to produce a similar traceback on systems other -than Linux, either using :command:`gdb` or some other -debugger. Solaris -.. index:: - triple: General; Platform!Solaris; Debug -with :command:`dbx` loaded works quite fine. On other -systems, you will need to modify the :command:`btraceback` -program to invoke the correct debugger, and possibly correct the -*btraceback.gdb* script to have appropriate commands -for your debugger. Please keep in mind that for any debugger to work, it -will most likely need to run as root. - -Manually Running Bareos Under The Debugger -========================================== - -If for some reason you cannot get the automatic traceback, or if you -want to interactively examine the variable contents after a crash, you -can run Bareos under the debugger. Assuming you want to run the Storage -daemon under the debugger (the technique is the same for the other -daemons, only the name changes), you would do the following: - -#. The Director and the File daemon should be running but the Storage - daemon should not. - -#. Start the Storage daemon under the debugger: - - .. raw:: latex - - \begin{commands}{run the Bareos Storage daemon in the debugger} - gdb --args /usr/sbin/bareos-sd -f -s -d 200 - (gdb) run - \end{commands} - - Parameter: - - -f - foreground - - -s - no signals - - -d nnn - debug level - - See section - :ref:`daemon command line options daemon-command-line-options` - for a detailed list of options. - -#. At this point, Bareos will be fully operational. - -#. In another shell command window, start the Console program and do - what is necessary to cause Bareos to die. - -#. When Bareos crashes, the **gdb** shell window will become active and - **gdb** will show you the error that occurred. - -#. To get a general traceback of all threads, issue the following - command: - - .. raw:: latex - - \begin{commands}{run the Bareos Storage daemon in the debugger} - (gdb) thread apply all bt - \end{commands} - - After that you can issue any debugging command. diff --git a/docs/manuals/en/new_main_reference/source/dirdconf.rst b/docs/manuals/en/new_main_reference/source/dirdconf.rst index 4c42d478d7b..1614e590dee 100644 --- a/docs/manuals/en/new_main_reference/source/dirdconf.rst +++ b/docs/manuals/en/new_main_reference/source/dirdconf.rst @@ -3,33 +3,19 @@ Director Configuration ====================== - - -.. _`DirectorConfChapter`: DirectorConfChapter -.. index:: - triple: General; Director; Configuration -.. _`Director`: - -.. index:: - triple: General; Configuration; Director -.. _`Configuration`: - +:raw-latex:`\label{DirectorConfChapter}` +:raw-latex:`\index[general]{Director!Configuration}` +:raw-latex:`\index[general]{Configuration!Director}` Of all the configuration files needed to run Bareos, the Director’s is the most complicated and the one that you will need to modify the most often as you add clients or modify the FileSets. For a general discussion of configuration files and resources including -the recognized data types see :ref:`ConfigureChapter`. - -.. index:: - triple: General; Types; Director Resource -.. _`Types`: - -.. index:: - triple: General; Director; Resource Types -.. _`Director`: +the recognized data types see :raw-latex:`\nameref{ConfigureChapter}`. +:raw-latex:`\index[general]{Types!Director Resource}` +:raw-latex:`\index[general]{Director!Resource Types}` :raw-latex:`\index[dir]{Resource Types}` Everything revolves around a job and is tied to a job in one way or @@ -37,49 +23,49 @@ another. The |bareosDir| knows about following resource types: -- :ref:`DirectorResourceDirector` – to define the +- :raw-latex:`\nameref{DirectorResourceDirector}` – to define the Director’s name and its access password used for authenticating the Console program. Only a single Director resource definition may appear in the Director’s configuration file. -- :ref:`DirectorResourceJob` – to define the +- :raw-latex:`\nameref{DirectorResourceJob}` – to define the backup/restore Jobs and to tie together the Client, FileSet and Schedule resources to be used for each Job. Normally, you will Jobs of different names corresponding to each client (i.e. one Job per client, but a different one with a different name for each client). -- :ref:`DirectorResourceJobDefs` – optional resource +- :raw-latex:`\nameref{DirectorResourceJobDefs}` – optional resource for providing defaults for Job resources. -- :ref:`DirectorResourceSchedule` – to define when a +- :raw-latex:`\nameref{DirectorResourceSchedule}` – to define when a Job has to run. You may have any number of Schedules, but each job will reference only one. -- :ref:`DirectorResourceFileSet` – to define the set of +- :raw-latex:`\nameref{DirectorResourceFileSet}` – to define the set of files to be backed up for each Client. You may have any number of FileSets but each Job will reference only one. -- :ref:`DirectorResourceClient` – to define what Client +- :raw-latex:`\nameref{DirectorResourceClient}` – to define what Client is to be backed up. You will generally have multiple Client definitions. Each Job will reference only a single client. -- :ref:`DirectorResourceStorage` – to define on what +- :raw-latex:`\nameref{DirectorResourceStorage}` – to define on what physical device the Volumes should be mounted. You may have one or more Storage definitions. -- :ref:`DirectorResourcePool` – to define the pool of +- :raw-latex:`\nameref{DirectorResourcePool}` – to define the pool of Volumes that can be used for a particular Job. Most people use a single default Pool. However, if you have a large number of clients or volumes, you may want to have multiple Pools. Pools allow you to restrict a Job (or a Client) to use only a particular set of Volumes. -- :ref:`DirectorResourceCatalog` – to define in what +- :raw-latex:`\nameref{DirectorResourceCatalog}` – to define in what database to keep the list of files and the Volume names where they are backed up. Most people only use a single catalog. It is possible, however not adviced and not supported to use multiple catalogs, see - :ref:`MultipleCatalogs`. + :raw-latex:`\nameref{MultipleCatalogs}`. -- :ref:`DirectorResourceMessages` – to define where +- :raw-latex:`\nameref{DirectorResourceMessages}` – to define where error and information messages are to be sent or logged. You may define multiple different message resources and hence direct particular classes of messages to different users or locations @@ -90,47 +76,33 @@ The |bareosDir| knows about following resource types: Director Resource ----------------- -.. index:: General; Director Resource -.. _`Director Resource`: - -.. index:: - triple: General; Resource; Director -.. _`Resource`: - +:raw-latex:`\index[general]{Director Resource}` +:raw-latex:`\index[general]{Resource!Director}` The Director resource defines the attributes of the Directors running on the network. Only a single Director resource is allowed. The following is an example of a valid Director resource definition: -.. raw:: latex +:: - \begin{bconfig}{Director Resource example} - Director { - Name = bareos-dir - Password = secretpassword - QueryFile = "/etc/bareos/query.sql" - Maximum Concurrent Jobs = 10 - Messages = Daemon - } - \end{bconfig} + {Director Resource example} + Director { + Name = bareos-dir + Password = secretpassword + QueryFile = "/etc/bareos/query.sql" + Maximum Concurrent Jobs = 10 + Messages = Daemon + } .. _DirectorResourceJob: Job Resource ------------ - - -.. _`JobResource`: JobResource -.. index:: - triple: General; Resource; Job -.. _`Resource`: - -.. index:: - triple: General; Job; Resource -.. _`Job`: - +:raw-latex:`\label{JobResource}` +:raw-latex:`\index[general]{Resource!Job}` +:raw-latex:`\index[general]{Job!Resource}` The Job resource defines a Job (Backup, Restore, ...) that Bareos must perform. Each Job resource definition contains the name of a Client and @@ -164,35 +136,28 @@ the FileSets may be the same). The following is an example of a valid Job resource definition: -.. raw:: latex - - \begin{bconfig}{Job Resource Example} - Job { - Name = "Minou" - Type = Backup - Level = Incremental # default - Client = Minou - FileSet="Minou Full Set" - Storage = DLTDrive - Pool = Default - Schedule = "MinouWeeklyCycle" - Messages = Standard - } - \end{bconfig} +:: + + {Job Resource Example} + Job { + Name = "Minou" + Type = Backup + Level = Incremental # default + Client = Minou + FileSet="Minou Full Set" + Storage = DLTDrive + Pool = Default + Schedule = "MinouWeeklyCycle" + Messages = Standard + } .. _DirectorResourceJobDefs: JobDefs Resource ---------------- -.. index:: - triple: General; Job; JobDefs Resource -.. _`Job`: - -.. index:: - triple: General; Resource; JobDefs -.. _`Resource`: - +:raw-latex:`\index[general]{Job!JobDefs Resource}` +:raw-latex:`\index[general]{Resource!JobDefs}` The JobDefs resource permits all the same directives that can appear in a Job resource. However, a JobDefs resource does not create a Job, @@ -206,14 +171,8 @@ Only the changes from the defaults need to be mentioned in each Job. Schedule Resource ----------------- -.. index:: - triple: General; Resource; Schedule -.. _`Resource`: - -.. index:: - triple: General; Schedule; Resource -.. _`Schedule`: - +:raw-latex:`\index[general]{Resource!Schedule}` +:raw-latex:`\index[general]{Schedule!Resource}` The Schedule resource provides a means of automatically scheduling a Job as well as the ability to override the default Level, Pool, Storage and @@ -241,68 +200,63 @@ An example schedule resource that is named **WeeklyCycle** and runs a job with level full each Sunday at 2:05am and an incremental job Monday through Saturday at 2:05am is: -.. raw:: latex +:: - \begin{bconfig}{Schedule Example} - Schedule { - Name = "WeeklyCycle" - Run = Level=Full sun at 2:05 - Run = Level=Incremental mon-sat at 2:05 - } - \end{bconfig} + {Schedule Example} + Schedule { + Name = "WeeklyCycle" + Run = Level=Full sun at 2:05 + Run = Level=Incremental mon-sat at 2:05 + } An example of a possible monthly cycle is as follows: -.. raw:: latex +:: - \begin{bconfig}{} - Schedule { - Name = "MonthlyCycle" - Run = Level=Full Pool=Monthly 1st sun at 2:05 - Run = Level=Differential 2nd-5th sun at 2:05 - Run = Level=Incremental Pool=Daily mon-sat at 2:05 - } - \end{bconfig} + {} + Schedule { + Name = "MonthlyCycle" + Run = Level=Full Pool=Monthly 1st sun at 2:05 + Run = Level=Differential 2nd-5th sun at 2:05 + Run = Level=Incremental Pool=Daily mon-sat at 2:05 + } The first of every month: -.. raw:: latex +:: - \begin{bconfig}{} - Schedule { - Name = "First" - Run = Level=Full on 1 at 2:05 - Run = Level=Incremental on 2-31 at 2:05 - } - \end{bconfig} + {} + Schedule { + Name = "First" + Run = Level=Full on 1 at 2:05 + Run = Level=Incremental on 2-31 at 2:05 + } The last friday of the month (i.e. the last friday in the last week of the month) -.. raw:: latex +:: - \begin{bconfig}{} - Schedule { - Name = "Last Friday" - Run = Level=Full last fri at 21:00 - } - \end{bconfig} + {} + Schedule { + Name = "Last Friday" + Run = Level=Full last fri at 21:00 + } Every 10 minutes: -.. raw:: latex +:: - \begin{bconfig}{} - Schedule { - Name = "TenMinutes" - Run = Level=Full hourly at 0:05 - Run = Level=Full hourly at 0:15 - Run = Level=Full hourly at 0:25 - Run = Level=Full hourly at 0:35 - Run = Level=Full hourly at 0:45 - Run = Level=Full hourly at 0:55 - } - \end{bconfig} + {} + Schedule { + Name = "TenMinutes" + Run = Level=Full hourly at 0:05 + Run = Level=Full hourly at 0:15 + Run = Level=Full hourly at 0:25 + Run = Level=Full hourly at 0:35 + Run = Level=Full hourly at 0:45 + Run = Level=Full hourly at 0:55 + } The **modulo scheduler** makes it easy to specify schedules like odd or even days/weeks, or more generally every n days or weeks. It is called @@ -313,42 +267,38 @@ part determines on which day/week the job should be run first. E.g. if you want to run a backup in a 5-week-cycle, starting on week 3, you set it up as w03/w05. -.. raw:: latex +:: + + {Schedule Examples: modulo} + Schedule { + Name = "Odd Days" + Run = 1/2 at 23:10 + } + + Schedule { + Name = "Even Days" + Run = 2/2 at 23:10 + } - \begin{bconfig}{Schedule Examples: modulo} - Schedule { - Name = "Odd Days" - Run = 1/2 at 23:10 - } - - Schedule { - Name = "Even Days" - Run = 2/2 at 23:10 - } - - Schedule { - Name = "On the 3rd week in a 5-week-cycle" - Run = w03/w05 at 23:10 - } - - Schedule { - Name = "Odd Weeks" - Run = w01/w02 at 23:10 - } - - Schedule { - Name = "Even Weeks" - Run = w02/w02 at 23:10 - } - \end{bconfig} + Schedule { + Name = "On the 3rd week in a 5-week-cycle" + Run = w03/w05 at 23:10 + } + + Schedule { + Name = "Odd Weeks" + Run = w01/w02 at 23:10 + } + + Schedule { + Name = "Even Weeks" + Run = w02/w02 at 23:10 + } Technical Notes on Schedules ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. index:: - triple: General; Schedule; Technical Notes on Schedules -.. _`Schedule`: - +:raw-latex:`\index[general]{Schedule!Technical Notes on Schedules}` Internally Bareos keeps a schedule as a bit mask. There are six masks and a minute field to each schedule. The masks are hour, day of the @@ -375,17 +325,9 @@ that the bit mask is zero based, and Sunday is the first day of the week FileSet Resource ---------------- - - -.. _`FileSetResource`: FileSetResource -.. index:: - triple: General; Resource; FileSet -.. _`Resource`: - -.. index:: - triple: General; FileSet; Resource -.. _`FileSet`: - +:raw-latex:`\label{FileSetResource}` +:raw-latex:`\index[general]{Resource!FileSet}` +:raw-latex:`\index[general]{FileSet!Resource}` The FileSet resource defines what files are to be included or excluded in a backup job. A **FileSet** resource is required for each backup Job. @@ -404,13 +346,8 @@ created, Bareos will ensure that the next backup is always a Full save. Client Resource --------------- -.. index:: - triple: General; Resource; Client -.. _`Resource`: - -.. index:: General; Client Resource -.. _`Client Resource`: - +:raw-latex:`\index[general]{Resource!Client}` +:raw-latex:`\index[general]{Client Resource}` The Client (or FileDaemon) resource defines the attributes of the Clients that are served by this Director; that is the machines that are @@ -419,77 +356,64 @@ machine to be backed up. The following is an example of a valid Client resource definition: -.. raw:: latex +:: - \begin{bconfig}{Minimal client resource definition in bareos-dir.conf} - Client { - Name = client1-fd - Address = client1.example.com - Password = "secret" - } - \end{bconfig} + {Minimal client resource definition in bareos-dir.conf} + Client { + Name = client1-fd + Address = client1.example.com + Password = "secret" + } The following is an example of a Quota Configuration in Client resource: -.. raw:: latex +:: - \begin{bconfig}{Quota Configuration in Client resource} - Client { - Name = client1-fd - Address = client1.example.com - Password = "secret" - - # Quota - Soft Quota = 50 mb - Soft Quota Grace Period = 2 days - Strict Quotas = Yes - Hard Quota = 150 mb - Quota Include Failed Jobs = yes - } - \end{bconfig} + {Quota Configuration in Client resource} + Client { + Name = client1-fd + Address = client1.example.com + Password = "secret" + + # Quota + Soft Quota = 50 mb + Soft Quota Grace Period = 2 days + Strict Quotas = Yes + Hard Quota = 150 mb + Quota Include Failed Jobs = yes + } .. _DirectorResourceStorage: Storage Resource ---------------- -.. index:: - triple: General; Resource; Storage -.. _`Resource`: - -.. index:: General; Storage Resource -.. _`Storage Resource`: - +:raw-latex:`\index[general]{Resource!Storage}` +:raw-latex:`\index[general]{Storage Resource}` The Storage resource defines which Storage daemons are available for use by the Director. The following is an example of a valid Storage resource definition: -.. raw:: latex +:: - \begin{bconfig}{Storage resource (tape) example} - Storage { - Name = DLTDrive - Address = lpmatou - Password = storage\_password # password for Storage daemon - Device = "HP DLT 80" # same as Device in Storage daemon - Media Type = DLT8000 # same as MediaType in Storage daemon - } - \end{bconfig} + {Storage resource (tape) example} + Storage { + Name = DLTDrive + Address = lpmatou + Password = storage\_password # password for Storage daemon + Device = "HP DLT 80" # same as Device in Storage daemon + Media Type = DLT8000 # same as MediaType in Storage daemon + } .. _DirectorResourcePool: Pool Resource ------------- -.. index:: - triple: General; Resource; Pool -.. _`Resource`: - -.. index:: General; Pool Resource -.. _`Pool Resource`: - +:raw-latex:`\index[general]{Resource!Pool}` +:raw-latex:`\index[general]{Pool Resource}` The Pool resource defines the set of storage Volumes (tapes or files) to be used by Bareos to write the data. By configuring different Pools, you @@ -505,7 +429,7 @@ attributes (Maximum Jobs, Retention Period, Recycle flag, ...) that will be given to a Volume when it is created. This avoids the need for you to answer a large number of questions when labeling a new Volume. Each of these attributes can later be changed on a Volume by Volume basis using -the :command:`update ` command in the console program. +the :raw-latex:`\bcommand{update}{}` command in the console program. Note that you must explicitly specify which Pool Bareos is to use with each Job. Bareos will not automatically search for the correct Pool. @@ -515,26 +439,26 @@ to the Catalog database. This is done automatically by the Director each time that it starts. Finally, if you change the Pool definition in the Director’s configuration file and restart Bareos, the pool will be updated alternatively you can use the -:command:`update pool` console command to refresh the +:raw-latex:`\bcommand{update}{pool}` console command to refresh the database image. It is this database image rather than the Director’s resource image that is used for the default Volume attributes. Note, for the pool to be automatically created or updated, it must be explicitly referenced by a Job resource. If automatic labeling is not enabled (see -:ref:`AutomaticLabeling`) the physical media must be +:raw-latex:`\nameref{AutomaticLabeling}`) the physical media must be manually labeled. The labeling can either be done with the -:command:`label ` command in the console program or using -the :command:`btape` program. The preferred method is to use -the :command:`label ` command in the console program. +:raw-latex:`\bcommand{label}{}` command in the console program or using +the :raw-latex:`\command{btape}` program. The preferred method is to use +the :raw-latex:`\bcommand{label}{}` command in the console program. Generally, automatic labeling is enabled for -**Device Type = File** (Sd configuration, Device resource) +:raw-latex:`\linkResourceDirectiveValue{Sd}{Device}{Device Type}{File}` and disabled for -**Device Type = Tape** (Sd configuration, Device resource). +:raw-latex:`\linkResourceDirectiveValue{Sd}{Device}{Device Type}{Tape}`. Finally, you must add Volume names (and their attributes) to the Pool. For Volumes to be used by Bareos they must be of the same -**Media Type** (Sd configuration, Device resource) as the +:raw-latex:`\linkResourceDirective{Sd}{Device}{Media Type}` as the archive device specified for the job (i.e. if you are going to back up to a DLT device, the Pool must have DLT volumes defined since 8mm volumes cannot be mounted on a DLT drive). The @@ -547,19 +471,19 @@ ensure that the Volume selected from the Pool is identical to that required by the Storage resource you have specified for the Job. -If you use the :command:`label ` command in the console +If you use the :raw-latex:`\bcommand{label}{}` command in the console program to label the Volumes, they will automatically be added to the Pool, so this last step is not normally required. It is also possible to add Volumes to the database without explicitly labeling the physical volume. This is done with the -:command:`add ` console command. +:raw-latex:`\bcommand{add}{}` console command. As previously mentioned, each time Bareos starts, it scans all the Pools associated with each Catalog, and if the database record does not already exist, it will be created from the Pool Resource definition. If you change the Pool definition, you manually have to call -:command:`update pool` command in the console program to +:raw-latex:`\bcommand{update}{pool}` command in the console program to propagate the changes to existing volumes. The Pool Resource defined in the Director’s configuration may contain @@ -567,27 +491,21 @@ the following directives: The following is an example of a valid Pool resource definition: -.. raw:: latex +:: - \begin{bconfig}{Pool resource example} - Pool { - Name = Default - Pool Type = Backup - } - \end{bconfig} + {Pool resource example} + Pool { + Name = Default + Pool Type = Backup + } .. _TheScratchPool: Scratch Pool ~~~~~~~~~~~~ -.. index:: General; Scratch Pool -.. _`Scratch Pool`: - -.. index:: - triple: General; Pool; Scratch -.. _`Pool`: - +:raw-latex:`\index[general]{Scratch Pool}` +:raw-latex:`\index[general]{Pool!Scratch}` In general, you can give your Pools any name you wish, but there is one important restriction: the Pool named **Scratch**, if it exists behaves @@ -601,13 +519,8 @@ pool into the Pool currently being used by the job. Catalog Resource ---------------- -.. index:: - triple: General; Resource; Catalog -.. _`Resource`: - -.. index:: General; Catalog Resource -.. _`Catalog Resource`: - +:raw-latex:`\index[general]{Resource!Catalog}` +:raw-latex:`\index[general]{Catalog Resource}` The Catalog Resource defines what catalog to use for the current job. Currently, Bareos can only handle a single database server (SQLite, @@ -625,64 +538,52 @@ on a different machine on the network. See below for more details. The following is an example of a valid Catalog resource definition: -.. raw:: latex +:: - \begin{bconfig}{Catalog Resource for Sqlite} - Catalog - { - Name = SQLite - DB Driver = sqlite - DB Name = bareos; - DB User = bareos; - DB Password = "" - } - \end{bconfig} + {Catalog Resource for Sqlite} + Catalog + { + Name = SQLite + DB Driver = sqlite + DB Name = bareos; + DB User = bareos; + DB Password = "" + } or for a Catalog on another machine: -.. raw:: latex +:: - \begin{bconfig}{Catalog Resource for remote MySQL} - Catalog - { - Name = MySQL - DB Driver = mysql - DB Name = bareos - DB User = bareos - DB Password = "secret" - DB Address = remote.example.com - DB Port = 1234 - } - \end{bconfig} + {Catalog Resource for remote MySQL} + Catalog + { + Name = MySQL + DB Driver = mysql + DB Name = bareos + DB User = bareos + DB Password = "secret" + DB Address = remote.example.com + DB Port = 1234 + } .. _DirectorResourceMessages: Messages Resource ----------------- -.. index:: - triple: General; Resource; Messages -.. _`Resource`: - -.. index:: General; Messages Resource -.. _`Messages Resource`: - +:raw-latex:`\index[general]{Resource!Messages}` +:raw-latex:`\index[general]{Messages Resource}` For the details of the Messages Resource, please see the -:ref:`MessagesChapter` of this manual. +:raw-latex:`\nameref{MessagesChapter}` of this manual. .. _DirectorResourceConsole: Console Resource ---------------- -.. index:: General; Console Resource -.. _`Console Resource`: - -.. index:: - triple: General; Resource; Console -.. _`Resource`: - +:raw-latex:`\index[general]{Console Resource}` +:raw-latex:`\index[general]{Resource!Console}` There are three different kinds of consoles, which the administrator or user can use to interact with the Director. These three kinds of @@ -724,9 +625,9 @@ Named Console in that it requires a Console resource definition in both the Director and the Console. In addition, if the console name, provided on the - **Name** (Dir configuration, Console resource) + :raw-latex:`\linkResourceDirective{Dir}{Console}{Name}` directive, is the same as a Client name, that console is - permitted to use the :command:`SetIP ` command to + permitted to use the :raw-latex:`\bcommand{SetIP}{}` command to change the Address directive in the Director’s client resource to the IP address of the Console. This permits portables or other machines using DHCP (non-fixed IP addresses) to "notify" the @@ -735,27 +636,22 @@ Named Console The Console resource is optional and need not be specified. The following directives are permitted within these resources: -The example at :ref:`sec:ConsoleAccessExample` shows how +The example at :raw-latex:`\nameref{sec-ConsoleAccessExample}` shows how to use a console resource for a connection from a client like -:command:`bconsole`. +:raw-latex:`\command{verbatim}`. .. _DirectorResourceProfile: Profile Resource ---------------- -.. index:: General; Profile Resource -.. _`Profile Resource`: - -.. index:: - triple: General; Resource; Profile -.. _`Resource`: - +:raw-latex:`\index[general]{Profile Resource}` +:raw-latex:`\index[general]{Resource!Profile}` The Profile Resource defines a set of ACLs. -:ref:`DirectorResourceConsole`s can be tight to one or +:raw-latex:`\nameref{DirectorResourceConsole}`s can be tight to one or more profiles -(**Profile** (Dir configuration, Console resource)), making it +(:raw-latex:`\linkResourceDirective{Dir}{Console}{Profile}`), making it easier to use a common set of ACLs. .. _DirectorResourceCounter: @@ -763,27 +659,19 @@ easier to use a common set of ACLs. Counter Resource ---------------- -.. index:: - triple: General; Resource; Counter -.. _`Resource`: - -.. index:: General; Counter Resource -.. _`Counter Resource`: - +:raw-latex:`\index[general]{Resource!Counter}` +:raw-latex:`\index[general]{Counter Resource}` The Counter Resource defines a counter variable that can be accessed by variable expansion used for creating Volume labels with the -**Label Format** (Dir configuration, Pool resource) directive. +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Label Format}` directive. .. _SampleDirectorConfiguration: Example Director Configuration File ----------------------------------- -.. index:: - triple: General; Configuration!Director; Example -.. _`Configuration!Director`: - +:raw-latex:`\index[general]{Configuration!Director!Example}` :raw-latex:`\index[dir]{Configuration File Example}` See below an example of a full Director configuration file: diff --git a/docs/manuals/en/new_main_reference/source/disk.rst b/docs/manuals/en/new_main_reference/source/disk.rst index d28b8bb16bc..f024c95c252 100644 --- a/docs/manuals/en/new_main_reference/source/disk.rst +++ b/docs/manuals/en/new_main_reference/source/disk.rst @@ -1,8 +1,6 @@ -.. _DiskChapter: - -.. index:: - triple: General; Volume; Management -.. index:: General; Disk Volumes +:raw-latex:`\label{DiskChapter}` +:raw-latex:`\index[general]{Volume!Management}` +:raw-latex:`\index[general]{Disk Volumes}` This chapter presents most all the features needed to do Volume management. Most of the concepts apply equally well to both tape and @@ -20,18 +18,18 @@ that you can manage either disk or tape volumes. Key Concepts and Resource Records ================================= - -.. index:: - triple: General; Volume!Management; Key Concepts and Resource Records +:raw-latex:`\index[general]{Volume!Management!Key Concepts and Resource Records}` Getting Bareos to write to disk rather than tape in the simplest case is rather easy. In the Storage daemon’s configuration file, you simply define an -Archive Device to be a +:raw-latex:`\linkResourceDirective{Sd}{Device}{Archive Device}` to be a directory. The default directory to store backups on disk is -*/var/lib/bareos/storage* +:raw-latex:`\path`\|/var/lib/bareos/storage|: +.. raw:: latex + \footnotesize :: @@ -45,13 +43,17 @@ directory. The default directory to store backups on disk is AlwaysOpen = no; } +.. raw:: latex + \normalsize Assuming you have the appropriate :raw-latex:`\configresource{Storage}` resource in your Director’s configuration file that references the above Device resource, +.. raw:: latex + \footnotesize :: @@ -63,7 +65,9 @@ Device resource, Media Type = File } +.. raw:: latex + \normalsize Bareos will then write the archive to the file **/var/lib/bareos/storage/** where is the @@ -83,22 +87,20 @@ below. In addition, if you want to use concurrent jobs that write to several different volumes at the same time, you will need to understand a number of other details. An example of such a configuration is given at the end -of this chapter under :ref:`ConcurrentDiskJobs`. +of this chapter under :raw-latex:`\nameref{ConcurrentDiskJobs}`. Pool Options to Limit the Volume Usage -------------------------------------- - -.. index:: - triple: General; Pool; Options to Limit the Volume Usage +:raw-latex:`\index[general]{Pool!Options to Limit the Volume Usage}` Some of the options you have, all of which are specified in the Pool record, are: -- Maximum Volume Jobs: +- :raw-latex:`\linkResourceDirective{Dir}{Pool}{Maximum Volume Jobs}`: write only the specified number of jobs on each Volume. -- Maximum Volume Bytes: +- :raw-latex:`\linkResourceDirective{Dir}{Pool}{Maximum Volume Bytes}`: limit the maximum size of each Volume. Note, if you use disk volumes you should probably limit the Volume @@ -106,7 +108,7 @@ record, are: failure, you are more likely to be able to recover more data if they are in smaller Volumes. -- Volume Use Duration: +- :raw-latex:`\linkResourceDirective{Dir}{Pool}{Volume Use Duration}`: restrict the time between first and last data written to Volume. Note that although you probably would not want to limit the number of @@ -117,28 +119,27 @@ ensure that you rotate through a set of daily Volumes if you wish. As mentioned above, each of those directives is specified in the Pool or Pools that you use for your Volumes. In the case of -Maximum Volume Jobs, -Maximum Volume Bytes and -Volume Use Duration, you +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Maximum Volume Jobs}`, +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Maximum Volume Bytes}` and +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Volume Use Duration}`, you can actually specify the desired value on a Volume by Volume basis. The value specified in the Pool record becomes the default when labeling new Volumes. Once a Volume has been created, it gets its own copy of the Pool defaults, and subsequently changing the Pool will have no effect on existing Volumes. You can either manually change the Volume values, or refresh them from the Pool defaults using the -:command:`update volume` command in the Console. As an +:raw-latex:`\bcommand{update}{volume}` command in the Console. As an example of the use of one of the above, suppose your Pool resource contains: -.. raw:: latex +:: - \begin{bconfig}{Volume Use Duration} - Pool { - Name = File - Pool Type = Backup - Volume Use Duration = 23h - } - \end{bconfig} + {Volume Use Duration} + Pool { + Name = File + Pool Type = Backup + Volume Use Duration = 23h + } then if you run a backup once a day (every 24 hours), Bareos will use a new Volume for each backup, because each Volume it writes can only be @@ -148,15 +149,13 @@ someone on-site during the weekends, because Bareos will want a new Volume and no one will be present to mount it, so no weekend backups will be done until Monday morning. +.. _AutomaticLabeling: + Automatic Volume Labeling ------------------------- - -.. index:: - triple: General; Label; Automatic Volume Labeling - -.. index:: - triple: General; Volume!Labeling; Automatic +:raw-latex:`\index[general]{Label!Automatic Volume Labeling}` +:raw-latex:`\index[general]{Volume!Labeling!Automatic}` Use of the above records brings up another problem – that of labeling your Volumes. For automated disk backup, you can either manually label @@ -169,7 +168,7 @@ This requires some user interaction. Automatic labeling from templates does NOT work with autochangers since Bareos will not access unknown slots. There are several methods of labeling all volumes in an autochanger magazine. For more information on this, please see the -:ref:`AutochangersChapter` chapter. +:raw-latex:`\nameref{AutochangersChapter}` chapter. Automatic Volume labeling is enabled by making a change to both the :raw-latex:`\resourcetype{Dir}{Pool}` resource and to the @@ -180,54 +179,50 @@ is simply the Volume name, to which Bareos will append a four digit number. This number starts at 0001 and is incremented for each Volume the catalog contains. Thus if you modify your Pool resource to be: -.. raw:: latex +:: - \begin{bconfig}{Label Format} - Pool { - Name = File - Pool Type = Backup - Volume Use Duration = 23h - Label Format = "Vol" - } - \end{bconfig} + {Label Format} + Pool { + Name = File + Pool Type = Backup + Volume Use Duration = 23h + Label Format = "Vol" + } Bareos will create Volume names Vol0001, Vol0002, and so on when new Volumes are needed. Much more complex and elaborate labels can be created using variable expansion defined in the -:ref:`Variable Expansion VarsChapter` chapter of this +:raw-latex:`\ilink{Variable Expansion}{VarsChapter}` chapter of this manual. The second change that is necessary to make automatic labeling work is to give the Storage daemon permission to automatically label Volumes. Do so by adding -Label Media = yes to +:raw-latex:`\linkResourceDirective{Sd}{Device}{Label Media}` = yes to the :raw-latex:`\configresource{Device}` resource as follows: -.. raw:: latex +:: + + {Label Media = yes} + Device { + Name = File + Media Type = File + Archive Device = /var/lib/bareos/storage/ + Random Access = yes + Automatic Mount = yes + Removable Media = no + Always Open = no + Label Media = yes + } - \begin{bconfig}{Label Media = yes} - Device { - Name = File - Media Type = File - Archive Device = /var/lib/bareos/storage/ - Random Access = yes - Automatic Mount = yes - Removable Media = no - Always Open = no - Label Media = yes - } - \end{bconfig} - -See Label Format for +See :raw-latex:`\linkResourceDirective{Dir}{Pool}{Label Format}` for details about the labeling format. Restricting the Number of Volumes and Recycling ----------------------------------------------- - -.. index:: - triple: General; Recycling; Restricting the Number of Volumes and Recycling -.. index:: General; Restricting the Number of Volumes and Recycling +:raw-latex:`\index[general]{Recycling!Restricting the Number of Volumes and Recycling}` +:raw-latex:`\index[general]{Restricting the Number of Volumes and Recycling}` Automatic labeling discussed above brings up the problem of Volume management. With the above scheme, a new Volume will be created every @@ -238,80 +233,84 @@ and this procedure will create one new archive file (Volume) every day. The tools Bareos gives you to help automatically manage these problems are the following: -- File Retention: +- :raw-latex:`\linkResourceDirective{Dir}{Client}{File Retention}`: catalog file record retention period. -- Job Retention: +- :raw-latex:`\linkResourceDirective{Dir}{Client}{Job Retention}`: catalog job record retention period. -- Auto Prune = yes: +- :raw-latex:`\linkResourceDirective{Dir}{Client}{Auto Prune}` = yes: permit the application of the above two retention periods. -- Volume Retention +- + + .. raw:: latex -- Auto Prune = yes: + \linkResourceDirective{Dir}{Pool}{Volume Retention} + +- :raw-latex:`\linkResourceDirective{Dir}{Pool}{Auto Prune}` = yes: permit the application of the - Volume Retention + :raw-latex:`\linkResourceDirective{Dir}{Pool}{Volume Retention}` period. -- Recycle = yes: permit +- :raw-latex:`\linkResourceDirective{Dir}{Pool}{Recycle}` = yes: permit automatic recycling of Volumes whose Volume retention period has expired. -- Recycle Oldest Volume +- :raw-latex:`\linkResourceDirective{Dir}{Pool}{Recycle Oldest Volume}` = yes: prune the oldest volume in the Pool, and if all files were pruned, recycle this volume and use it. -- Recycle Current Volume +- :raw-latex:`\linkResourceDirective{Dir}{Pool}{Recycle Current Volume}` = yes: prune the currently mounted volume in the Pool, and if all files were pruned, recycle this volume and use it. -- | Purge Oldest Volume +- | :raw-latex:`\linkResourceDirective{Dir}{Pool}{Purge Oldest Volume}` = yes: permits a forced recycling of the oldest Volume when a new one is needed. | :raw-latex:`\warning{This record ignores retention periods! We highly recommend not to use this record, but instead use \linkResourceDirective{Dir}{Pool}{Recycle Oldest Volume}.}` -- Maximum Volumes: - limitthe number of Volumes that can be created. +- :raw-latex:`\linkResourceDirective{Dir}{Pool}{Maximum Volumes}`: + limit the number of Volumes that can be created. The first three records -(File Retention, -Job Retention and -Auto Prune) determine +(:raw-latex:`\linkResourceDirective{Dir}{Client}{File Retention}`, +:raw-latex:`\linkResourceDirective{Dir}{Client}{Job Retention}` and +:raw-latex:`\linkResourceDirective{Dir}{Client}{Auto Prune}`) determine the amount of time that Job and File records will remain in your Catalog and they are discussed in detail in the -:ref:`Automatic Volume Recycling RecyclingChapter` +:raw-latex:`\ilink{Automatic Volume Recycling}{RecyclingChapter}` chapter. -Volume Retention, -Auto Prune and -Recycle determine how +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Volume Retention}`, +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Auto Prune}` and +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Recycle}` determine how long Bareos will keep your Volumes before reusing them and they are also discussed in detail in the -:ref:`Automatic Volume Recycling RecyclingChapter` +:raw-latex:`\ilink{Automatic Volume Recycling}{RecyclingChapter}` chapter. -The Maximum Volumes +The :raw-latex:`\linkResourceDirective{Dir}{Pool}{Maximum Volumes}` record can also be used in conjunction with the -Volume Retention period +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Volume Retention}` period to limit the total number of archive Volumes that Bareos will create. By setting an appropriate -Volume Retention period, +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Volume Retention}` period, a Volume will be purged just before it is needed and thus Bareos can cycle through a fixed set of Volumes. Cycling through a fixed set of Volumes can also be done by setting -Purge Oldest Volume = +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Purge Oldest Volume}` = yes or -Recycle Current Volume = +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Recycle Current Volume}` = yes. In this case, when Bareos needs a new Volume, it will prune the specified volume. Concurrent Disk Jobs ==================== -.. index:: General; Concurrent Disk Jobs -.. _ConcurrentDiskJobs: Above, we discussed how you +:raw-latex:`\index[general]{Concurrent Disk Jobs}` +:raw-latex:`\label{ConcurrentDiskJobs}` Above, we discussed how you could have a single device named :raw-latex:`\resourcename{Sd}{Device}{FileBackup}` that writes to volumes in */var/lib/bareos/storage/*. You can, in fact, run multiple @@ -327,8 +326,8 @@ definition above, neither of these two is possible. Why? Because Bareos disk storage follows the same rules as tape devices. Only one Volume can be mounted on any Device at any time. If you want to simultaneously write multiple Volumes, you will need multiple Device resources in your - |bareosSd| configuration and thus multiple Storage resources -in your |bareosDir| configuration. +|bareosSd| configuration and thus multiple Storage resources +in your |bareosDir| configuration. Okay, so now you should understand that you need multiple Device definitions in the case of different directories or different Pools, but @@ -336,21 +335,21 @@ you also need to know that the catalog data that Bareos keeps contains only the Media Type and not the specific storage device. This permits a tape for example to be re-read on any compatible tape drive. The compatibility being determined by the Media Type -(Media Type and -Media Type). The same +(:raw-latex:`\linkResourceDirective{Dir}{Storage}{Media Type}` and +:raw-latex:`\linkResourceDirective{Sd}{Device}{Media Type}`). The same applies to disk storage. Since a volume that is written by a Device in -say directory */home/bareos/backups* +say directory :raw-latex:`\path`\|/home/bareos/backups\| cannot be read by a Device with an -Archive Device = -*/home/bareos/client1* +:raw-latex:`\linkResourceDirective{Sd}{Device}{Archive Device}` = +:raw-latex:`\path`\|/home/bareos/client1|, you will not be able to restore all your files if you give both those devices -Media Type = File. +:raw-latex:`\linkResourceDirective{Sd}{Device}{Media Type}` = File. During the restore, Bareos will simply choose the first available device, which may not be the correct one. If this is confusing, just remember that the Directory has only the Media Type and the Volume name. It does not know the -Archive Device (or the -full path) that is specified in the |bareosSd| . Thus you +:raw-latex:`\linkResourceDirective{Sd}{Device}{Archive Device}` (or the +full path) that is specified in the |bareosSd|. Thus you must explicitly tie your Volumes to the correct Device by using the Media Type. @@ -367,188 +366,186 @@ Full saves done every hour (so the whole thing cycles around after three hours). What is key here is that each physical device on the - |bareosSd| has a different Media Type. This allows the +|bareosSd| has a different Media Type. This allows the Director to choose the correct device for restores. -The |bareosDir| configuration is as follows: +The |bareosDir| configuration is as follows: -.. raw:: latex +:: - \begin{bconfig}{} - Director { - Name = bareos-dir - QueryFile = "/usr/lib/bareos/scripts/query.sql" - Password = "" - } - - Schedule { - Name = "FourPerHour" - Run = Level=Full hourly at 0:05 - Run = Level=Full hourly at 0:20 - Run = Level=Full hourly at 0:35 - Run = Level=Full hourly at 0:50 - } - - FileSet { - Name = "Example FileSet" - Include { - Options { - compression=GZIP - signature=SHA1 - } - File = /etc - } - } - - Job { - Name = "RecycleExample" - Type = Backup - Level = Full - Client = client1-fd - FileSet= "Example FileSet" - Messages = Standard - Storage = FileStorage - Pool = Recycle - Schedule = FourPerHour - } - - Job { - Name = "RecycleExample2" - Type = Backup - Level = Full - Client = client2-fd - FileSet= "Example FileSet" - Messages = Standard - Storage = FileStorage2 - Pool = Recycle2 - Schedule = FourPerHour - } - - Client { - Name = client1-fd - Address = client1.example.com - Password = client1_password - } - - Client { - Name = client2-fd - Address = client2.example.com - Password = client2_password - } - - Storage { - Name = FileStorage - Address = bareos-sd.example.com - Password = local_storage_password - Device = RecycleDir - Media Type = File - } - - Storage { - Name = FileStorage2 - Address = bareos-sd.example.com - Password = local_storage_password - Device = RecycleDir2 - Media Type = File1 - } - - Catalog { - Name = MyCatalog - ... - } - - Messages { - Name = Standard - ... - } - - Pool { - Name = Recycle - Pool Type = Backup - Label Format = "Recycle-" - Auto Prune = yes - Use Volume Once = yes - Volume Retention = 2h - Maximum Volumes = 12 - Recycle = yes - } - - Pool { - Name = Recycle2 - Pool Type = Backup - Label Format = "Recycle2-" - Auto Prune = yes - Use Volume Once = yes - Volume Retention = 2h - Maximum Volumes = 12 - Recycle = yes - } - \end{bconfig} - -and the |bareosSd| configuration is: + {} + Director { + Name = bareos-dir + QueryFile = "/usr/lib/bareos/scripts/query.sql" + Password = "" + } -.. raw:: latex + Schedule { + Name = "FourPerHour" + Run = Level=Full hourly at 0:05 + Run = Level=Full hourly at 0:20 + Run = Level=Full hourly at 0:35 + Run = Level=Full hourly at 0:50 + } + + FileSet { + Name = "Example FileSet" + Include { + Options { + compression=GZIP + signature=SHA1 + } + File = /etc + } + } + + Job { + Name = "RecycleExample" + Type = Backup + Level = Full + Client = client1-fd + FileSet= "Example FileSet" + Messages = Standard + Storage = FileStorage + Pool = Recycle + Schedule = FourPerHour + } + + Job { + Name = "RecycleExample2" + Type = Backup + Level = Full + Client = client2-fd + FileSet= "Example FileSet" + Messages = Standard + Storage = FileStorage2 + Pool = Recycle2 + Schedule = FourPerHour + } + + Client { + Name = client1-fd + Address = client1.example.com + Password = client1_password + } + + Client { + Name = client2-fd + Address = client2.example.com + Password = client2_password + } + + Storage { + Name = FileStorage + Address = bareos-sd.example.com + Password = local_storage_password + Device = RecycleDir + Media Type = File + } + + Storage { + Name = FileStorage2 + Address = bareos-sd.example.com + Password = local_storage_password + Device = RecycleDir2 + Media Type = File1 + } + + Catalog { + Name = MyCatalog + ... + } + + Messages { + Name = Standard + ... + } + + Pool { + Name = Recycle + Pool Type = Backup + Label Format = "Recycle-" + Auto Prune = yes + Use Volume Once = yes + Volume Retention = 2h + Maximum Volumes = 12 + Recycle = yes + } + + Pool { + Name = Recycle2 + Pool Type = Backup + Label Format = "Recycle2-" + Auto Prune = yes + Use Volume Once = yes + Volume Retention = 2h + Maximum Volumes = 12 + Recycle = yes + } + +and the |bareosSd| configuration is: + +:: + + {} + Storage { + Name = bareos-sd + Maximum Concurrent Jobs = 10 + } - \begin{bconfig}{} - Storage { - Name = bareos-sd - Maximum Concurrent Jobs = 10 - } - - Director { - Name = bareos-dir - Password = local_storage_password - } - - Device { - Name = RecycleDir - Media Type = File - Archive Device = /home/bareos/backups - LabelMedia = yes; - Random Access = Yes; - AutomaticMount = yes; - RemovableMedia = no; - AlwaysOpen = no; - } - - Device { - Name = RecycleDir2 - Media Type = File2 - Archive Device = /home/bareos/backups2 - LabelMedia = yes; - Random Access = Yes; - AutomaticMount = yes; - RemovableMedia = no; - AlwaysOpen = no; - } - - Messages { - Name = Standard - director = bareos-dir = all - } - \end{bconfig} + Director { + Name = bareos-dir + Password = local_storage_password + } + + Device { + Name = RecycleDir + Media Type = File + Archive Device = /home/bareos/backups + LabelMedia = yes; + Random Access = Yes; + AutomaticMount = yes; + RemovableMedia = no; + AlwaysOpen = no; + } + + Device { + Name = RecycleDir2 + Media Type = File2 + Archive Device = /home/bareos/backups2 + LabelMedia = yes; + Random Access = Yes; + AutomaticMount = yes; + RemovableMedia = no; + AlwaysOpen = no; + } + + Messages { + Name = Standard + director = bareos-dir = all + } With a little bit of work, you can change the above example into a weekly or monthly cycle (take care about the amount of archive disk space used). +.. _sec-MultipleStorageDevices: + Using Multiple Storage Devices ------------------------------ -.. index:: General; Multiple Storage Devices - -.. index:: - triple: General; Storage Device; Multiple +:raw-latex:`\index[general]{Multiple Storage Devices}` +:raw-latex:`\index[general]{Storage Device!Multiple}` Bareos treats disk volumes similar to tape volumes as much as it can. This means that you can only have a single Volume mounted at one time on a disk as defined in your :raw-latex:`\resourcetype{Sd}{Device}` resource. -If you use Bareos without :ref:`sec:DataSpooling`, +If you use Bareos without :raw-latex:`\nameref{sec-DataSpooling}`, multiple concurrent backup jobs can be written to a Volume using interleaving. However, interleaving has disadvantages, see -:ref:`sec:Interleaving`. +:raw-latex:`\nameref{sec-Interleaving}`. Also the :raw-latex:`\resourcetype{Sd}{Device}` will be in use. If there are other jobs, requesting other Volumes, these jobs have to wait. @@ -560,99 +557,97 @@ the software. To enable Bareos to run concurrent jobs (on disk storage), define as many :raw-latex:`\resourcetype{Sd}{Device}` as concurrent jobs should run. All these :raw-latex:`\resourcetype{Sd}{Device}`s can use the same -Archive Device +:raw-latex:`\linkResourceDirective{Sd}{Device}{Archive Device}` directory. Set -Maximum Concurrent Jobs +:raw-latex:`\linkResourceDirective{Sd}{Device}{Maximum Concurrent Jobs}` = 1 for all these devices. Example: use four storage devices pointing to the same directory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. raw:: latex +:: - \begin{bconfig}{\bareosDir configuration: using 4 storage devices} - Director { - Name = bareos-dir.example.com - QueryFile = "/usr/lib/bareos/scripts/query.sql" - Maximum Concurrent Jobs = 10 - Password = "" - } - - Storage { - Name = File - Address = bareos-sd.bareos.com - Password = "" - Device = FileStorage1 - Device = FileStorage2 - Device = FileStorage3 - Device = FileStorage4 - # number of devices = Maximum Concurrent Jobs - Maximum Concurrent Jobs = 4 - Media Type = File - } - - [...] - \end{bconfig} + {\bareosDir configuration: using 4 storage devices} + Director { + Name = bareos-dir.example.com + QueryFile = "/usr/lib/bareos/scripts/query.sql" + Maximum Concurrent Jobs = 10 + Password = "" + } -.. raw:: latex + Storage { + Name = File + Address = bareos-sd.bareos.com + Password = "" + Device = FileStorage1 + Device = FileStorage2 + Device = FileStorage3 + Device = FileStorage4 + # number of devices = Maximum Concurrent Jobs + Maximum Concurrent Jobs = 4 + Media Type = File + } + + [...] + +:: + + {\bareosSd configuraton: using 4 storage devices} + Storage { + Name = bareos-sd.example.com + # any number >= 4 + Maximum Concurrent Jobs = 20 + } + + Director { + Name = bareos-dir.example.com + Password = "" + } + + Device { + Name = FileStorage1 + Media Type = File + Archive Device = /var/lib/bareos/storage + LabelMedia = yes + Random Access = yes + AutomaticMount = yes + RemovableMedia = no + AlwaysOpen = no + Maximum Concurrent Jobs = 1 + } - \begin{bconfig}{\bareosSd configuraton: using 4 storage devices} - Storage { - Name = bareos-sd.example.com - # any number >= 4 - Maximum Concurrent Jobs = 20 - } - - Director { - Name = bareos-dir.example.com - Password = "" - } - - Device { - Name = FileStorage1 - Media Type = File - Archive Device = /var/lib/bareos/storage - LabelMedia = yes - Random Access = yes - AutomaticMount = yes - RemovableMedia = no - AlwaysOpen = no - Maximum Concurrent Jobs = 1 - } - - Device { - Name = FileStorage2 - Media Type = File - Archive Device = /var/lib/bareos/storage - LabelMedia = yes - Random Access = yes - AutomaticMount = yes - RemovableMedia = no - AlwaysOpen = no - Maximum Concurrent Jobs = 1 - } - - Device { - Name = FileStorage3 - Media Type = File - Archive Device = /var/lib/bareos/storage - LabelMedia = yes - Random Access = yes - AutomaticMount = yes - RemovableMedia = no - AlwaysOpen = no - Maximum Concurrent Jobs = 1 - } - - Device { - Name = FileStorage4 - Media Type = File - Archive Device = /var/lib/bareos/storage - LabelMedia = yes - Random Access = yes - AutomaticMount = yes - RemovableMedia = no - AlwaysOpen = no - Maximum Concurrent Jobs = 1 - } - \end{bconfig} + Device { + Name = FileStorage2 + Media Type = File + Archive Device = /var/lib/bareos/storage + LabelMedia = yes + Random Access = yes + AutomaticMount = yes + RemovableMedia = no + AlwaysOpen = no + Maximum Concurrent Jobs = 1 + } + + Device { + Name = FileStorage3 + Media Type = File + Archive Device = /var/lib/bareos/storage + LabelMedia = yes + Random Access = yes + AutomaticMount = yes + RemovableMedia = no + AlwaysOpen = no + Maximum Concurrent Jobs = 1 + } + + Device { + Name = FileStorage4 + Media Type = File + Archive Device = /var/lib/bareos/storage + LabelMedia = yes + Random Access = yes + AutomaticMount = yes + RemovableMedia = no + AlwaysOpen = no + Maximum Concurrent Jobs = 1 + } diff --git a/docs/manuals/en/new_main_reference/source/filedconf.rst b/docs/manuals/en/new_main_reference/source/filedconf.rst index 42ed64c621f..b9a1e9f08ca 100644 --- a/docs/manuals/en/new_main_reference/source/filedconf.rst +++ b/docs/manuals/en/new_main_reference/source/filedconf.rst @@ -3,13 +3,8 @@ Client/File Daemon Configuration ================================ -.. index:: - triple: General; Configuration; Client/File daemon -.. _`Configuration`: - -.. index:: General; Client/File daemon Configuration -.. _`Client/File daemon Configuration`: - +:raw-latex:`\index[general]{Configuration!Client/File daemon}` +:raw-latex:`\index[general]{Client/File daemon Configuration}` The Client (or File Daemon) Configuration is one of the simpler ones to specify. Generally, other than changing the Client name so that error @@ -18,16 +13,16 @@ Client configuration file. For a general discussion of configuration file and resources including the data types recognized by **Bareos**, please see the -:ref:`ConfigureChapter Configuration` chapter of this +:raw-latex:`\ilink{Configuration}{ConfigureChapter}` chapter of this manual. The following Client Resource definitions must be defined: -- :ref:`ClientResourceClient Client` – to define what +- :raw-latex:`\ilink{Client}{ClientResourceClient}` – to define what Clients are to be backed up. -- :ref:`ClientResourceDirector Director` – to define the +- :raw-latex:`\ilink{Director}{ClientResourceDirector}` – to define the Director’s name and its access password. -- :ref:`MessagesChapter Messages` – to define where +- :raw-latex:`\ilink{Messages}{MessagesChapter}` – to define where error and information messages are to be sent. .. _ClientResourceClient: @@ -35,13 +30,8 @@ manual. The following Client Resource definitions must be defined: Client Resource --------------- -.. index:: - triple: General; Resource; Client -.. _`Resource`: - -.. index:: General; Client Resource -.. _`Client Resource`: - +:raw-latex:`\index[general]{Resource!Client}` +:raw-latex:`\index[general]{Client Resource}` The Client Resource (or FileDaemon) resource defines the name of the Client (as used by the Director) as well as the port on which the Client @@ -72,13 +62,8 @@ The following is an example of a valid Client resource definition: Director Resource ----------------- -.. index:: General; Director Resource -.. _`Director Resource`: - -.. index:: - triple: General; Resource; Director -.. _`Resource`: - +:raw-latex:`\index[general]{Director Resource}` +:raw-latex:`\index[general]{Resource!Director}` The Director resource defines the name and password of the Directors that are permitted to contact this Client. @@ -117,15 +102,10 @@ The following is an example of a valid Director resource definition: Messages Resource ----------------- -.. index:: General; Messages Resource -.. _`Messages Resource`: - -.. index:: - triple: General; Resource; Messages -.. _`Resource`: - +:raw-latex:`\index[general]{Messages Resource}` +:raw-latex:`\index[general]{Resource!Messages}` -Please see the :ref:`MessagesChapter Messages Resource` +Please see the :raw-latex:`\ilink{Messages Resource}{MessagesChapter}` Chapter of this manual for the details of the Messages Resource. There must be at least one Message resource in the Client configuration diff --git a/docs/manuals/en/new_main_reference/source/general.rst b/docs/manuals/en/new_main_reference/source/general.rst index 91b7fc1920d..933b958bd60 100644 --- a/docs/manuals/en/new_main_reference/source/general.rst +++ b/docs/manuals/en/new_main_reference/source/general.rst @@ -22,16 +22,16 @@ History ------- Bareos is a -`fork `_ +:raw-latex:`\elink{fork}{http://www.bareos.org/en/faq/items/why_fork.html}` of the open source project -`Bacula `_ version 5.2. In 2010 +:raw-latex:`\elink{Bacula}{http://www.bacula.org}` version 5.2. In 2010 the Bacula community developer Marco van Wieringen started to collect rejected or neglected community contributions in his own branch. This branch was later on the base of Bareos and since then was enriched by a lot of new features. This documentation also bases on the -`original Bacula documentation `_, +:raw-latex:`\elink{original Bacula documentation}{http://www.bacula.org/5.2.x-manuals/en/main/main/}`, it is technically also a fork of the documenation created following the rules of the GNU Free Documentation License. @@ -39,7 +39,7 @@ Original author of Bacula and it’s documentation is Kern Sibbald. We thank Kern and all contributors to Bacula and it’s documentation. We maintain a list of contributors to Bacula (until the time we’ve started the fork) and Bareos in our -`AUTHORS `_ +:raw-latex:`\elink{AUTHORS}{https://github.com/bareos/bareos/blob/master/AUTHORS}` file. Who Needs Bareos? @@ -86,18 +86,16 @@ The Director is the central control program for all the other daemons. It schedules and supervises all the backup, restore, verify and archive operations. The system administrator uses the Bareos Director to schedule backups and to recover files. The Director runs as a daemon (or -service) in the background. - -.. _`UADef`: UADef +service) in the background. :raw-latex:`\label{UADef}` Bareos Console ~~~~~~~~~~~~~~ -The Bareos Console (:command:`bconsole`) is the program that +The Bareos Console (:raw-latex:`\command{verbatim}`) is the program that allows the administrator or user to communicate with the |bareosDir|. It runs in a shell window (i.e. TTY interface). Most system administrators will find this completely adequate. For more -details see the :ref:`sec:bconsole`. +details see the :raw-latex:`\nameref{sec-bconsole}`. .. _FDDef: @@ -164,12 +162,8 @@ Storage daemon, and the Catalog service (MySQL, PostgreSQL or SQLite). Bareos Version Numbers and Releases ----------------------------------- -.. index:: General; Version numbers -.. _`Version numbers`: - -.. index:: General; Releases -.. _`Releases`: - +:raw-latex:`\index[general]{Version numbers}` +:raw-latex:`\index[general]{Releases}` Bareos version numbers consists of three parts: YY.Q.C @@ -206,9 +200,9 @@ bareos-16.2.4: - 4: this is the first stable release of the bareos-16.2 branch For details about the different releases see -:ref:`releasenotes`. +:raw-latex:`\nameref{releasenotes}`. -.. _sec:BareosPackages: +.. _sec-BareosPackages: Bareos Packages --------------- @@ -314,36 +308,36 @@ Following Bareos Linux packages are available (release 17.2.4): Not all packages (especially optional backends and plugins) are available on all platforms. For details, see -:ref:`sec:packages`. +:raw-latex:`\nameref{sec-packages}`. Additionally, packages containing debug information are available. These are named differently depending on the distribution -(**bareos-debuginfo** or -**bareos-dbg** or :math:`\ldots`). +(:raw-latex:`\package{bareos-debuginfo}` or +:raw-latex:`\package{bareos-dbg}` or :math:`\ldots`). Not all packages are required to run Bareos. - For the Bareos Director, the package - **bareos-director** and one of - **bareos-database-postgresql**, - **bareos-database-mysql** or - **bareos-database-sqlite3** are required. It is - recommended to use **bareos-database-postgresql**. + :raw-latex:`\package{bareos-director}` and one of + :raw-latex:`\package{bareos-database-postgresql}`, + :raw-latex:`\package{bareos-database-mysql}` or + :raw-latex:`\package{bareos-database-sqlite3}` are required. It is + recommended to use :raw-latex:`\package{bareos-database-postgresql}`. - For the |bareosSd|, the package - **bareos-storage** is required. If you plan to + :raw-latex:`\package{bareos-storage}` is required. If you plan to connect tape drives to the storage director, also install the package - **bareos-storage-tape**. This is kept separately, + :raw-latex:`\package{bareos-storage-tape}`. This is kept separately, because it has additional dependencies for tape tools. - On a client, only the package - **bareos-filedaemon** is required. If you run it + :raw-latex:`\package{bareos-filedaemon}` is required. If you run it on a workstation, the packages - **bareos-traymonitor** gives the user information + :raw-latex:`\package{bareos-traymonitor}` gives the user information about running backups. - On a Backup Administration system you need to install at least - **bareos-bconsole** to have an interactive console + :raw-latex:`\package{bareos-bconsole}` to have an interactive console to the |bareosDir|. Quick Start @@ -352,38 +346,30 @@ Quick Start To get Bareos up and running quickly, the author recommends that you first scan the Terminology section below, then quickly review the next chapter entitled -:ref:`StateChapter The Current State of Bareos`, then the -:ref:`InstallChapter Installing Bareos`, the -:ref:`QuickStartChapter Getting Started with Bareos`, +:raw-latex:`\ilink{The Current State of Bareos}{StateChapter}`, then the +:raw-latex:`\ilink{Installing Bareos}{InstallChapter}`, the +:raw-latex:`\ilink{Getting Started with Bareos}{QuickStartChapter}`, which will give you a quick overview of getting Bareos running. After which, you should proceed to the chapter -:ref:`ConfigureChapter How to Configure Bareos`, and +:raw-latex:`\ilink{How to Configure Bareos}{ConfigureChapter}`, and finally the chapter on -:ref:`TutorialChapter Running Bareos`. +:raw-latex:`\ilink{Running Bareos}{TutorialChapter}`. Terminology ----------- -.. index:: General; Terminology -.. _`Terminology`: - +:raw-latex:`\index[general]{Terminology}` Administrator - .. index:: General; Administrator - .. _`Administrator`: - The person or persons + :raw-latex:`\index[general]{Administrator}` The person or persons responsible for administrating the Bareos system. Backup - .. index:: General; Backup - .. _`Backup`: - The term Backup refers to a + :raw-latex:`\index[general]{Backup}` The term Backup refers to a Bareos Job that saves files. Bootstrap File - .. index:: General; Bootstrap File - .. _`Bootstrap File`: - The bootstrap file is + :raw-latex:`\index[general]{Bootstrap File}` The bootstrap file is an ASCII file containing a compact form of commands that allow Bareos or the stand-alone file extraction utility (bextract) to restore the contents of one or more Volumes, for example, the @@ -392,9 +378,7 @@ Bootstrap File bootstrap file from a Catalog to extract any file or files you wish. Catalog - .. index:: General; Catalog - .. _`Catalog`: - The Catalog is used to store + :raw-latex:`\index[general]{Catalog}` The Catalog is used to store summary information about the Jobs, Clients, and Files that were backed up and on what Volume or Volumes. The information saved in the Catalog permits the administrator or user to determine what jobs @@ -410,58 +394,42 @@ Catalog simple backup and archive programs such as dump and tar. Client - .. index:: General; Client - .. _`Client`: - - .. index:: General; File Daemon|see{Client} - .. _`File Daemon|see{Client}`: - In Bareos’s + :raw-latex:`\index[general]{Client}` + :raw-latex:`\index[general]{File Daemon|see{Client}}` In Bareos’s terminology, the word Client refers to the machine being backed up, and it is synonymous with the File services or File daemon, and quite often, it is referred to it as the FD. A Client is defined in a configuration file resource. Console - .. index:: General; Console - .. _`Console`: - The program that interfaces to + :raw-latex:`\index[general]{Console}` The program that interfaces to the Director allowing the user or system administrator to control Bareos. Daemon - .. index:: General; Daemon - .. _`Daemon`: - Unix terminology for a program + :raw-latex:`\index[general]{Daemon}` Unix terminology for a program that is always present in the background to carry out a designated task. On Windows systems, as well as some Unix systems, daemons are called Services. Directive - .. index:: General; Directive - .. _`Directive`: - The term directive is used + :raw-latex:`\index[general]{Directive}` The term directive is used to refer to a statement or a record within a Resource in a configuration file that defines one specific setting. For example, the **Name** directive defines the name of the Resource. Director - .. index:: General; Director - .. _`Director`: - The main Bareos server daemon + :raw-latex:`\index[general]{Director}` The main Bareos server daemon that schedules and directs all Bareos operations. Occasionally, the project refers to the Director as DIR. Differential - .. index:: General; Differential - .. _`Differential`: - A backup that includes + :raw-latex:`\index[general]{Differential}` A backup that includes all files changed since the last Full save started. Note, other backup programs may define this differently. File Attributes - .. index:: General; File Attributes - .. _`File Attributes`: - The File Attributes + :raw-latex:`\index[general]{File Attributes}` The File Attributes are all the information necessary about a file to identify it and all its properties such as size, creation date, modification date, permissions, etc. Normally, the attributes are handled entirely by @@ -469,59 +437,45 @@ File Attributes attributes do not include the file’s data. File daemon - .. index:: General; File Daemon - .. _`File Daemon`: - The daemon running on the + :raw-latex:`\index[general]{File Daemon}` The daemon running on the client computer to be backed up. This is also referred to as the File services, and sometimes as the Client services or the FD. - - -.. _`FileSetDef`: FileSetDef + :raw-latex:`\label{FileSetDef}` FileSet A FileSet is a Resource contained in a configuration file that defines the files to be backed up. It consists of a list of included files or directories, a list of excluded files, and how the file is to be stored (compression, encryption, signatures). For more - details, see the :ref:`DirectorResourceFileSet` in + details, see the :raw-latex:`\nameref{DirectorResourceFileSet}` in the Director chapter of this document. Incremental - .. index:: General; Incremental - .. _`Incremental`: - A backup that includes all + :raw-latex:`\index[general]{Incremental}` A backup that includes all files changed since the last Full, Differential, or Incremental backup started. It is normally specified on the **Level** directive within the Job resource definition, or in a Schedule resource. - - -.. _`JobDef`: JobDef + :raw-latex:`\label{JobDef}` Job - .. index:: General; Job - .. _`Job`: - A Bareos Job is a configuration + :raw-latex:`\index[general]{Job}` A Bareos Job is a configuration resource that defines the work that Bareos must perform to backup or restore a particular Client. It consists of the **Type** (backup, restore, verify, etc), the **Level** (full, differential, incremental, etc.), the **FileSet**, and **Storage** the files are to be backed up (Storage device, Media Pool). For more details, see - the :ref:`DirectorResourceJob` in the Director + the :raw-latex:`\nameref{DirectorResourceJob}` in the Director chapter of this document. Monitor - .. index:: General; Monitor - .. _`Monitor`: - The program that interfaces to + :raw-latex:`\index[general]{Monitor}` The program that interfaces to all the daemons allowing the user or system administrator to monitor Bareos status. Resource - .. index:: General; Resource - .. _`Resource`: - A resource is a part of a + :raw-latex:`\index[general]{Resource}` A resource is a part of a configuration file that defines a specific unit of information that is available to Bareos. It consists of several directives (individual configuration statements). For example, the **Job** @@ -529,9 +483,7 @@ Resource schedule, Volume pool, backup type, backup level, ... Restore - .. index:: General; Restore - .. _`Restore`: - A restore is a configuration + :raw-latex:`\index[general]{Restore}` A restore is a configuration resource that describes the operation of recovering a file from backup media. It is the inverse of a save, except that in most cases, a restore will normally have a small set of files to restore, @@ -540,26 +492,20 @@ Restore Restore of all files that were on the system. Schedule - .. index:: General; Schedule - .. _`Schedule`: - A Schedule is a configuration + :raw-latex:`\index[general]{Schedule}` A Schedule is a configuration resource that defines when the Bareos Job will be scheduled for execution. To use the Schedule, the Job resource will refer to the name of the Schedule. For more details, see the - :ref:`DirectorResourceSchedule` in the Director + :raw-latex:`\nameref{DirectorResourceSchedule}` in the Director chapter of this document. Service - .. index:: General; Service - .. _`Service`: - This is a program that remains + :raw-latex:`\index[general]{Service}` This is a program that remains permanently in memory awaiting instructions. In Unix environments, services are also known as **daemons**. Storage Coordinates - .. index:: General; Storage Coordinates - .. _`Storage Coordinates`: - The information + :raw-latex:`\index[general]{Storage Coordinates}` The information returned from the Storage Services that uniquely locates a file on a backup medium. It consists of two parts: one part pertains to each file saved, and the other part pertains to the whole Job. Normally, @@ -569,25 +515,19 @@ Storage Coordinates location of the information on the backup Volume. Storage Daemon - .. index:: General; Storage Daemon - .. _`Storage Daemon`: - The Storage daemon, + :raw-latex:`\index[general]{Storage Daemon}` The Storage daemon, sometimes referred to as the SD, is the code that writes the attributes and data to a storage Volume (usually a tape or disk). Session - .. index:: General; Session - .. _`Session`: - Normally refers to the + :raw-latex:`\index[general]{Session}` Normally refers to the internal conversation between the File daemon and the Storage daemon. The File daemon opens a **session** with the Storage daemon to save a FileSet or to restore it. A session has a one-to-one correspondence to a Bareos Job (see above). Verify - .. index:: General; Verify - .. _`Verify`: - A verify is a job that compares + :raw-latex:`\index[general]{Verify}` A verify is a job that compares the current file attributes to the attributes that have previously been stored in the Bareos Catalog. This feature can be used for detecting changes to critical system files similar to what a file @@ -604,9 +544,7 @@ Verify contents against the original files on disk. Retention Period - .. index:: General; Retention Period - .. _`Retention Period`: - There are various + :raw-latex:`\index[general]{Retention Period}` There are various kinds of retention periods that Bareos recognizes. The most important are the **File** Retention Period, **Job** Retention Period, and the **Volume** Retention Period. Each of these retention @@ -651,9 +589,7 @@ Retention Period the retention periods defined. Scan - .. index:: General; Scan - .. _`Scan`: - A Scan operation causes the + :raw-latex:`\index[general]{Scan}` A Scan operation causes the contents of a Volume or a series of Volumes to be scanned. These Volumes with the information on which files they contain are restored to the Bareos Catalog. Once the information is restored to @@ -662,13 +598,11 @@ Scan Jobs have exceeded their retention period and have been pruned or purged from the Catalog. Scanning data from Volumes into the Catalog is done by using the **bscan** program. See the - :ref:`bscan bscan section` of the Bareos Utilities + :raw-latex:`\ilink{bscan section}{bscan}` of the Bareos Utilities chapter of this manual for more details. Volume - .. index:: General; Volume - .. _`Volume`: - A Volume is an archive unit, + :raw-latex:`\index[general]{Volume}` A Volume is an archive unit, normally a tape or a named disk file where Bareos stores the data from one or more backup jobs. All Bareos Volumes have a software label written to the Volume by Bareos so that it identifies what @@ -681,7 +615,7 @@ What Bareos is Not Bareos is a backup, restore and verification program and is not a complete disaster recovery system in itself, but it can be a key part of one if you plan carefully and follow the instructions included in the -:ref:`RescueChapter Disaster Recovery` chapter of this +:raw-latex:`\ilink{Disaster Recovery}{RescueChapter}` chapter of this manual. Interactions Between the Bareos Services diff --git a/docs/manuals/en/new_main_reference/source/howto.rst b/docs/manuals/en/new_main_reference/source/howto.rst index 39859ac88d2..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/howto.rst +++ b/docs/manuals/en/new_main_reference/source/howto.rst @@ -1,41 +1 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/manuals/en/new_main_reference/source/images/bareos-full-logo.png b/docs/manuals/en/new_main_reference/source/images/bareos-full-logo.png deleted file mode 100644 index 96d3b6883a8..00000000000 Binary files a/docs/manuals/en/new_main_reference/source/images/bareos-full-logo.png and /dev/null differ diff --git a/docs/manuals/en/new_main_reference/source/index.rst b/docs/manuals/en/new_main_reference/source/index.rst index db529166ea3..3378b5c6aa4 100644 --- a/docs/manuals/en/new_main_reference/source/index.rst +++ b/docs/manuals/en/new_main_reference/source/index.rst @@ -8,9 +8,9 @@ Bareos Main Reference and Documentation :numbered: index-part-1 - index-part-2 - index-part-3 - index-part-4 +# index-part-2 +# index-part-3 +# index-part-4 Indicies and tables =================== diff --git a/docs/manuals/en/new_main_reference/source/install.rst b/docs/manuals/en/new_main_reference/source/install.rst index 131585f5efc..a21b71c8659 100644 --- a/docs/manuals/en/new_main_reference/source/install.rst +++ b/docs/manuals/en/new_main_reference/source/install.rst @@ -7,23 +7,41 @@ Bareos comes prepackaged for a number of Linux distributions. So the easiest way to get to a running Bareos installation, is to use a platform where prepacked Bareos packages are available. Additional information can be found in the chapter -:ref:`Operating Systems SupportedOSes`. +:raw-latex:`\ilink{Operating Systems}{SupportedOSes}`. If Bareos is available as a package, only 4 steps are required to get to a running Bareos system: -#. :ref:`sec:AddSoftwareRepository` +#. -#. :ref:`sec:InstallBareosPackages` + .. raw:: latex -#. :ref:`sec:CreateDatabase` + \nameref{sec-AddSoftwareRepository} -#. :ref:`sec:StartDaemons` +#. + + .. raw:: latex + + \nameref{sec-InstallBareosPackages} + +#. + + .. raw:: latex + + \nameref{sec-CreateDatabase} + +#. + + .. raw:: latex + + \nameref{sec-StartDaemons} This will start a very basic Bareos installation which will regularly backup a directory to disk. In order to fit it to your needs, you’ll have to adapt the configuration and might want to backup other clients. +.. _sec-AddSoftwareRepository: + Decide about the Bareos release to use ====================================== @@ -34,28 +52,28 @@ http://download.bareos.org/. The latest stable released version is available at http://download.bareos.org/bareos/release/latest/. The public key to verify the repository is also in repository directory -(*Release.key* for Debian based distributions, -*repodata/repomd.xml.key* for RPM based +(:raw-latex:`\file{Release.key}` for Debian based distributions, +:raw-latex:`\file{repodata/repomd.xml.key}` for RPM based distributions). -Section :ref:`sec:InstallBareosPackages` describes how +Section :raw-latex:`\nameref{sec-InstallBareosPackages}` describes how to add the software repository to your system. +.. _sec-ChooseDatabaseBackend: + Decide about the Database Backend ================================= Bareos offers the following database backends: - PostgreSQL by package - **bareos-database-postgresql**. This is the + :raw-latex:`\package{bareos-database-postgresql}`. This is the recommended backend. -- MariaDB/MySQL by package **bareos-database-mysql** +- MariaDB/MySQL by package :raw-latex:`\package{bareos-database-mysql}` -- | Sqlite by package **bareos-database-sqlite3** - | -.. warning:: - The Sqlite backend is only intended for testing, not for productive use. +- | Sqlite by package :raw-latex:`\package{bareos-database-sqlite3}` + | :raw-latex:`\warning{The Sqlite backend is only intended for testing, not for productive use.}` PostgreSQL ^^^^^^^^^^ @@ -81,16 +99,18 @@ system installer will choose one for you. The default should be PostgreSQL, but depending on your operating system and the already installed packages, this may differ. +.. _sec-InstallBareosPackages: + Install the Bareos Software Packages ==================================== -The package **bareos** is only a meta package, that +The package :raw-latex:`\package{bareos}` is only a meta package, that contains dependencies to the main components of Bareos, see -:ref:`sec:BareosPackages`. If you want to setup a +:raw-latex:`\nameref{sec-BareosPackages}`. If you want to setup a distributed environment (like one Director, separate database server, multiple Storage daemons) you have to choose the corresponding Bareos packages to install on each hosts instead of just installing the -**bareos** package. +:raw-latex:`\package{bareos}` package. Install on RedHat based Linux Distributions ------------------------------------------- @@ -98,152 +118,150 @@ Install on RedHat based Linux Distributions RHEL\ :math:`\ge`\ 7, CentOS\ :math:`\ge`\ 7, Fedora ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:raw-latex:`\index[general]{Platform!RHEL}` +:raw-latex:`\index[general]{Platform!CentOS}` +:raw-latex:`\index[general]{Platform!Fedora}` -.. index:: - triple: General; Platform; RHEL - -.. index:: - triple: General; Platform; CentOS - -.. index:: - triple: General; Platform; Fedora - -Bareos 15.2.0 -requires the :ref:`Jansson library jansson` package. On +Bareos :raw-latex:`\sinceVersion{dir}{requires!jansson}{15.2.0}` +requires the :raw-latex:`\ilink{Jansson library}{jansson}` package. On RHEL 7 it is available through the RHEL Server Optional channel. On CentOS 7 and Fedora is it included on the main repository. -.. raw:: latex +:: - \begin{commands}{Bareos installation on RHEL $\ge$ 7 / CentOS $\ge$ 7 / Fedora} - # - # define parameter - # + {Bareos installation on RHEL $\ge$ 7 / CentOS $\ge$ 7 / Fedora} + # + # define parameter + # - DIST=RHEL_7 - # or - # DIST=CentOS_7 - # DIST=Fedora_26 - # DIST=Fedora_25 + DIST=RHEL\_7 + # or + # DIST=CentOS\_7 + # DIST=Fedora\_26 + # DIST=Fedora\_25 - RELEASE=release/17.2/ - # or - # RELEASE=release/latest/ - # RELEASE=experimental/nightly/ + RELEASE=release/17.2/ + # or + # RELEASE=release/latest/ + # RELEASE=experimental/nightly/ - # add the Bareos repository - URL=http://download.bareos.org/bareos/$RELEASE/$DIST - wget -O /etc/yum.repos.d/bareos.repo $URL/bareos.repo + # add the Bareos repository + URL=http://download.bareos.org/bareos/$RELEASE/$DIST + wget -O /etc/yum.repos.d/bareos.repo $URL/bareos.repo - # install Bareos packages - yum install bareos bareos-database-postgresql - \end{commands} - \hide{$} + # install Bareos packages + yum install bareos bareos-database-postgresql - \subsubsection{RHEL 6, CentOS 6} - \index[general]{Platform!RHEL!6} - \index[general]{Platform!CentOS!6} +RHEL 6, CentOS 6 +~~~~~~~~~~~~~~~~ - Bareos \sinceVersion{dir}{requires!jansson}{15.2.0} requires the \ilink{Jansson library}{jansson} package. - This package is available on \elink{EPEL}{https://fedoraproject.org/wiki/EPEL} 6. Make sure, it is available on your system. +:raw-latex:`\index[general]{Platform!RHEL!6}` +:raw-latex:`\index[general]{Platform!CentOS!6}` - \begin{commands}{Bareos installation on RHEL $\ge$ 6 / CentOS $\ge$ 6} - # - # add EPEL repository, if not already present. - # Required for the jansson package. - # - rpm -Uhv https://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm +Bareos :raw-latex:`\sinceVersion{dir}{requires!jansson}{15.2.0}` +requires the :raw-latex:`\ilink{Jansson library}{jansson}` package. This +package is available on +:raw-latex:`\elink{EPEL}{https://fedoraproject.org/wiki/EPEL}` 6. Make +sure, it is available on your system. - # - # define parameter - # +:: - DIST=RHEL_6 - # DIST=CentOS_6 + {Bareos installation on RHEL $\ge$ 6 / CentOS $\ge$ 6} + # + # add EPEL repository, if not already present. + # Required for the jansson package. + # + rpm -Uhv https://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm - RELEASE=release/17.2/ - # or - # RELEASE=release/latest/ - # RELEASE=experimental/nightly/ + # + # define parameter + # - # add the Bareos repository - URL=http://download.bareos.org/bareos/$RELEASE/$DIST - wget -O /etc/yum.repos.d/bareos.repo $URL/bareos.repo + DIST=RHEL\_6 + # DIST=CentOS\_6 - # install Bareos packages - yum install bareos bareos-database-postgresql - \end{commands} + RELEASE=release/17.2/ + # or + # RELEASE=release/latest/ + # RELEASE=experimental/nightly/ + # add the Bareos repository + URL=http://download.bareos.org/bareos/$RELEASE/$DIST + wget -O /etc/yum.repos.d/bareos.repo $URL/bareos.repo + # install Bareos packages + yum install bareos bareos-database-postgresql RHEL 5 ~~~~~~ +:raw-latex:`\index[general]{Platform!RHEL!5}` -.. index:: - triple: General; Platform!RHEL; 5 yum in RHEL 5/CentOS 5 has -slightly different behaviour as far as dependency resolving is -concerned: it sometimes install a dependent package after the one that -has the dependency defined. To make sure that it works, install the -desired Bareos database backend package first in a separate step: +yum in RHEL 5/CentOS 5 has slightly different behaviour as far as +dependency resolving is concerned: it sometimes install a dependent +package after the one that has the dependency defined. To make sure that +it works, install the desired Bareos database backend package first in a +separate step: -.. raw:: latex +:: - \begin{commands}{Bareos installation on RHEL 5 / CentOS 5} - # - # define parameter - # + {Bareos installation on RHEL 5 / CentOS 5} + # + # define parameter + # - DIST=RHEL_5 + DIST=RHEL\_5 - RELEASE=release/17.2/ - # or - # RELEASE=release/latest/ - # RELEASE=experimental/nightly/ + RELEASE=release/17.2/ + # or + # RELEASE=release/latest/ + # RELEASE=experimental/nightly/ - # add the Bareos repository - URL=http://download.bareos.org/bareos/$RELEASE/$DIST - wget -O /etc/yum.repos.d/bareos.repo $URL/bareos.repo + # add the Bareos repository + URL=http://download.bareos.org/bareos/$RELEASE/$DIST + wget -O /etc/yum.repos.d/bareos.repo $URL/bareos.repo - # install Bareos packages - yum install bareos-database-postgresql - yum install bareos - \end{commands} - \hide{$} + # install Bareos packages + yum install bareos-database-postgresql + yum install bareos - \subsection{Install on SUSE based Linux Distributions} +Install on SUSE based Linux Distributions +----------------------------------------- - \subsubsection{SUSE Linux Enterprise Server (SLES), openSUSE} - \index[general]{Platform!SLES} - \index[general]{Platform!openSUSE} +SUSE Linux Enterprise Server (SLES), openSUSE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - \begin{commands}{Bareos installation on SLES / openSUSE} - # - # define parameter - # +:raw-latex:`\index[general]{Platform!SLES}` +:raw-latex:`\index[general]{Platform!openSUSE}` - DIST=SLE_12_SP3 - # or - # DIST=SLE_12_SP2 - # DIST=SLE_12_SP1 - # DIST=SLE_11_SP4 - # DIST=openSUSE_Leap_42.3 - # DIST=openSUSE_Leap_42.2 +:: - RELEASE=release/17.2/ - # or - # RELEASE=release/latest/ - # RELEASE=experimental/nightly/ + {Bareos installation on SLES / openSUSE} + # + # define parameter + # - # add the Bareos repository - URL=http://download.bareos.org/bareos/$RELEASE/$DIST - zypper addrepo --refresh $URL/bareos.repo + DIST=SLE\_12_SP3 + # or + # DIST=SLE\_12_SP2 + # DIST=SLE\_12_SP1 + # DIST=SLE\_11_SP4 + # DIST=openSUSE\_Leap_42.3 + # DIST=openSUSE\_Leap_42.2 - # install Bareos packages - zypper install bareos bareos-database-postgresql - \end{commands} + RELEASE=release/17.2/ + # or + # RELEASE=release/latest/ + # RELEASE=experimental/nightly/ + # add the Bareos repository + URL=http://download.bareos.org/bareos/$RELEASE/$DIST + zypper addrepo --refresh $URL/bareos.repo + # install Bareos packages + zypper install bareos bareos-database-postgresql + +.. _sec-InstallBareosPackagesDebian: Install on Debian based Linux Distributions ------------------------------------------- @@ -251,69 +269,66 @@ Install on Debian based Linux Distributions Debian / Ubuntu ~~~~~~~~~~~~~~~ +:raw-latex:`\index[general]{Platform!Debian}` +:raw-latex:`\index[general]{Platform!Ubuntu}` -.. index:: - triple: General; Platform; Debian - -.. index:: - triple: General; Platform; Ubuntu - -Bareos 15.2.0 -requires the :ref:`Jansson library jansson` package. On +Bareos :raw-latex:`\sinceVersion{dir}{requires!jansson}{15.2.0}` +requires the :raw-latex:`\ilink{Jansson library}{jansson}` package. On Ubuntu is it available in Ubuntu Universe. In Debian, is it included in the main repository. -.. raw:: latex +:: - \begin{commands}{Bareos installation on Debian / Ubuntu} - # - # define parameter - # + {Bareos installation on Debian / Ubuntu} + # + # define parameter + # - DIST=Debian_9.0 - # or - # DIST=Debian_8.0 - # DIST=xUbuntu_16.04 - # DIST=xUbuntu_14.04 - # DIST=xUbuntu_12.04 + DIST=Debian\_9.0 + # or + # DIST=Debian\_8.0 + # DIST=xUbuntu\_16.04 + # DIST=xUbuntu\_14.04 + # DIST=xUbuntu\_12.04 - RELEASE=release/17.2/ - # or - # RELEASE=release/latest/ - # RELEASE=experimental/nightly/ + RELEASE=release/17.2/ + # or + # RELEASE=release/latest/ + # RELEASE=experimental/nightly/ - URL=http://download.bareos.org/bareos/$RELEASE/$DIST + URL=http://download.bareos.org/bareos/$RELEASE/$DIST - # add the Bareos repository - printf "deb $URL /\n" > /etc/apt/sources.list.d/bareos.list + # add the Bareos repository + printf "deb $URL /\n" > /etc/apt/sources.list.d/bareos.list - # add package key - wget -q $URL/Release.key -O- | apt-key add - + # add package key + wget -q $URL/Release.key -O- | apt-key add - - # install Bareos packages - apt-get update - apt-get install bareos bareos-database-postgresql - \end{commands} + # install Bareos packages + apt-get update + apt-get install bareos bareos-database-postgresql If you prefer using the versions of Bareos directly integrated into the distributions, please note that there are some differences, see -:ref:`sec:DebianOrgLimitations`. +:raw-latex:`\nameref{sec-DebianOrgLimitations}`. Install on Univention Corporate Server -------------------------------------- +.. raw:: latex -.. index:: - triple: General; Platform; Univention Corporate Server + \os{Univention}{} Bareos offers additional functionality and integration into an Univention Corporate Server environment. Please follow the intructions -in :ref:`sec:UniventionCorporateServer`. +in :raw-latex:`\nameref{sec-UniventionCorporateServer}`. If you are not interested in this additional functionality, the commands -described in :ref:`sec:InstallBareosPackagesDebian` will +described in :raw-latex:`\nameref{sec-InstallBareosPackagesDebian}` will also work for Univention Corporate Servers. +.. _sec-CreateDatabase: + Prepare Bareos database ======================= @@ -322,18 +337,18 @@ running. Using the PostgreSQL database backend is recommended. The easiest way to set up a database is using an system account that have passwordless local access to the database. Often this is the user -**root** for MySQL and the user -**postgres** for PostgreSQL. +:raw-latex:`\user{root}` for MySQL and the user +:raw-latex:`\user{postgres}` for PostgreSQL. -For details, see chapter :ref:`CatMaintenanceChapter`. +For details, see chapter :raw-latex:`\nameref{CatMaintenanceChapter}`. Debian based Linux Distributions -------------------------------- Since Bareos -14.2.0 the +:raw-latex:`\sinceVersion{dir}{dbconfig-common (Debian)}{14.2.0}` the Debian (and Ubuntu) based packages support the -**dbconfig-common** mechanism to create and update +:raw-latex:`\package{dbconfig-common}` mechanism to create and update the Bareos database. Follow the instructions during install to configure it according to your @@ -341,41 +356,44 @@ needs. |image| |image| -If you decide not to use **dbconfig-common** -(selecting **** on the initial dialog), follow +If you decide not to use :raw-latex:`\package{dbconfig-common}` +(selecting :raw-latex:`\parameter{}` on the initial dialog), follow the instructions for -:ref:`sec:CreateDatabaseOtherDistributions`. +:raw-latex:`\nameref{sec-CreateDatabaseOtherDistributions}`. The selectable database backends depend on the -**bareos-database-*** packages installed. +:raw-latex:`\package{bareos-database-*}` packages installed. + +For details see :raw-latex:`\nameref{sec-dbconfig}`. -For details see :ref:`sec:dbconfig`. +.. _sec-CreateDatabaseOtherDistributions: Other Platforms --------------- +.. _postgresql-1: + PostgreSQL ~~~~~~~~~~ If your are using PostgreSQL and your PostgreSQL administration user is -**postgres** (default), use following commands: +:raw-latex:`\user{postgres}` (default), use following commands: -.. raw:: latex +:: - \begin{commands}{Setup Bareos catalog with PostgreSQL} - su postgres -c /usr/lib/bareos/scripts/create_bareos_database - su postgres -c /usr/lib/bareos/scripts/make_bareos_tables - su postgres -c /usr/lib/bareos/scripts/grant_bareos_privileges - \end{commands} + {Setup Bareos catalog with PostgreSQL} + su postgres -c /usr/lib/bareos/scripts/create_bareos_database + su postgres -c /usr/lib/bareos/scripts/make_bareos_tables + su postgres -c /usr/lib/bareos/scripts/grant_bareos_privileges MySQL/MariaDB ~~~~~~~~~~~~~ -Make sure, that **root** has direct access to the local -MySQL server. Check if the command :command:`mysql` connects +Make sure, that :raw-latex:`\user{root}` has direct access to the local +MySQL server. Check if the command :raw-latex:`\command{mysql}` connects to the database without defining the password. This is the default on RedHat and SUSE distributions. On other systems (Debian, Ubuntu), create -the file *~/.my.cnf* with your authentication +the file :raw-latex:`\file{~/.my.cnf}` with your authentication informations: .. raw:: latex @@ -389,33 +407,33 @@ informations: It is recommended, to secure the Bareos database connection with a password. See -:ref:`Catalog Maintenance -- MySQL catalog-maintenance-mysql` +:raw-latex:`\ilink{Catalog Maintenance -- MySQL}{catalog-maintenance-mysql}` about how to archieve this. For testing, using a password-less MySQL connection is probable okay. Setup the Bareos database tables by following commands: -.. raw:: latex +:: - \begin{commands}{Setup Bareos catalog with MySQL} - /usr/lib/bareos/scripts/create_bareos_database - /usr/lib/bareos/scripts/make_bareos_tables - /usr/lib/bareos/scripts/grant_bareos_privileges - \end{commands} + {Setup Bareos catalog with MySQL} + /usr/lib/bareos/scripts/create_bareos_database + /usr/lib/bareos/scripts/make_bareos_tables + /usr/lib/bareos/scripts/grant_bareos_privileges As some Bareos updates require a database schema update, therefore the -file */root/.my.cnf* might also be useful in the +file :raw-latex:`\file{/root/.my.cnf}` might also be useful in the future. +.. _sec-StartDaemons: + Start the daemons ================= -.. raw:: latex +:: - \begin{commands}{Start the Bareos Daemons} - service bareos-dir start - service bareos-sd start - service bareos-fd start - \end{commands} + {Start the Bareos Daemons} + service bareos-dir start + service bareos-sd start + service bareos-fd start You will eventually have to allow access to the ports 9101-9103, used by Bareos. @@ -423,7 +441,7 @@ Bareos. Now you should be able to access the director using the bconsole. When you want to use the bareos-webui, please refer to the chapter -:ref:`sec:install-webui`. +:raw-latex:`\nameref{sec-install-webui}`. .. |image| image:: \idir dbconfig-1-enable :width: 45.0% diff --git a/docs/manuals/en/new_main_reference/source/lanaddress.rst b/docs/manuals/en/new_main_reference/source/lanaddress.rst index 22684812301..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/lanaddress.rst +++ b/docs/manuals/en/new_main_reference/source/lanaddress.rst @@ -1,123 +1 @@ -Using different IP Adresses for SD – FD Communication -===================================================== -.. index:: General; Lan Address - -Bareos supports network topologies where the |bareosFd| and - |bareosSd| are situated inside of a LAN, but the - |bareosDir| is outside of that LAN in the Internet and -accesses the |bareosFd| and |bareosSd| via SNAT / -port forwarding. - -Consider the following scheme: - -.. raw:: latex - - \begin{commands}{} - /-------------------\ - | | LAN 10.0.0.1/24 - | | - | FD_LAN SD_LAN | - | .10 .20 | - | | - \___________________/ - | - NAT Firewall - FD: 8.8.8.10 -> 10.0.0.10 - SD: 8.8.8.20 -> 10.0.0.20 - | - /-------------------\ - | | - | | WAN / Internet - | DIR | - | 8.8.8.100 | - | | - | FD_WAN SD_WAN | - | .30 .40 | - \___________________/ - \end{commands} - -The |bareosDir| can access the **FD_LAN** via -the IP 8.8.8.10, which is forwarded to the IP 10.0.0.10 inside of the -LAN. - -The |bareosDir| can access the **SD_LAN** via -the IP 8.8.8.20 which is forwarded to the IP 10.0.0.20 inside of the -LAN. - -There is also a |bareosFd| and a - |bareosSd| outside of the LAN, which have the IPs 8.8.8.30 -and 8.8.8.40 - -All resources are configured so that the -:raw-latex:`\configdirective{Address}` directive gets the address where -the |bareosDir| can reach the daemons. - -Additionally, devices being in the LAN get the LAN address configured in -the :raw-latex:`\configdirective{Lan Address}` directive. The -configuration looks as follows: - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-dir}{client}{FD\_LAN} - Client { - Name = FD_LAN - Address = 8.8.8.10 - LanAddress = 10.0.0.10 - ... - } - \end{bareosConfigResource} - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-dir}{client}{SD\_LAN} - Storage { - Name = SD_LAN - Address = 8.8.8.20 - LanAddress = 10.0.0.20 - ... - } - \end{bareosConfigResource} - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-dir}{client}{FD\_WAN} - Client { - Name = FD_WAN - Address = 8.8.8.30 - ... - } - \end{bareosConfigResource} - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-dir}{client}{SD\_WAN} - Storage { - Name = SD_WAN - Address = 8.8.8.40 - ... - } - \end{bareosConfigResource} - -This way, backups and restores from each |bareosFd| using -each |bareosSd| are possible as long as the firewall allows -the needed network connections. - -The |bareosDir| simply checks if both the involved - |bareosFd| and |bareosSd| both have a -:raw-latex:`\configdirective{Lan Address}` -(Lan Address and -Lan Address) -configured. - -In that case, the initiating daemon is ordered to connect to the -:raw-latex:`\configdirective{Lan Address}` instead of the -:raw-latex:`\configdirective{Address}`. In active client mode, the - |bareosFd| connects to the |bareosSd| , in passive -client mode (see :ref:`PassiveClient`) the - |bareosSd| connects to the |bareosFd| . - -If only one or none of the involved |bareosFd| and - |bareosSd| have a :raw-latex:`\configdirective{Lan Address}` -configured, the :raw-latex:`\configdirective{Address}` is used as -connection target for the initiating daemon. diff --git a/docs/manuals/en/new_main_reference/source/license.rst b/docs/manuals/en/new_main_reference/source/license.rst index 77b0f2b79cc..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/license.rst +++ b/docs/manuals/en/new_main_reference/source/license.rst @@ -1,111 +1 @@ -Licenses Overview -================= -There are a number of different licenses that are used in Bareos. - -FDL ---- - -.. index:: - triple: General; License; FDL -.. _`License`: - - -The :ref:`fdl GNU Free Documentation License (FDL)` is -used for this manual, which is a free and open license. This means that -you may freely reproduce it and even make changes to it. - -AGPL ----- - -.. index:: - triple: General; License; AGPL -.. _`License`: - - -The vast bulk of the source code is released under the -:ref:`agpl GNU Affero General Public License (AGPL) version 3`. - -Most of this code is copyrighted: Copyright ©2000-2012 Free Software -Foundation Europe e.V. - -All new code is copyrighted: Copyright ©2013-2013 Bareos GmbH & Co. KG - -Portions may be copyrighted by other people. These files are released -under different licenses which are compatible with the AGPL license. - -LGPL ----- - -.. index:: - triple: General; License; LGPL -.. _`License`: - - -Some of the Bareos library source code is released under the -:ref:`lgpl GNU Lesser General Public License (LGPL)`. -This permits third parties to use these parts of our code in their -proprietary programs to interface to Bareos. - -Public Domain -------------- - -.. index:: - triple: General; License; Public Domain -.. _`License`: - - -Some of the Bareos code, or code that Bareos references, has been -released to the public domain. E.g. md5.c, SQLite. - -Trademark ---------- - -.. index:: General; Trademark -.. _`Trademark`: - - -Bareos:raw-latex:`\raisebox{.6ex}{\textsuperscript{\textregistered}}` is -a registered trademark of Bareos GmbH & Co. KG. - -Bacula:raw-latex:`\raisebox{.6ex}{\textsuperscript{\textregistered}}` is -a registered trademark of Kern Sibbald. - -Disclaimer ----------- - -.. index:: General; Disclaimer -.. _`Disclaimer`: - - -NO WARRANTY - -BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR -THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER -EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE -ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH -YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL -NECESSARY SERVICING, REPAIR OR CORRECTION. - -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR -DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL -DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM -(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED -INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF -THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR -OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -Other Copyrights and Trademarks -------------------------------- - -Certain words and/or products are Copyrighted or Trademarked such as -Windows (by Microsoft). Since they are numerous, and we are not -necessarily aware of the details of each, we don’t try to list them -here. However, we acknowledge all such Copyrights and Trademarks, and if -any copyright or trademark holder wishes a specific acknowledgment, -notify us, and we will be happy to add it where appropriate. diff --git a/docs/manuals/en/new_main_reference/source/messagesres.rst b/docs/manuals/en/new_main_reference/source/messagesres.rst index 20aa901caea..112b5162630 100644 --- a/docs/manuals/en/new_main_reference/source/messagesres.rst +++ b/docs/manuals/en/new_main_reference/source/messagesres.rst @@ -3,16 +3,9 @@ Messages Resource ================= - - -.. _`ResourceMessages`: ResourceMessages -.. index:: - triple: General; Resource; Messages -.. _`Resource`: - -.. index:: General; Messages Resource -.. _`Messages Resource`: - +:raw-latex:`\label{ResourceMessages}` +:raw-latex:`\index[general]{Resource!Messages}` +:raw-latex:`\index[general]{Messages Resource}` The Messages resource defines how messages are to be handled and destinations to which they should be sent. @@ -55,16 +48,16 @@ destination = address = message-type1, message-type2, message-type3, ... destination is one of a predefined set of keywords that define where the message is to be sent - (**Append** (Dir configuration, Messages resource), - **Console** (Dir configuration, Messages resource), - **File** (Dir configuration, Messages resource), - **Mail** (Dir configuration, Messages resource), ...), + (:raw-latex:`\linkResourceDirective{Dir}{Messages}{Append}`, + :raw-latex:`\linkResourceDirective{Dir}{Messages}{Console}`, + :raw-latex:`\linkResourceDirective{Dir}{Messages}{File}`, + :raw-latex:`\linkResourceDirective{Dir}{Messages}{Mail}`, ...), address varies according to the **destination** keyword, but is typically an email address or a filename, - :ref:`MessageTypes message-type` + :raw-latex:`\ilink{message-type}{MessageTypes}` is one of a predefined set of keywords that define the type of message generated by Bareos: **ERROR**, **WARNING**, **FATAL**, ... @@ -79,54 +72,40 @@ list of the following types or classes of messages: info | :raw-latex:`\hfill ` - | .. index:: General; Messages!type!info - | .. _`Messages!type!info`: - | General + | :raw-latex:`\index[general]{Messages!type!info}` General information messages. warning | :raw-latex:`\hfill ` - | .. index:: General; Messages!type!warning - | .. _`Messages!type!warning`: - | Warning + | :raw-latex:`\index[general]{Messages!type!warning}` Warning messages. Generally this is some unusual condition but not expected to be serious. error | :raw-latex:`\hfill ` - | .. index:: General; Messages!type!error - | .. _`Messages!type!error`: - | Non-fatal error + | :raw-latex:`\index[general]{Messages!type!error}` Non-fatal error messages. The job continues running. Any error message should be investigated as it means that something went wrong. fatal | :raw-latex:`\hfill ` - | .. index:: General; Messages!type!fatal - | .. _`Messages!type!fatal`: - | Fatal error + | :raw-latex:`\index[general]{Messages!type!fatal}` Fatal error messages. Fatal errors cause the job to terminate. terminate | :raw-latex:`\hfill ` - | .. index:: General; Messages!type!terminate - | .. _`Messages!type!terminate`: - | Message + | :raw-latex:`\index[general]{Messages!type!terminate}` Message generated when the daemon shuts down. notsaved | :raw-latex:`\hfill ` - | .. index:: General; Messages!type!notsaved - | .. _`Messages!type!notsaved`: - | Files not + | :raw-latex:`\index[general]{Messages!type!notsaved}` Files not saved because of some error. Usually because the file cannot be accessed (i.e. it does not exist or is not mounted). skipped | :raw-latex:`\hfill ` - | .. index:: General; Messages!type!skipped - | .. _`Messages!type!skipped`: - | Files that + | :raw-latex:`\index[general]{Messages!type!skipped}` Files that were skipped because of a user supplied option such as an incremental backup or a file that matches an exclusion pattern. This is not considered an error condition such as the files listed @@ -137,60 +116,44 @@ skipped mount | :raw-latex:`\hfill ` - | .. index:: General; Messages!type!mount - | .. _`Messages!type!mount`: - | Volume mount or + | :raw-latex:`\index[general]{Messages!type!mount}` Volume mount or intervention requests from the Storage daemon. These requests require a specific operator intervention for the job to continue. restored | :raw-latex:`\hfill ` - | .. index:: General; Messages!type!restored - | .. _`Messages!type!restored`: - | The **ls** + | :raw-latex:`\index[general]{Messages!type!restored}` The **ls** style listing generated for each file restored is sent to this message class. all | :raw-latex:`\hfill ` - | .. index:: General; Messages!type!all - | .. _`Messages!type!all`: - | All message types. + | :raw-latex:`\index[general]{Messages!type!all}` All message types. security | :raw-latex:`\hfill ` - | .. index:: General; Messages!type!security - | .. _`Messages!type!security`: - | Security + | :raw-latex:`\index[general]{Messages!type!security}` Security info/warning messages principally from unauthorized connection attempts. alert | :raw-latex:`\hfill ` - | .. index:: General; Messages!type!alert - | .. _`Messages!type!alert`: - | Alert messages. + | :raw-latex:`\index[general]{Messages!type!alert}` Alert messages. These are messages generated by tape alerts. volmgmt | :raw-latex:`\hfill ` - | .. index:: General; Messages!type!volmgmt - | .. _`Messages!type!volmgmt`: - | Volume + | :raw-latex:`\index[general]{Messages!type!volmgmt}` Volume management messages. Currently there are no volume management messages generated. audit | :raw-latex:`\hfill ` - | .. index:: General; Messages!type!audit - | .. _`Messages!type!audit`: - | - .. index:: General; auditing - .. _`auditing`: - Audit messages. Interacting + | :raw-latex:`\index[general]{Messages!type!audit}` + :raw-latex:`\index[general]{auditing}` Audit messages. Interacting with the Bareos Director will be audited. Can be configured with in resource - **Auditing** (Dir configuration, Director resource). + :raw-latex:`\linkResourceDirective{Dir}{Director}{Auditing}`. The following is an example of a valid Messages resource definition, where all messages except files explicitly skipped or daemon termination @@ -199,30 +162,28 @@ all mount messages are sent to the operator (i.e. emailed to backupoperator@example.com). Finally all messages other than explicitly skipped files and files saved are sent to the console: -.. raw:: latex +:: - \begin{bconfig}{Message resource} - Messages { - Name = Standard - Mail = backupoperator@example.com = all, !skipped, !terminate - Operator = backupoperator@example.com = mount - Console = all, !skipped, !saved - } - \end{bconfig} + {Message resource} + Messages { + Name = Standard + Mail = backupoperator@example.com = all, !skipped, !terminate + Operator = backupoperator@example.com = mount + Console = all, !skipped, !saved + } With the exception of the email address, an example Director’s Messages resource is as follows: -.. raw:: latex - - \begin{bconfig}{Message resource} - Messages { - Name = Standard - Mail Command = "/usr/sbin/bsmtp -h mail.example.com -f \"\(Bareos\) %r\" -s \"Bareos: %t %e of %c %l\" %r" - Operator Command = "/usr/sbin/bsmtp -h mail.example.com -f \"\(Bareos\) %r\" -s \"Bareos: Intervention needed for %j\" %r" - Mail On Error = backupoperator@example.com = all, !skipped, !terminate - Append = "/var/log/bareos/bareos.log" = all, !skipped, !terminate - Operator = backupoperator@example.com = mount - Console = all, !skipped, !saved - } - \end{bconfig} +:: + + {Message resource} + Messages { + Name = Standard + Mail Command = "/usr/sbin/bsmtp -h mail.example.com -f \"\(Bareos\) %r\" -s \"Bareos: %t %e of %c %l\" %r" + Operator Command = "/usr/sbin/bsmtp -h mail.example.com -f \"\(Bareos\) %r\" -s \"Bareos: Intervention needed for %j\" %r" + Mail On Error = backupoperator@example.com = all, !skipped, !terminate + Append = "/var/log/bareos/bareos.log" = all, !skipped, !terminate + Operator = backupoperator@example.com = mount + Console = all, !skipped, !saved + } diff --git a/docs/manuals/en/new_main_reference/source/migration.rst b/docs/manuals/en/new_main_reference/source/migration.rst index 55ea19ffe17..2d494f4c080 100644 --- a/docs/manuals/en/new_main_reference/source/migration.rst +++ b/docs/manuals/en/new_main_reference/source/migration.rst @@ -3,12 +3,8 @@ Migration and Copy ================== -.. index:: General; Migration -.. _`Migration`: - -.. index:: General; Copy -.. _`Copy`: - +:raw-latex:`\index[general]{Migration}` +:raw-latex:`\index[general]{Copy}` The term Migration, as used in the context of Bareos, means moving data from one Volume to another. In particular it refers to a Job (similar to @@ -51,13 +47,13 @@ The details of these selection criteria will be defined below. To run a Migration job, you must first define a Job resource very similar to a Backup Job but with -**Type** (Dir configuration, Job resource) = Migrate instead of -**Type** (Dir configuration, Job resource) = Backup. One of the +:raw-latex:`\linkResourceDirective{Dir}{Job}{Type}` = Migrate instead of +:raw-latex:`\linkResourceDirective{Dir}{Job}{Type}` = Backup. One of the key points to remember is that the Pool that is specified for the migration job is the only pool from which jobs will be migrated, with one exception noted below. In addition, the Pool to which the selected Job or Jobs will be migrated is defined by the -**Next Pool** (Dir configuration, Pool resource) = ... in the +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Next Pool}` = ... in the Pool resource specified for the Migration Job. Bareos permits Pools to contain Volumes of different Media Types. @@ -68,7 +64,7 @@ of the same Media Type for all migration jobs. A migration job can be started manually or from a Schedule, like a backup job. It searches for existing backup Jobs that match the parameters specified in the migration Job resource, primarily a -**Selection Type** (Dir configuration, Job resource). If no +:raw-latex:`\linkResourceDirective{Dir}{Job}{Selection Type}`. If no match was found, the Migration job terminates without further action. Otherwise, for each Job found this way, the Migration Job will run a new Job which copies the Job data to a new Volume in the Migration Pool. @@ -95,14 +91,11 @@ rather than simultaneously. Important Migration Considerations ---------------------------------- -.. index:: - triple: General; Migration; Important Migration Considerations -.. _`Migration`: - +:raw-latex:`\index[general]{Migration!Important Migration Considerations}` - Each Pool into which you migrate Jobs or Volumes **must** contain Volumes of only one - **Media Type** (Dir configuration, Storage resource). + :raw-latex:`\linkResourceDirective{Dir}{Storage}{Media Type}`. - Migration takes place on a JobId by JobId basis. That is each JobId is migrated in its entirety and independently of other JobIds. Once @@ -137,7 +130,7 @@ Important Migration Considerations fatal error. - Setting the - **Migration High Bytes** (Dir configuration, Pool resource) + :raw-latex:`\linkResourceDirective{Dir}{Pool}{Migration High Bytes}` watermark is not sufficient for migration to take place. In addition, you must define and schedule a migration job which looks for jobs that can be migrated. @@ -147,10 +140,10 @@ Important Migration Considerations the same device or Bareos may block waiting to reserve a drive that it will never find. A way to prevent problems is that all your migration pools contain only one - **Media Type** (Dir configuration, Storage resource), and + :raw-latex:`\linkResourceDirective{Dir}{Storage}{Media Type}`, and that you always migrate to a pool with a different Media Type. -- The **Next Pool** (Dir configuration, Pool resource) = ... +- The :raw-latex:`\linkResourceDirective{Dir}{Pool}{Next Pool}` = ... directive must be defined in the Pool referenced in the Migration Job to define the Pool into which the data will be migrated. @@ -170,8 +163,8 @@ The following directives can be used to define a Copy or Migration job: Job Resource '''''''''''' -- **Type** (Dir configuration, Job resource) = - Migrate \| Copy +- :raw-latex:`\linkResourceDirective{Dir}{Job}{Type}` = + Migrate:raw-latex:`\textbar`Copy - @@ -185,8 +178,8 @@ Job Resource \linkResourceDirective{Dir}{Job}{Selection Pattern} -- | **Pool** (Dir configuration, Job resource) - | For **Selection Type** (Dir configuration, Job resource) +- | :raw-latex:`\linkResourceDirective{Dir}{Job}{Pool}` + | For :raw-latex:`\linkResourceDirective{Dir}{Job}{Selection Type}` other than SQLQuery, this defines what Pool will be examined for finding JobIds to migrate @@ -199,157 +192,151 @@ Job Resource Pool Resource ''''''''''''' -- | **Next Pool** (Dir configuration, Pool resource) +- | :raw-latex:`\linkResourceDirective{Dir}{Pool}{Next Pool}` | to what pool Jobs will be migrated -- | **Migration Time** (Dir configuration, Pool resource) - | if **Selection Type** (Dir configuration, Job resource) = +- | :raw-latex:`\linkResourceDirective{Dir}{Pool}{Migration Time}` + | if :raw-latex:`\linkResourceDirective{Dir}{Job}{Selection Type}` = PoolTime -- | **Migration High Bytes** (Dir configuration, Pool resource) - | if **Selection Type** (Dir configuration, Job resource) = +- | :raw-latex:`\linkResourceDirective{Dir}{Pool}{Migration High Bytes}` + | if :raw-latex:`\linkResourceDirective{Dir}{Job}{Selection Type}` = PoolOccupancy -- | **Migration Low Bytes** (Dir configuration, Pool resource) +- | :raw-latex:`\linkResourceDirective{Dir}{Pool}{Migration Low Bytes}` | optional if - **Selection Type** (Dir configuration, Job resource) = + :raw-latex:`\linkResourceDirective{Dir}{Job}{Selection Type}` = PoolOccupancy is used -- | **Storage** (Dir configuration, Pool resource) +- | :raw-latex:`\linkResourceDirective{Dir}{Pool}{Storage}` | if Copy/Migration involves multiple Storage Daemon, see - :ref:`sec:CopyMigrationJobsMultipleStorageDaemons` + :raw-latex:`\nameref{sec-CopyMigrationJobsMultipleStorageDaemons}` Example Migration Jobs ~~~~~~~~~~~~~~~~~~~~~~ -.. index:: - triple: General; Example; Migration Jobs -.. _`Example`: - +:raw-latex:`\index[general]{Example!Migration Jobs}` Assume a simple configuration with a single backup job as described below. -.. raw:: latex - - \begin{bconfig}{Backup Job} - # Define the backup Job - Job { - Name = "NightlySave" - Type = Backup - Level = Incremental # default - Client=rufus-fd - FileSet="Full Set" - Schedule = "WeeklyCycle" - Messages = Standard - Pool = Default - } - - # Default pool definition - Pool { - Name = Default - Pool Type = Backup - AutoPrune = yes - Recycle = yes - Next Pool = Tape - Storage = File - LabelFormat = "File" - } - - # Tape pool definition - Pool { - Name = Tape - Pool Type = Backup - AutoPrune = yes - Recycle = yes - Storage = DLTDrive - } - - # Definition of File storage device - Storage { - Name = File - Address = rufus - Password = "secret" - Device = "File" # same as Device in Storage daemon - Media Type = File # same as MediaType in Storage daemon - } - - # Definition of DLT tape storage device - Storage { - Name = DLTDrive - Address = rufus - Password = "secret" - Device = "HP DLT 80" # same as Device in Storage daemon - Media Type = DLT8000 # same as MediaType in Storage daemon - } - \end{bconfig} - -Note that the backup job writes to the **Default** pool, +:: + + {Backup Job} + # Define the backup Job + Job { + Name = "NightlySave" + Type = Backup + Level = Incremental # default + Client=rufus-fd + FileSet="Full Set" + Schedule = "WeeklyCycle" + Messages = Standard + Pool = Default + } + + # Default pool definition + Pool { + Name = Default + Pool Type = Backup + AutoPrune = yes + Recycle = yes + Next Pool = Tape + Storage = File + LabelFormat = "File" + } + + # Tape pool definition + Pool { + Name = Tape + Pool Type = Backup + AutoPrune = yes + Recycle = yes + Storage = DLTDrive + } + + # Definition of File storage device + Storage { + Name = File + Address = rufus + Password = "secret" + Device = "File" # same as Device in Storage daemon + Media Type = File # same as MediaType in Storage daemon + } + + # Definition of DLT tape storage device + Storage { + Name = DLTDrive + Address = rufus + Password = "secret" + Device = "HP DLT 80" # same as Device in Storage daemon + Media Type = DLT8000 # same as MediaType in Storage daemon + } + +Note that the backup job writes to the :raw-latex:`\pool{Default}` pool, which corresponds to :raw-latex:`\resourcename{Dir}{Storage}{File}` storage. There is no -**Storage** (Dir configuration, Pool resource) directive in the +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Storage}` directive in the Job resource while the two :raw-latex:`\resourcetype{Dir}{Pool}` resources contain different -**Storage** (Dir configuration, Pool resource) directives. -Moreover, the **Default** pool contains a -**Next Pool** (Dir configuration, Pool resource) directive that -refers to the **Tape** pool. +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Storage}` directives. +Moreover, the :raw-latex:`\pool{Default}` pool contains a +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Next Pool}` directive that +refers to the :raw-latex:`\pool{Tape}` pool. In order to migrate jobs from the :raw-latex:`\resourcename{Dir}{Pool}{Default}` pool to the :raw-latex:`\resourcename{Dir}{Pool}{Tape}` pool we add the following Job resource: -.. raw:: latex - - \begin{bconfig}{migrate all volumes of a pool} - Job { - Name = "migrate-volume" - Type = Migrate - Messages = Standard - Pool = Default - Selection Type = Volume - Selection Pattern = "." - } - \end{bconfig} - -The **Selection Type** (Dir configuration, Job resource) and -**Selection Pattern** (Dir configuration, Job resource) +:: + + {migrate all volumes of a pool} + Job { + Name = "migrate-volume" + Type = Migrate + Messages = Standard + Pool = Default + Selection Type = Volume + Selection Pattern = "." + } + +The :raw-latex:`\linkResourceDirective{Dir}{Job}{Selection Type}` and +:raw-latex:`\linkResourceDirective{Dir}{Job}{Selection Pattern}` directives instruct Bareos to select all volumes of the given pool -(**Default**) whose volume names match the given regular -expression (**"."**), i.e., all volumes. Hence those +(:raw-latex:`\pool{Default}`) whose volume names match the given regular +expression (:raw-latex:`\argument{"."}`), i.e., all volumes. Hence those jobs which were backed up to any volume in the -**Default** pool will be migrated. Because of the -**Next Pool** (Dir configuration, Pool resource) directive of -the **Default** pool resource, the jobs will be migrated +:raw-latex:`\pool{Default}` pool will be migrated. Because of the +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Next Pool}` directive of +the :raw-latex:`\pool{Default}` pool resource, the jobs will be migrated to tape storage. Another way to accomplish the same is the following Job resource: -.. raw:: latex - - \begin{bconfig}{migrate all jobs named *Save} - Job { - Name = "migrate" - Type = Migrate - Messages = Standard - Pool = Default - Selection Type = Job - Selection Pattern = ".*Save" - } - \end{bconfig} - -This migrates all jobs ending with **Save** from the -**Default}` pool to the :raw-latex:`\pool{Tape** pool, +:: + + {migrate all jobs named *Save} + Job { + Name = "migrate" + Type = Migrate + Messages = Standard + Pool = Default + Selection Type = Job + Selection Pattern = ".*Save" + } + +This migrates all jobs ending with :raw-latex:`\argument{Save}` from the +:raw-latex:`\pool{Default}` pool to the :raw-latex:`\pool{Tape}` pool, i.e., from File storage to Tape storage. -.. _sec:CopyMigrationJobsMultipleStorageDaemons: +.. _sec-CopyMigrationJobsMultipleStorageDaemons: Multiple Storage Daemons ^^^^^^^^^^^^^^^^^^^^^^^^ Beginning from Bareos -13.2.0, +:raw-latex:`\sinceVersion{dir}{Copy and Migration Jobs between different Storage Daemons}{13.2.0}`, Migration and Copy jobs are also possible from one Storage daemon to another Storage Daemon. @@ -365,7 +352,7 @@ Please note: the pool resource - to configure the migration from pool1 to pool2, the - **Next Pool** (Dir configuration, Pool resource) directive + :raw-latex:`\linkResourceDirective{Dir}{Pool}{Next Pool}` directive of pool1 has to point to pool2 - the copy job itself has to be of type copy/migrate (exactly as @@ -373,64 +360,63 @@ Please note: Example: -.. raw:: latex - - \begin{bconfig}{bareos-dir.conf: Copy Job between different Storage Daemons} - #bareos-dir.conf - - # Fake fileset for copy jobs - Fileset { - Name = None - Include { - Options { - signature = MD5 - } - } - } - - # Fake client for copy jobs - Client { - Name = None - Address = localhost - Password = "NoNe" - Catalog = MyCatalog - } - - # Source storage for migration - Storage { - Name = storage1 - Address = sd1.example.com - Password = "secret1" - Device = File1 - Media Type = File - } - - # Target storage for migration - Storage { - Name = storage2 - Address = sd2.example.com - Password = "secret2" - Device = File2 - Media Type = File2 # Has to be different than in storage1 - } - - Pool { - Name = pool1 - Storage = storage1 - Next Pool = pool2 # This points to the target storage - } - - Pool { - Name = pool2 - Storage = storage2 - } - - Job { - Name = CopyToRemote - Type = Copy - Messages = Standard - Selection Type = PoolUncopiedJobs - Spool Data = Yes - Pool = pool1 - } - \end{bconfig} +:: + + {bareos-dir.conf: Copy Job between different Storage Daemons} + #bareos-dir.conf + + # Fake fileset for copy jobs + Fileset { + Name = None + Include { + Options { + signature = MD5 + } + } + } + + # Fake client for copy jobs + Client { + Name = None + Address = localhost + Password = "NoNe" + Catalog = MyCatalog + } + + # Source storage for migration + Storage { + Name = storage1 + Address = sd1.example.com + Password = "secret1" + Device = File1 + Media Type = File + } + + # Target storage for migration + Storage { + Name = storage2 + Address = sd2.example.com + Password = "secret2" + Device = File2 + Media Type = File2 # Has to be different than in storage1 + } + + Pool { + Name = pool1 + Storage = storage1 + Next Pool = pool2 # This points to the target storage + } + + Pool { + Name = pool2 + Storage = storage2 + } + + Job { + Name = CopyToRemote + Type = Copy + Messages = Standard + Selection Type = PoolUncopiedJobs + Spool Data = Yes + Pool = pool1 + } diff --git a/docs/manuals/en/new_main_reference/source/monitorconf.rst b/docs/manuals/en/new_main_reference/source/monitorconf.rst index f8012db3a5c..8adce41ace5 100644 --- a/docs/manuals/en/new_main_reference/source/monitorconf.rst +++ b/docs/manuals/en/new_main_reference/source/monitorconf.rst @@ -1,15 +1,10 @@ -.. _sec:MonitorConfig: +.. _sec-MonitorConfig: Monitor Configuration ===================== -.. index:: General; Monitor Configuration -.. _`Monitor Configuration`: - -.. index:: - triple: General; Configuration; Monitor -.. _`Configuration`: - +:raw-latex:`\index[general]{Monitor Configuration}` +:raw-latex:`\index[general]{Configuration!Monitor}` The Monitor configuration file is a stripped down version of the Director configuration file, mixed with a Console configuration file. It @@ -18,19 +13,19 @@ and Storage daemons you want to monitor. For a general discussion of configuration file and resources including the data types recognized by **Bareos**, please see the -:ref:`ConfigureChapter Configuration` chapter of this +:raw-latex:`\ilink{Configuration}{ConfigureChapter}` chapter of this manual. The following Monitor Resource definition must be defined: -- :ref:`MonitorResource Monitor` – to define the +- :raw-latex:`\ilink{Monitor}{MonitorResource}` – to define the Monitor’s name used to connect to all the daemons and the password used to connect to the Directors. Note, you must not define more than one Monitor resource in the Monitor configuration file. -- At least one :ref:`ClientResource1 Client`, - :ref:`StorageResource1 Storage` or - :ref:`DirectorResource2 Director` resource, to define +- At least one :raw-latex:`\ilink{Client}{ClientResource1}`, + :raw-latex:`\ilink{Storage}{StorageResource1}` or + :raw-latex:`\ilink{Director}{DirectorResource2}` resource, to define the daemons to monitor. .. _MonitorResource: @@ -38,13 +33,8 @@ The following Monitor Resource definition must be defined: Monitor Resource ---------------- -.. index:: General; Monitor Resource -.. _`Monitor Resource`: - -.. index:: - triple: General; Resource; Monitor -.. _`Resource`: - +:raw-latex:`\index[general]{Monitor Resource}` +:raw-latex:`\index[general]{Resource!Monitor}` The Monitor resource defines the attributes of the Monitor running on the network. The parameters you define here must be configured as a @@ -56,20 +46,15 @@ Console resource in Directors configuration files. Director Resource ----------------- -.. index:: General; Director Resource -.. _`Director Resource`: - -.. index:: - triple: General; Resource; Director -.. _`Resource`: - +:raw-latex:`\index[general]{Director Resource}` +:raw-latex:`\index[general]{Resource!Director}` The Director resource defines the attributes of the Directors that are monitored by this Monitor. As you are not permitted to define a Password in this resource, to avoid obtaining full Director privileges, you must create a Console resource -in the :ref:`DirectorChapter Director's configuration` +in the :raw-latex:`\ilink{Director's configuration}{DirectorChapter}` file, using the Console Name and Password defined in the Monitor resource. To avoid security problems, you should configure this Console resource to allow access to no other daemons, and permit the use of only @@ -83,19 +68,14 @@ Monitor configuration file. Client Resource --------------- -.. index:: - triple: General; Resource; Client -.. _`Resource`: - -.. index:: General; Client Resource -.. _`Client Resource`: - +:raw-latex:`\index[general]{Resource!Client}` +:raw-latex:`\index[general]{Client Resource}` The Client resource defines the attributes of the Clients that are monitored by this Monitor. You must create a Director resource in the -:ref:`FiledConfChapter Client's configuration` file, +:raw-latex:`\ilink{Client's configuration}{FiledConfChapter}` file, using the Director Name defined in the Monitor resource. To avoid security problems, you should set the **Monitor** directive to **Yes** in this Director resource. @@ -108,19 +88,14 @@ Monitor configuration file. Storage Resource ---------------- -.. index:: - triple: General; Resource; Storage -.. _`Resource`: - -.. index:: General; Storage Resource -.. _`Storage Resource`: - +:raw-latex:`\index[general]{Resource!Storage}` +:raw-latex:`\index[general]{Storage Resource}` The Storage resource defines the attributes of the Storages that are monitored by this Monitor. You must create a Director resource in the -:ref:`StoredConfChapter Storage's configuration` file, +:raw-latex:`\ilink{Storage's configuration}{StoredConfChapter}` file, using the Director Name defined in the Monitor resource. To avoid security problems, you should set the **Monitor** directive to **Yes** in this Director resource. @@ -134,13 +109,8 @@ Tray Monitor Tray Monitor Security ~~~~~~~~~~~~~~~~~~~~~ -.. index:: General; Tray Monitor Security -.. _`Tray Monitor Security`: - -.. index:: - triple: General; Security; Tray Monitor -.. _`Security`: - +:raw-latex:`\index[general]{Tray Monitor Security}` +:raw-latex:`\index[general]{Security!Tray Monitor}` There is no security problem in relaxing the permissions on tray-monitor.conf as long as FD, SD and DIR are configured properly, so @@ -166,103 +136,93 @@ being dangerous). Example Tray Monitor configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. index:: - triple: General; Tray Monitor; Configuration -.. _`Tray Monitor`: - -.. index:: - triple: General; Configuration; Tray Monitor -.. _`Configuration`: - +:raw-latex:`\index[general]{Tray Monitor!Configuration}` +:raw-latex:`\index[general]{Configuration!Tray Monitor}` An example Tray Monitor configuration file might be the following: -.. raw:: latex - - \begin{bconfig}{Example tray-monitor.conf} - # - # Bareos Tray Monitor Configuration File - # - Monitor { - Name = rufus-mon # password for Directors - Password = "GN0uRo7PTUmlMbqrJ2Gr1p0fk0HQJTxwnFyE4WSST3MWZseR" - RefreshInterval = 10 seconds - } - - Client { - Name = rufus-fd - Address = rufus - FDPort = 9102 # password for FileDaemon - Password = "FYpq4yyI1y562EMS35bA0J0QC0M2L3t5cZObxT3XQxgxppTn" - } - Storage { - Name = rufus-sd - Address = rufus - SDPort = 9103 # password for StorageDaemon - Password = "9usxgc307dMbe7jbD16v0PXlhD64UVasIDD0DH2WAujcDsc6" - } - Director { - Name = rufus-dir - DIRport = 9101 - address = rufus - } - \end{bconfig} +:: + + {Example tray-monitor.conf} + # + # Bareos Tray Monitor Configuration File + # + Monitor { + Name = rufus-mon # password for Directors + Password = "GN0uRo7PTUmlMbqrJ2Gr1p0fk0HQJTxwnFyE4WSST3MWZseR" + RefreshInterval = 10 seconds + } + + Client { + Name = rufus-fd + Address = rufus + FDPort = 9102 # password for FileDaemon + Password = "FYpq4yyI1y562EMS35bA0J0QC0M2L3t5cZObxT3XQxgxppTn" + } + Storage { + Name = rufus-sd + Address = rufus + SDPort = 9103 # password for StorageDaemon + Password = "9usxgc307dMbe7jbD16v0PXlhD64UVasIDD0DH2WAujcDsc6" + } + Director { + Name = rufus-dir + DIRport = 9101 + address = rufus + } Example File daemon’s Director record ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. raw:: latex +:: - \begin{bconfig}{Example Monitor resource} - # - # Restricted Director, used by tray-monitor to get the - # status of the file daemon - # - Director { - Name = rufus-mon - Password = "FYpq4yyI1y562EMS35bA0J0QC0M2L3t5cZObxT3XQxgxppTn" - Monitor = yes - } - \end{bconfig} + {Example Monitor resource} + # + # Restricted Director, used by tray-monitor to get the + # status of the file daemon + # + Director { + Name = rufus-mon + Password = "FYpq4yyI1y562EMS35bA0J0QC0M2L3t5cZObxT3XQxgxppTn" + Monitor = yes + } A full example can be found at -:ref:`SampleClientConfiguration`. +:raw-latex:`\nameref{SampleClientConfiguration}`. Example Storage daemon’s Director record ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. raw:: latex +:: - \begin{bconfig}{Example Monitor resource} - # - # Restricted Director, used by tray-monitor to get the - # status of the storage daemon - # - Director { - Name = rufus-mon - Password = "9usxgc307dMbe7jbD16v0PXlhD64UVasIDD0DH2WAujcDsc6" - Monitor = yes - } - \end{bconfig} + {Example Monitor resource} + # + # Restricted Director, used by tray-monitor to get the + # status of the storage daemon + # + Director { + Name = rufus-mon + Password = "9usxgc307dMbe7jbD16v0PXlhD64UVasIDD0DH2WAujcDsc6" + Monitor = yes + } A full example can be found at -:ref:`ExampleStorageConfiguration`. +:raw-latex:`\nameref{ExampleStorageConfiguration}`. Example Director’s Console record ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. raw:: latex +:: - \begin{bconfig}{Example Monitor resource} - # - # Restricted console used by tray-monitor to get the status of the director - # - Console { - Name = Monitor - Password = "GN0uRo7PTUmlMbqrJ2Gr1p0fk0HQJTxwnFyE4WSST3MWZseR" - CommandACL = status, .status - } - \end{bconfig} + {Example Monitor resource} + # + # Restricted console used by tray-monitor to get the status of the director + # + Console { + Name = Monitor + Password = "GN0uRo7PTUmlMbqrJ2Gr1p0fk0HQJTxwnFyE4WSST3MWZseR" + CommandACL = status, .status + } A full example can be found at -:ref:`SampleDirectorConfiguration`. +:raw-latex:`\nameref{SampleDirectorConfiguration}`. diff --git a/docs/manuals/en/new_main_reference/source/ndmp.rst b/docs/manuals/en/new_main_reference/source/ndmp.rst index ba08fa07d9f..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/ndmp.rst +++ b/docs/manuals/en/new_main_reference/source/ndmp.rst @@ -1,50 +1 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/manuals/en/new_main_reference/source/passiveclient.rst b/docs/manuals/en/new_main_reference/source/passiveclient.rst index a94c98e511d..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/passiveclient.rst +++ b/docs/manuals/en/new_main_reference/source/passiveclient.rst @@ -1,79 +1 @@ -.. _PassiveClient: -Passive Clients -=============== - -The normal way of initializing the data channel (the channel where the -backup data itself is transported) is done by the -|bareosFd| (client) that connects to the -|bareosSd|. - -In many setups, this can cause problems, as this means that: - -- The client must be able to resolve the name of the - |bareosSd| (often not true, you have to do tricks with - the hosts file) - -- The client must be allowed to create a new connection. - -- The client must be able to connect to the |bareosSd| over - the network (often difficult over NAT or Firewall) - -By using Passive Client, the initialization of the datachannel is -reversed, so that the storage daemon connects to the -|bareosFd|. This solves almost every problem created by -firewalls, NAT-gateways and resolving issues, as - -- The |bareosSd| initiates the connection, and thus can - pass through the same or similar firewall rules that the director - already has to access the |bareosFd|. - -- The client never initiates any connection, thus can be completely - firewalled. - -- The client never needs any name resolution and is totally independent - from any resolving issues. - -|image| - -Usage ------ - -To use this new feature, just configure -**Passive** (Dir configuration, Client resource)=yes in the -client definition of the |bareosDir|: - -.. raw:: latex - - \begin{bconfig}{Enable passive mode in bareos-dir.conf} - Client { - Name = client1-fd - Password = "secretpassword" - Passive = yes - [...] - } - \end{bconfig} - -Also, prior to bareos version 15, you need to set -**Compatible** (Fd configuration, Client resource)=no in the -*bareos-fd.conf* configuration file. Since Bareos -Version 15, the compatible option is set to no per default and does not -need to be specified anymore. - -.. raw:: latex - - \begin{bconfig}{Disable compatible mode for the \bareosFd in bareos-fd.conf} - Director { - Name = bareos-dir - Password = "secretpassword" - } - - Client { - Name = client1-fd - [...] - Compatible = no - } - \end{bconfig} - -.. |image| image:: \idir passive-client-communication - :width: 60.0% diff --git a/docs/manuals/en/new_main_reference/source/plugins.rst b/docs/manuals/en/new_main_reference/source/plugins.rst deleted file mode 100644 index d0387174f29..00000000000 --- a/docs/manuals/en/new_main_reference/source/plugins.rst +++ /dev/null @@ -1,1255 +0,0 @@ -Plugins -======= - -.. index:: General; Plugin}` :raw-latex:`\label{sec:plugins - -The functionality of Bareos can be extended by plugins. They do exists -plugins for the different daemons (Director, Storage- and File-Daemon). - -To use plugins, they must be enabled in the configuration -(:raw-latex:`\configdirective{Plugin Directory}` and optionally -:raw-latex:`\configdirective{Plugin Names}`). - -If a :raw-latex:`\configdirective{Plugin Directory}` is specified -:raw-latex:`\configdirective{Plugin Names}` defines, which plugins get -loaded. - -If :raw-latex:`\configdirective{Plugin Names}` is not defined. - -File Daemon Plugins -------------------- - -File Daemon plugins are configured by the -:raw-latex:`\configdirective{Plugin}` directive of a -:ref:`File Set directive-fileset-plugin`. - - -.. warning:: - Currently the plugin command is being stored as part of the backup. The restore command in your directive should be flexible enough if things might change in future, otherwise you could run into trouble. - -bpipe Plugin -~~~~~~~~~~~~ - - -.. index:: - triple: General; Plugin; bpipe - -The bpipe plugin is a generic pipe program, that simply transmits the -data from a specified program to Bareos for backup, and from Bareos to a -specified program for restore. The purpose of the plugin is to provide -an interface to any system program for backup and restore. That allows -you, for example, to do database backups without a local dump. By using -different command lines to bpipe, you can backup any kind of data (ASCII -or binary) depending on the program called. - -On Linux, the Bareos bpipe plugin is part of the -**bareos-filedaemon** package and is therefore -installed on any system running the filedaemon. - -The bpipe plugin is so simple and flexible, you may call it the “Swiss -Army Knife” of the current existing plugins for Bareos. - -The bpipe plugin is specified in the Include section of your Job’s -FileSet resource in your *bareos-dir.conf*. - -.. raw:: latex - - \begin{bconfig}{bpipe fileset} - FileSet { - Name = "MyFileSet" - Include { - Options { - signature = MD5 - compression = gzip - } - Plugin = "bpipe:file=:reader=:writer= - } - } - \end{bconfig} - -The syntax and semantics of the Plugin directive require the first part -of the string up to the colon to be the name of the plugin. Everything -after the first colon is ignored by the File daemon but is passed to the -plugin. Thus the plugin writer may define the meaning of the rest of the -string as he wishes. The full syntax of the plugin directive as -interpreted by the bpipe plugin is: - -.. raw:: latex - - \begin{bconfig}{bpipe directive} - Plugin = ":file=:reader=:writer=" - \end{bconfig} - -plugin - is the name of the plugin with the trailing -fd.so stripped off, so - in this case, we would put bpipe in the field. - -filepath - specifies the namespace, which for bpipe is the pseudo path and - filename under which the backup will be saved. This pseudo path and - filename will be seen by the user in the restore file tree. For - example, if the value is **/MySQL/mydump.sql**, - the data backed up by the plugin will be put under that - :raw-latex:`\bquote{pseudo}` path and filename. You must be careful - to choose a naming convention that is unique to avoid a conflict - with a path and filename that actually exists on your system. - -readprogram - for the bpipe plugin specifies the “reader” program that is called - by the plugin during backup to read the data. bpipe will call this - program by doing a popen on it. - -writeprogram - for the bpipe plugin specifies the “writer” program that is called - by the plugin during restore to write the data back to the - filesystem. - -Please note that the two items above describing the “reader” and -“writer”, these programs are “executed” by Bareos, which means there is -no shell interpretation of any command line arguments you might use. If -you want to use shell characters (redirection of input or output, ...), -then we recommend that you put your command or commands in a shell -script and execute the script. In addition if you backup a file with -reader program, when running the writer program during the restore, -Bareos will not automatically create the path to the file. Either the -path must exist, or you must explicitly do so with your command or in a -shell script. - -See the examples about :ref:`backup-postgresql` and -:ref:`backup-mysql`. - -PGSQL Plugin -~~~~~~~~~~~~ - -See chapter :ref:`backup-postgresql-plugin`. - -MySQL Plugin -~~~~~~~~~~~~ - -See the chapters :ref:`backup-mysql-xtrabackup` and -:ref:`backup-mysql-python`. - -MSSQL Plugin -~~~~~~~~~~~~ - -See chapter :ref:`MSSQL`. - -LDAP Plugin -~~~~~~~~~~~ - - -.. index:: - triple: General; Plugin; ldap - -This plugin is intended to backup (and restore) the contents of a LDAP -server. It uses normal LDAP operation for this. The package -**bareos-filedaemon-ldap-python-plugin** -(15.2.0) contains an -example configuration file, that must be adapted to your envirnoment. - -Cephfs Plugin -~~~~~~~~~~~~~ - - -.. index:: - triple: General; Plugin!ceph; cephfs - -.. index:: - triple: General; Ceph; Cephfs Plugin - -Opposite to the :ref:`Rados Backend SdBackendRados` that -is used to store data on a CEPH Object Store, this plugin is intended to -backup a CEPH Object Store via the Cephfs interface to other media. The -package **bareos-filedaemon-ceph-plugin** -(15.2.0) contains an -example configuration file, that must be adapted to your envirnoment. - -Rados Plugin -~~~~~~~~~~~~ - - -.. index:: - triple: General; Plugin!ceph; rados - -.. index:: - triple: General; Ceph; Rados Plugin - -Opposite to the :ref:`Rados Backend SdBackendRados` that -is used to store data on a CEPH Object Store, this plugin is intended to -backup a CEPH Object Store via the Rados interface to other media. The -package **bareos-filedaemon-ceph-plugin** -(15.2.0) contains an -example configuration file, that must be adapted to your envirnoment. - -GlusterFS Plugin -~~~~~~~~~~~~~~~~ - - -.. index:: - triple: General; Plugin; glusterfs - -.. index:: - triple: General; GlusterFS; Plugin - -Opposite to the :ref:`GFAPI Backend SdBackendGfapi` that -is used to store data on a Gluster system, this plugin is intended to -backup data from a Gluster system to other media. The package -**bareos-filedaemon-glusterfs-plugin** -(15.2.0) contains an -example configuration file, that must be adapted to your envirnoment. - -python-fd Plugin -~~~~~~~~~~~~~~~~ - - -.. index:: - triple: General; Plugin!Python; File Daemon - -The **python-fd** plugin behaves similar to the -:ref:`director-python-plugin`. Base plugins and an -example get installed via the package bareos-filedaemon-python-plugin. -Configuration is done in the -:ref:`DirectorResourceFileSet` on the director. - -We basically distinguish between command-plugin and option-plugins. - -Command Plugins -^^^^^^^^^^^^^^^ - -Command plugins are used to replace or extend the FileSet definition in -the File Section. If you have a command-plugin, you can use it like in -this example: - -.. raw:: latex - - \begin{bconfig}{bareos-dir.conf: Python FD command plugins} - FileSet { - Name = "mysql" - Include { - Options { - Signature = MD5 # calculate md5 checksum per file - } - File = "/etc" - Plugin = "python:module_path=/usr/lib/bareos/plugins:module_name=bareos-fd-mysql" - } - } - \end{bconfig} - - -.. index:: - triple: General; MySQL; Backup This example uses the -:ref:`MySQL plugin backup-mysql-python` to backup MySQL -dumps in addition to */etc*. - -Option Plugins -^^^^^^^^^^^^^^ - -Option plugins are activated in the Options resource of a FileSet -definition. - -Example: - -.. raw:: latex - - \begin{bconfig}{bareos-dir.conf: Python FD option plugins} - FileSet { - Name = "option" - Include { - Options { - Signature = MD5 # calculate md5 checksum per file - Plugin = "python:module_path=/usr/lib/bareos/plugins:module_name=bareos-fd-file-interact" - } - File = "/etc" - File = "/usr/lib/bareos/plugins" - } - } - \end{bconfig} - -This plugin bareos-fd-file-interact from -https://github.com/bareos/bareos-contrib/tree/master/fd-plugins/options-plugin-sample -has a method that is called before and after each file that goes into -the backup, it can be used as a template for whatever plugin wants to -interact with files before or after backup. - -VMware Plugin -~~~~~~~~~~~~~ - - -.. index:: - triple: General; Plugin; VMware -.. index:: General; VMware Plugin - -The |vmware|  Plugin can be used for agentless backups of -virtual machines running on |vsphere| . It makes use of CBT -(Changed Block Tracking) to do space efficient full and incremental -backups, see below for mandatory requirements. - -It is included in Bareos since -15.2.0. - -Status -^^^^^^ - -The Plugin can do full, differential and incremental backup and restore -of VM disks. - -Current limitations amongst others are: - -:raw-latex:`\limitation*{VMware Plugin}{Normal VM disks can not be excluded from the backup}{% - It is not yet possible to exclude normal (dependent) VM disks from backups. - However, independent disks are excluded implicitly because they are not affected - by snapshots which are required for CBT based backup.}` - -:raw-latex:`\limitation*{VMware Plugin}{VM configuration is not backed up}{% - The VM configuration is not backed up, so that it is not yet possible to recreate a completely deleted VM.}` - -:raw-latex:`\limitation*{VMware Plugin}{Virtual Disks have to be smaller than 2TB}{% - Virtual Disks have to be smaller than 2 TB, see \ticket{670}.}` - -:raw-latex:`\limitation*{VMware Plugin}{Restore can only be done to the same VM or to local VMDK files}{% - Until Bareos Version 15.2.2, the restore has only be possible to the same existing VM with existing virtual disks. - Since \sinceVersion{fd}{VMware Plugin: restore to VMDK files}{15.2.3} - %\package{bareos-vadp-dumper} \sinceVersion{fd}{bareos-vadp-dumper}{15.2.2-15} and - %\package{bareos-vmware-plugin} \sinceVersion{fd}{bareos-vmware-plugin}{15.2.2-27} - it is also possible to restore to local VMDK files, see below for more details.}` - -Requirements -^^^^^^^^^^^^ - -As the Plugin is based on the |vsphere| Storage APIs for Data -Protection, which requires at least a |vsphere| Essentials -License. It is tested against |vsphere| Storage APIs for Data -Protection of |vmware| 5.x. It does not work with standalone -unlicensed |vmware| ESXi:raw-latex:`\trademark`. - -Since Bareos -17.2.4 the -plugin is using the Virtual Disk Development Kit (VDDK) 6.5.2, as of the -VDDK 6.5 release notes, it should be compatible with vSphere 6.5 and the -next major release (except new features) and backward compatible with -vSphere 5.5 and 6.0, see VDDK release notes at -https://code.vmware.com/web/sdk/65/vddk for details. - -Installation -^^^^^^^^^^^^ - -Install the package **bareos-vmware-plugin** -including its requirments by using an appropriate package management -tool (eg. :command:`yum}`, :raw-latex:`\command{zypper`, -:command:`apt`) - -The http://www.bareos.org/en/faq.html may have -additional useful information. - -Configuration -^^^^^^^^^^^^^ - -First add a user account in vCenter that has full privileges by -assigning the account to an administrator role or by adding the account -to a group that is assigned to an administrator role. While any user -account with full privileges could be used, it is better practice to -create a separate user account, so that the actions by this account -logged in vSphere are clearly distinguishable. In the future a more -detailed set of required role privilges may be defined. - -When using the vCenter appliance with embedded SSO, a user account -usually has the structure -:command:`@vsphere.local`, it may be different -when using Active Directory as SSO in vCenter. For the examples here, we -will use :command:`bakadm@vsphere.local` with the password -:command:`Bak.Adm-1234`. - -For more details regarding users and permissions in vSphere see - -- http://pubs.vmware.com/vsphere-55/topic/com.vmware.vsphere.security.doc/GUID-72BFF98C-C530-4C50-BF31-B5779D2A4BBB.html - and - -- http://pubs.vmware.com/vsphere-55/topic/com.vmware.vsphere.security.doc/GUID-5372F580-5C23-4E9C-8A4E-EF1B4DD9033E.html - -Make sure to add or enable the following settings in your - |bareosFd| configuration: - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-fd}{client}{myself} - Client { - ... - Plugin Directory = /usr/lib/bareos/plugins - Plugin Names = python - ... - } - \end{bareosConfigResource} - -Note: Depending on Platform, the Plugin Directory may also be -*/usr/lib64/bareos/plugins* - -To define the backup of a VM in Bareos, a job definition and a fileset -resource must be added to the Bareos director configuration. In vCenter, -VMs are usually organized in datacenters and folders. The following -example shows how to configure the backup of the VM named *websrv1* in -the datacenter *mydc1* folder *webservers* on the vCenter server -:command:`vcenter.example.org`: - -.. raw:: latex - - \begin{bconfig}{bareos-dir.conf: VMware Plugin Job and FileSet definition} - Job { - Name = "vm-websrv1" - JobDefs = "DefaultJob" - FileSet = "vm-websrv1_fileset" - } - - FileSet { - Name = "vm-websrv1_fileset" - - Include { - Options { - signature = MD5 - Compression = GZIP - } - Plugin = "python:module_path=/usr/lib64/bareos/plugins:module_name=bareos-fd-vmware:dc=mydc1:folder=/webservers:vmname=websrv1:vcserver=vcenter.example.org:vcuser=bakadm@vsphere.local:vcpass=Bak.Adm-1234" - } - } - \end{bconfig} - -For VMs defined in the root-folder, :command:`folder=/` must -be specified in the Plugin definition. - -Since Bareos -17.2.4 -the **module\_path** is without -*vmware_plugin* directory. On upgrades you either -adapt your configuration from - -.. raw:: latex - - \begin{bconfig}{python:module\_path for Bareos $<$ 17.2.0} - Plugin = "python:module_path=/usr/lib64/bareos/plugins/vmware_plugin:module_name=bareos-fd-vmware:... - \end{bconfig} - -to - -.. raw:: latex - - \begin{bconfig}{python:module\_path for Bareos $\geq$ 17.2.0} - Plugin = "python:module_path=/usr/lib64/bareos/plugins:module_name=bareos-fd-vmware:... - \end{bconfig} - -or install the **bareos-vmware-plugin-compat** -package which includes compatibility symbolic links. - -Since -17.2.4: as -the Plugin is using the Virtual Disk Development Kit (VDDK) 6.5, it is -required to pass the thumbprint of the vCenter SSL Certificate, which is -the SHA1 checksum of the SSL Certificate. The thumbprint can be -retrieved like this: - -.. raw:: latex - - \begin{commands}{Example Retrieving vCenter SSL Certificate Thumbprint} - echo -n | openssl s_client -connect vcenter.example.org:443 2>/dev/null | openssl x509 -noout -fingerprint -sha1 - \end{commands} - -The result would look like this: - -.. raw:: latex - - \begin{commands}{Example Result Thumbprint} - SHA1 Fingerprint=CC:81:81:84:A3:CF:53:ED:63:B1:46:EF:97:13:4A:DF:A5:9F:37:89 - \end{commands} - -For additional security, there is a now plugin option -:command:`vcthumbprint`, that can optionally be added. It -must be given without colons like in the following example: - -.. raw:: latex - - \begin{bconfig}{bareos-dir.conf: VMware Plugin Options with vcthumbprint} - ... - Plugin = "python:module_path=/usr/lib64/bareos/plugins:module_name=bareos-fd-vmware:dc=mydc1:folder=/webservers:vmname=websrv1:vcserver=vcenter.example.org:vcuser=bakadm@vsphere.local:vcpass=Bak.Adm-1234:vcthumbprint=56F597FE60521773D073A2ED47CE07282CE6FE9C" - ... - \end{bconfig} - -For ease of use (but less secure) when the -:command:`vcthumbprint` is not given, the plugin will -retrieve the thumbprint. - -Also since -17.2.4 -another optional plugin option has been added that can be used for -trying to force a given transport method. Normally, when no transport -method is given, VDDK will negotiate available transport methods and -select the best one. For a description of transport methods, see - -https://code.vmware.com/doc/preview?id=4076#/doc/vddkDataStruct.5.5.html - -When the plugin runs in a VMware virtual machine which has access to -datastore where the virtual disks to be backed up reside, VDDK will use -the hotadd transport method. On a physical server without SAN access, it -will use the NBD transport method, hotadd transport is not available in -this case. - -To try forcing a given transport method, the plugin option -:command:`transport` can be used, for example - -.. raw:: latex - - \begin{bconfig}{bareos-dir.conf: VMware Plugin options with transport} - ... - Plugin = "python:module_path=/usr/lib64/bareos/plugins:module_name=bareos-fd-vmware:dc=mydc1:folder=/webservers:vmname=websrv1:vcserver=vcenter.example.org:vcuser=bakadm@vsphere.local:vcpass=Bak.Adm-1234:transport=nbdssl" - ... - \end{bconfig} - -Note that the backup will fail when specifying a transport method that -is not available. - -Backup -^^^^^^ - -Before running the first backup, CBT (Changed Block Tracking) must be -enabled for the VMs to be backed up. - -As of http://kb.vmware.com/kb/2075984 manually enabling CBT is currently -not working properly. The API however works properly. To enable CBT use -the Script :command:`vmware_cbt_tool.py`, it is packaged in -the bareos-vmware-plugin package: - -.. raw:: latex - - \begin{commands}{usage of vmware\_cbt\_tool.py} - # vmware_cbt_tool.py --help - usage: vmware_cbt_tool.py [-h] -s HOST [-o PORT] -u USER [-p PASSWORD] -d - DATACENTER -f FOLDER -v VMNAME [--enablecbt] - [--disablecbt] [--resetcbt] [--info] - - Process args for enabling/disabling/resetting CBT - - optional arguments: - -h, --help show this help message and exit - -s HOST, --host HOST Remote host to connect to - -o PORT, --port PORT Port to connect on - -u USER, --user USER User name to use when connecting to host - -p PASSWORD, --password PASSWORD - Password to use when connecting to host - -d DATACENTER, --datacenter DATACENTER - DataCenter Name - -f FOLDER, --folder FOLDER - Folder Name - -v VMNAME, --vmname VMNAME - Names of the Virtual Machines - --enablecbt Enable CBT - --disablecbt Disable CBT - --resetcbt Reset CBT (disable, then enable) - --info Show information (CBT supported and enabled or - disabled) - \end{commands} - -For the above configuration example, the command to enable CBT would be - -.. raw:: latex - - \begin{commands}{Example using vmware\_cbt\_tool.py} - # vmware_cbt_tool.py -s vcenter.example.org -u bakadm@vsphere.local -p Bak.Adm-1234 -d mydc1 -f /webservers -v websrv1 --enablecbt - \end{commands} - -Note: CBT does not work if the virtual hardware version is 6 or earlier. - -After enabling CBT, Backup Jobs can be run or scheduled as usual, for -example in :command:`bconsole`: - -:command:`run job=vm-websrv1 level=Full` - -Restore -^^^^^^^ - -For restore, the VM must be powered off and no snapshot must exist. In -:command:`bconsole` use the restore menu 5, select the -correct FileSet and enter :command:`mark *`, then -:command:` done`. After restore has finished, the VM can -be powered on. - -Restore to local VMDK File -^^^^^^^^^^^^^^^^^^^^^^^^^^ - - -.. index:: - triple: General; VMware Plugin; VMDK files - -Since -15.2.3 -it is possible to restore to local VMDK files. That means, instead of -directly restoring a disk that belongs to the VM, the restore creates -VMDK disk image files on the filesystem of the system that runs the - |bareosFd| . As the VM that the backup was taken from is not -affected by this, it can remain switched on while restoring to local -VMDK. Such a restored VMDK file can then be uploaded to a - |vsphere| datastore or accessed by tools like -http://libguestfs.org/guestfish.1.html -to extract single files. - -For restoring to local VMDK, the plugin option -**localvmdk=yes** must be passed. The following -example shows how to perform such a restore using -:command:`bconsole`: - -.. raw:: latex - - \begin{commands}{Example restore to local VMDK} - *restore - Automatically selected Catalog: MyCatalog - Using Catalog "MyCatalog" - - First you select one or more JobIds that contain files - to be restored. You will be presented several methods - of specifying the JobIds. Then you will be allowed to - select which files from those JobIds are to be restored. - - To select the JobIds, you have the following choices: - 1: List last 20 Jobs run - ... - 5: Select the most recent backup for a client - ... - 13: Cancel - Select item: (1-13): 5 - Automatically selected Client: vmw5-bareos-centos6-64-devel-fd - The defined FileSet resources are: - 1: Catalog - ... - 5: PyTestSetVmware-test02 - 6: PyTestSetVmware-test03 - ... - Select FileSet resource (1-10): 5 - +-------+-------+----------+---------------+---------------------+------------------+ - | jobid | level | jobfiles | jobbytes | starttime | volumename | - +-------+-------+----------+---------------+---------------------+------------------+ - | 625 | F | 4 | 4,733,002,754 | 2016-02-18 10:32:03 | Full-0067 | - ... - You have selected the following JobIds: 625,626,631,632,635 - - Building directory tree for JobId(s) 625,626,631,632,635 ... - 10 files inserted into the tree. - - You are now entering file selection mode where you add (mark) and - remove (unmark) files to be restored. No files are initially added, unless - you used the "all" keyword on the command line. - Enter "done" to leave this mode. - - cwd is: / - $ mark * - 10 files marked. - $ done - Bootstrap records written to /var/lib/bareos/vmw5-bareos-centos6-64-devel-dir.restore.1.bsr - - The job will require the following - Volume(s) Storage(s) SD Device(s) - =========================================================================== - - Full-0001 File FileStorage - ... - Incremental-0078 File FileStorage - - Volumes marked with "*" are online. - - 10 files selected to be restored. - - Using Catalog "MyCatalog" - Run Restore job - JobName: RestoreFiles - Bootstrap: /var/lib/bareos/vmw5-bareos-centos6-64-devel-dir.restore.1.bsr - Where: /tmp/bareos-restores - Replace: Always - FileSet: Linux All - Backup Client: vmw5-bareos-centos6-64-devel-fd - Restore Client: vmw5-bareos-centos6-64-devel-fd - Format: Native - Storage: File - When: 2016-02-25 15:06:48 - Catalog: MyCatalog - Priority: 10 - Plugin Options: *None* - OK to run? (yes/mod/no): mod - Parameters to modify: - 1: Level - ... - 14: Plugin Options - Select parameter to modify (1-14): 14 - Please enter Plugin Options string: python:localvmdk=yes - Run Restore job - JobName: RestoreFiles - Bootstrap: /var/lib/bareos/vmw5-bareos-centos6-64-devel-dir.restore.1.bsr - Where: /tmp/bareos-restores - Replace: Always - FileSet: Linux All - Backup Client: vmw5-bareos-centos6-64-devel-fd - Restore Client: vmw5-bareos-centos6-64-devel-fd - Format: Native - Storage: File - When: 2016-02-25 15:06:48 - Catalog: MyCatalog - Priority: 10 - Plugin Options: python: module_path=/usr/lib64/bareos/plugins:module_name=bareos-fd-vmware: dc=dass5:folder=/: vmname=stephand-test02: vcserver=virtualcenter5.dass-it:vcuser=bakadm@vsphere.local: vcpass=Bak.Adm-1234: localvmdk=yes - OK to run? (yes/mod/no): yes - Job queued. JobId=639 - \end{commands} - -Note: Since Bareos -15.2.3 -it is sufficient to add Python plugin options, e.g. by - -**python:localvmdk=yes** - -Before, all Python plugin must be repeated and the additional be added, -like: -*python:module\_path=/usr/lib64/bareos/plugins:module\_name=bareos-fd-vmware:dc=dass5:folder=/:vmname=stephand-test02:vcserver=virtualcenter5.dass-it:vcuser=bakadm@vsphere.local:vcpass=Bak.Adm-1234:localvmdk=yes* - -After the restore process has finished, the restored VMDK files can be -found under :raw-latex:`\path{/tmp/bareos-restores/}`: - -.. raw:: latex - - \begin{commands}{Example result of restore to local VMDK} - # ls -laR /tmp/bareos-restores - /tmp/bareos-restores: - total 28 - drwxr-x--x. 3 root root 4096 Feb 25 15:47 . - drwxrwxrwt. 17 root root 20480 Feb 25 15:44 .. - drwxr-xr-x. 2 root root 4096 Feb 25 15:19 [ESX5-PS100] stephand-test02 - - /tmp/bareos-restores/[ESX5-PS100] stephand-test02: - total 7898292 - drwxr-xr-x. 2 root root 4096 Feb 25 15:19 . - drwxr-x--x. 3 root root 4096 Feb 25 15:47 .. - -rw-------. 1 root root 2075197440 Feb 25 15:19 stephand-test02_1.vmdk - -rw-------. 1 root root 6012731392 Feb 25 15:19 stephand-test02.vmdk - \end{commands} - -Storage Daemon Plugins ----------------------- - -autoxflate-sd -~~~~~~~~~~~~~ - - -.. index:: - triple: General; Plugin; autoxflate-sd - -This plugin is part of the **bareos-storage** -package. - -The autoxflate-sd plugin can inflate (decompress) and deflate (compress) -the data being written to or read from a device. It can also do both. - -|image| - -Therefore the autoxflate plugin inserts a inflate and a deflate function -block into the stream going to the device (called OUT) and coming from -the device (called IN). - -Each stream passes first the inflate function block, then the deflate -function block. - -The inflate blocks are controlled by the setting of the -Auto Inflate directive. - -The deflate blocks are controlled by the setting of the -Auto Deflate, -Auto Deflate Algorithm -and Auto Deflate Level -directives. - -The inflate blocks, if enabled, will uncompress data if it is compressed -using the algorithm that was used during compression. - -The deflate blocks, if enabled, will compress uncompressed data with the -algorithm and level configured in the according directives. - -The series connection of the inflate and deflate function blocks makes -the plugin very flexible. - -Szenarios where this plugin can be used are for example: - -- client computers with weak cpus can do backups without compression - and let the sd do the compression when writing to disk - -- compressed backups can be recompressed to a different compression - format (e.g. gzip :raw-latex:`\textrightarrow` lzo) using migration - jobs - -- client backups can be compressed with compression algorithms that the - client itself does not support - -Multi-core cpus will be utilized when using parallel jobs as the -compression is done in each jobs’ thread. - -When the autoxflate plugin is configured, it will write some status -information into the joblog. - -.. raw:: latex - - \begin{bmessage}{used compression algorithm} - autodeflation: compressor on device FileStorage is FZ4H - \end{bmessage} - -.. raw:: latex - - \begin{bmessage}{configured inflation and deflation blocks} - autoxflate-sd.c: FileStorage OUT:[SD->inflate=yes->deflate=yes->DEV] IN:[DEV->inflate=yes->deflate=yes->SD] - \end{bmessage} - -.. raw:: latex - - \begin{bmessage}{overall deflation/inflation ratio} - autoxflate-sd.c: deflate ratio: 50.59% - \end{bmessage} - -Additional -Auto XFlate On Replication -can be configured at the Storage resource. - -scsicrypto-sd -~~~~~~~~~~~~~ - - -.. index:: - triple: General; Plugin; scsicrypto-sd - -This plugin is part of the **bareos-storage-tape** -package. - -General -^^^^^^^ - -LTO Hardware Encryption -''''''''''''''''''''''' - -Modern tape-drives, for example LTO (from LTO4 onwards) support hardware -encryption. There are several ways of using encryption with these -drives. The following three types of key management are available for -encrypting drives. The transmission of the keys to the volumes is -accomplished by either of the three: - -- A backup application that supports Application Managed Encryption - (AME) - -- A tape library that supports Library Managed Encryption (LME) - -- A Key Management Appliance (KMA) - -We added support for Application Managed Encryption (AME) scheme, where -on labeling a crypto key is generated for a volume and when the volume -is mounted, the crypto key is loaded. When finally the volume is -unmounted, the key is cleared from the memory of the Tape Drive using -the SCSI SPOUT command set. - -If you have implemented Library Managed Encryption (LME) or a Key -Management Appliance (KMA), there is no need to have support from Bareos -on loading and clearing the encryption keys, as either the Library knows -the per volume encryption keys itself, or it will ask the KMA for the -encryption key when it needs it. For big installations you might -consider using a KMA, but the Application Managed Encryption implemented -in Bareos should also scale rather well and have a low overhead as the -keys are only loaded and cleared when needed. - -The scsicrypto-sd plugin -'''''''''''''''''''''''' - -The :command:`scsicrypto-sd` hooks into the -:raw-latex:`\pluginevent{unload}`, -:raw-latex:`\pluginevent{label read}`, -:raw-latex:`\pluginevent{label write}` and -:raw-latex:`\pluginevent{label verified}` events for loading and -clearing the key. It checks whether it it needs to clear the drive by -either using an internal state (if it loaded a key before) or by -checking the state of a special option that first issues an encrytion -status query. If there is a connection to the director and the volume -information is not available, it will ask the director for the data on -the currently loaded volume. If no connection is available, a cache will -be used which should contain the most recently mounted volumes. If an -encryption key is available, it will be loaded into the drive’s memory. - -Changes in the director -''''''''''''''''''''''' - -The director has been extended with additional code for handling -hardware data encryption. The extra keyword **encrypt** -on the label of a volume will force the director to generate a new -semi-random passphrase for the volume, which will be stored in the -database as part of the media information. - -A passphrase is always stored in the database base64-encoded. When a so -called **Key Encryption Key** is set in the config of -the director, the passphrase is first wrapped using RFC3394 key wrapping -and then base64-encoded. By using key wrapping, the keys in the database -are safe against people sniffing the info, as the data is still -encrypted using the Key Encryption Key (which in essence is just an -extra passphrase of the same length as the volume passphrases used). - -When the storage daemon needs to mount the volume, it will ask the -director for the volume information and that protocol is extended with -the exchange of the base64-wrapped encryption key (passphrase). The -storage daemon provides an extra config option in which it records the -Key Encryption Key of the particular director, and as such can unwrap -the key sent into the original passphrase. - -As can be seen from the above info we don’t allow the user to enter a -passphrase, but generate a semi-random passphrase using the openssl -random functions (if available) and convert that into a readable ASCII -stream of letters, numbers and most other characters, apart from the -quotes and space etc. This will produce much stronger passphrases than -when requesting the info from a user. As we store this information in -the database, the user never has to enter these passphrases. - -The volume label is written in unencrypted form to the volume, so we can -always recognize a Bareos volume. When the key is loaded onto the drive, -we set the decryption mode to mixed, so we can read both unencrypted and -encrypted data from the volume. When no key or the wrong key has been -loaded, the drive will give an IO error when trying to read the volume. -For disaster recovery you can store the Key Encryption Key and the -content of the wrapped encryption keys somewhere safe and the -:ref:`bscrypto bscrypto` tool together with the -scsicrypto-sd plugin can be used to get access to your volumes, in case -you ever lose your complete environment. - -If you don’t want to use the scsicrypto-sd plugin when doing DR and you -are only reading one volume, you can also set the crypto key using the -bscrypto tool. Because we use the mixed decryption mode, in which you -can read both encrypted and unencrypted data from a volume, you can set -the right encryption key before reading the volume label. - -If you need to read more than one volume, you better use the -scsicrypto-sd plugin with tools like bscan/bextract, as the plugin will -then auto-load the correct encryption key when it loads the volume, -similiarly to what the storage daemon does when performing backups and -restores. - -The volume label is unencrypted, so a volume can also be recognized by a -non-encrypted installation, but it won’t be able to read the actual data -from it. Using an encrypted volume label doesn’t add much security -(there is no security-related info in the volume label anyhow) and it -makes it harder to recognize either a labeled volume with encrypted data -or an unlabeled new volume (both would return an IO-error on read of the -label.) - -Configuration -^^^^^^^^^^^^^ - -SCSI crypto setup -''''''''''''''''' - -The initial setup of SCSI crypto looks something like this: - -- Generate a Key Encryption Key e.g. - - .. raw:: latex - - \begin{commands}{} - bscrypto -g - - \end{commands} - -For details see :ref:`bscrypto bscrypto`. - -Security Setup -'''''''''''''' - -Some security levels need to be increased for the storage daemon to be -able to use the low level SCSI interface for setting and getting the -encryption status on a tape device. - -The following additional security is needed for the following operating -systems: - -Linux (SG\_IO ioctl interface): - - -The user running the storage daemon needs the following additional -capabilities: .. index:: SD; Platform!Linux!Privileges - -- **CAP_SYS_RAWIO** (see capabilities(7)) - - - On older kernels you might need - **CAP_SYS_ADMIN**. Try - **CAP_SYS_RAWIO** first and if that doesn’t - work try **CAP_SYS_ADMIN** - -- If you are running the storage daemon as another user than root - (which has the **CAP_SYS_RAWIO** capability), - you need to add it to the current set of capabilities. - -- If you are using systemd, you could add this additional capability to - the CapabilityBoundingSet parameter. - - - For systemd add the following to the bareos-sd.service: - **Capabilities=cap_sys_rawio+ep** - -You can also set up the extra capability on -:command:`bscrypto}` and :raw-latex:`\command{bareos-sd` by -running the following commands: - -.. raw:: latex - - \begin{commands}{} - setcap cap_sys_rawio=ep bscrypto - setcap cap_sys_rawio=ep bareos-sd - \end{commands} - -Check the setting with - -.. raw:: latex - - \begin{commands}{} - getcap -v bscrypto - getcap -v bareos-sd - \end{commands} - -:command:`getcap}` and :raw-latex:`\command{setcap` are part -of libcap-progs. - -If :command:`bareos-sd` does not have the appropriate -capabilities, all other tape operations may still work correctly, but -you will get :raw-latex:`\bquote{Unable to perform SG\_IO ioctl}` -errors. - -Solaris (USCSI ioctl interface): - - -The user running the storage daemon needs the following additional -privileges: .. index:: SD; Platform!Solaris!Privileges - -- **PRIV_SYS_DEVICES** (see privileges(5)) - -If you are running the storage daemon as another user than root (which -has the **PRIV_SYS_DEVICES** privilege), you need -to add it to the current set of privileges. This can be set up by -setting this either as a project for the user, or as a set of extra -privileges in the SMF definition starting the storage daemon. The SMF -setup is the cleanest one. - -For SMF make sure you have something like this in the instance block: - -.. raw:: latex - - \begin{bconfig}{} - - \end{bconfig} - -Changes in bareos-sd.conf -''''''''''''''''''''''''' - -- Set the Key Encryption Key - - - Key Encryption Key - = **passphrase** - -- Enable the loading of storage daemon plugins - - - Plugin Directory - = *path_to_sd_plugins* - -- Enable the SCSI encryption option - - - Drive Crypto Enabled - = yes - -- Enable this, if you want the plugin to probe the encryption status of - the drive when it needs to clear a pending key - - - Query Crypto Status - = yes - -Changes in bareos-dir.conf -'''''''''''''''''''''''''' - -- Set the Key Encryption Key - - - Key Encryption Key - = **passphrase** - -Testing -^^^^^^^ - -Restart the Storage Daemon and the Director. After this you can label -new volumes with the encrypt option, e.g. - -.. raw:: latex - - \begin{bconfig}{} - label slots=1-5 barcodes encrypt - \end{bconfig} - -Disaster Recovery -^^^^^^^^^^^^^^^^^ - -For Disaster Recovery (DR) you need the following information: - -- Actual bareos-sd.conf with config options enabled as described above, - including, among others, a definition of a director with the Key - Encryption Key used for creating the encryption keys of the volumes. - -- The actual keys used for the encryption of the volumes. - -This data needs to be availabe as a so called crypto cache file which is -used by the plugin when no connection to the director can be made to do -a lookup (most likely on DR). - -Most of the times the needed information, e.g. the bootstrap info, is -available on recently written volumes and most of the time the -encryption cache will contain the most recent data, so a recent copy of -the *bareos-sd..cryptoc* file in the working -directory is enough most of the time. You can also save the info from -database in a safe place and use bscrypto to populate this info -(VolumeName :raw-latex:`\textrightarrow`EncryptKey) into the crypto -cache file used by :command:`bextract` and -:command:`bscan`. You can use -:command:`bscrypto` with the following flags to create a new -or update an existing crypto cache file e.g.: - -.. raw:: latex - - \begin{commands}{} - bscrypto -p /var/lib/bareos/bareos-sd..cryptoc - \end{commands} - -- A valid BSR file containing the location of the last safe of the - database makes recovery much easier. Adding a post script to the - database save job could collect the needed info and make sure its - stored somewhere safe. - -- Recover the database in the normal way e.g. for postgresql: - - .. raw:: latex - - \begin{commands}{} - bextract -D -c bareos-sd.conf -V \ /dev/nst0 /tmp -b bootstrap.bsr - /usr/lib64/bareos/create_bareos_database - /usr/lib64/bareos/grant_bareos_privileges - psql bareos < /tmp/var/lib/bareos/bareos.sql - \end{commands} - -Or something similar (change paths to follow where you installed the -software or where the package put it). - -**Note:** As described at the beginning of this chapter, there are -different types of key management, AME, LME and KMA. If the Library is -set up for LME or KMA, it probably won’t allow our AME setup and the -scsi-crypto plugin will fail to set/clear the encryption key. To be able -to use AME you need to :raw-latex:`\bquote{Modify Encryption Method}` -and set it to something like :raw-latex:`\bquote{Application Managed}`. -If you decide to use LME or KMA you don’t have to bother with the whole -setup of AME which may for big libraries be easier, although the -overhead of using AME even for very big libraries should be minimal. - -scsitapealert-sd -~~~~~~~~~~~~~~~~ - - -.. index:: - triple: General; Plugin; scsitapealert-sd - -This plugin is part of the **bareos-storage-tape** -package. - -python-sd Plugin -~~~~~~~~~~~~~~~~ - - -.. index:: - triple: General; Plugin!Python; Storage Daemon - -The **python-sd** plugin behaves similar to the -:ref:`director-python-plugin`. - -Director Plugins ----------------- - -python-dir Plugin -~~~~~~~~~~~~~~~~~ - - -.. index:: - triple: General; Plugin!Python; Director - -The **python-dir** plugin is intended to extend the -functionality of the Bareos Director by Python code. A working example -is included. - -- install the **bareos-director-python-plugin** - package - -- change to the Bareos plugin directory - (*/usr/lib/bareos/plugins/* or - */usr/lib64/bareos/plugins/*) - -- copy *bareos-dir.py.template* to - *bareos-dir.py* - -- activate the plugin in the Bareos Director configuration - -- restart the Bareos Director - -- change *bareos-dir.py* as required - -- restart the Bareos Director - -Loading plugins -^^^^^^^^^^^^^^^ - -Since 14.4.0 -multiple Python plugins can be loaded and plugin names can be arbitrary. -Before this, the Python plugin always loads the file -*bareos-dir.py*. - -The director plugins are configured in the Job-Resource (or JobDefs -resource). To load a Python plugin you need - -- pointing to your plugin directory (needs to be enabled in the - Director resource, too - -- Your plugin (without the suffix .py) - -- default is ’0’, you can leave this, as long as you only have 1 - Director Python plugin. If you have more than 1, start with - instance=0 and increment the instance for each plugin. - -- You can add plugin specific option key-value pairs, each pair - separated by ’:’ key=value - -Example: - -.. raw:: latex - - \begin{bconfig}{bareos-dir.conf: Python Plugins} - Director { - # ... - # Plugin directory - Plugin Directory = /usr/lib64/bareos/plugins - # Load the python plugin - Plugin Names = "python" - } - - JobDefs { - Name = "DefaultJob" - Type = Backup - # ... - # Load the class based plugin with testoption=testparam - Dir Plugin Options = "python:instance=0:module_path=/usr/lib64/bareos/plugins:module_name=bareos-dir-class-plugins:testoption=testparam - # ... - } - \end{bconfig} - -Write your own Python Plugin -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Some plugin examples are available on -https://github.com/bareos/bareos-contrib. The class-based approach lets -you easily reuse stuff already defined in the baseclass -BareosDirPluginBaseclass, which ships with the -**bareos-director-python-plugin** package. The -examples contain the plugin bareos-dir-nsca-sender, that submits the -results and performance data of a backup job directly to -Icinga.. index:: General; Icinga or -Nagios.. index:: General; Nagios|see{Icinga} using the NSCA -protocol. - -.. |image| image:: \idir autoxflate-functionblocks - :width: 80.0% diff --git a/docs/manuals/en/new_main_reference/source/pools.rst b/docs/manuals/en/new_main_reference/source/pools.rst index b4422b7632a..1ba1f0c0dcc 100644 --- a/docs/manuals/en/new_main_reference/source/pools.rst +++ b/docs/manuals/en/new_main_reference/source/pools.rst @@ -1,14 +1,12 @@ +.. _PoolsChapter: + Automated Disk Backup ===================== - -.. index:: - triple: General; Volumes; Using Pools to Manage - -.. index:: - triple: General; Disk; Automated Backup -.. index:: General; Automated Disk Backup -.. index:: General; Pool +:raw-latex:`\index[general]{Volumes!Using Pools to Manage}` +:raw-latex:`\index[general]{Disk!Automated Backup}` +:raw-latex:`\index[general]{Automated Disk Backup}` +:raw-latex:`\index[general]{Pool}` If you manage five or ten machines and have a nice tape backup, you don’t need Pools, and you may wonder what they are good for. In this @@ -40,6 +38,8 @@ The rest of this chapter will explain how to setup Bareos so that it would automatically manage a set of disk files with the minimum sysadmin intervention. +.. _OverallDesign: + Overall Design -------------- @@ -66,7 +66,9 @@ backup, so if you have multiple clients you will need to multiply those numbers by the number of clients, or use a different system for switching volumes, such as limiting the volume size. -:raw-latex:`\TODO{This chapter will get rewritten. Instead of limiting a Volume to one job, we will utilize \variable{Max Use Duration = 24 hours}. This prevents problems when adding more clients, because otherwise each job has to run seperat.}` +.. raw:: latex + + \TODO{This chapter will get rewritten. Instead of limiting a Volume to one job, we will utilize \variable{Max Use Duration = 24 hours}. This prevents problems when adding more clients, because otherwise each job has to run seperat.} The next problem to resolve is recycling of Volumes. As you noted from above, the requirements are to be able to restore monthly for 6 months, @@ -82,34 +84,31 @@ Differential saves, and one for Incremental saves, and each would have a different number of volumes and a different Retention period to accomplish the requirements. -.. _FullPool: +:raw-latex:`\label{FullPool}` Full Pool ~~~~~~~~~ - -.. index:: - triple: General; Pool; Full -.. index:: General; Full Pool +:raw-latex:`\index[general]{Pool!Full}` +:raw-latex:`\index[general]{Full Pool}` Putting a single Full backup on each Volume, will require six Full save Volumes, and a retention period of six months. The Pool needed to do that is: -.. raw:: latex +:: - \begin{bconfig}{Full-Pool} - Pool { - Name = Full-Pool - Pool Type = Backup - Recycle = yes - AutoPrune = yes - Volume Retention = 6 months - Maximum Volume Jobs = 1 - Label Format = Full- - Maximum Volumes = 9 - } - \end{bconfig} + {Full-Pool} + Pool { + Name = Full-Pool + Pool Type = Backup + Recycle = yes + AutoPrune = yes + Volume Retention = 6 months + Maximum Volume Jobs = 1 + Label Format = Full- + Maximum Volumes = 9 + } Since these are disk Volumes, no space is lost by having separate Volumes for each backup (done once a month in this case). The items to @@ -128,34 +127,31 @@ If you have two clients, you would want to set **Maximum Volume Jobs** to 2 instead of one, or set a limit on the size of the Volumes, and possibly increase the maximum number of Volumes. -.. _DiffPool: +:raw-latex:`\label{DiffPool}` Differential Pool ~~~~~~~~~~~~~~~~~ - -.. index:: - triple: General; Pool; Differential -.. index:: General; Differential Pool +:raw-latex:`\index[general]{Pool!Differential}` +:raw-latex:`\index[general]{Differential Pool}` For the Differential backup Pool, we choose a retention period of a bit longer than a month and ensure that there is at least one Volume for each of the maximum of five weeks in a month. So the following works: -.. raw:: latex +:: - \begin{bconfig}{Differential Pool} - Pool { - Name = Diff-Pool - Pool Type = Backup - Recycle = yes - AutoPrune = yes - Volume Retention = 40 days - Maximum Volume Jobs = 1 - Label Format = Diff- - Maximum Volumes = 10 - } - \end{bconfig} + {Differential Pool} + Pool { + Name = Diff-Pool + Pool Type = Backup + Recycle = yes + AutoPrune = yes + Volume Retention = 40 days + Maximum Volume Jobs = 1 + Label Format = Diff- + Maximum Volumes = 10 + } As you can see, the Differential Pool can grow to a maximum of 9 volumes, and the Volumes are retained 40 days and thereafter they can be @@ -170,32 +166,29 @@ and recycled. See the discussion above concering the Full pool for how to handle multiple clients. -.. _IncPool: +:raw-latex:`\label{IncPool}` Incremental Pool ~~~~~~~~~~~~~~~~ -.. index:: General; Incremental Pool - -.. index:: - triple: General; Pool; Incremental +:raw-latex:`\index[general]{Incremental Pool}` +:raw-latex:`\index[general]{Pool!Incremental}` Finally, here is the resource for the Incremental Pool: -.. raw:: latex +:: - \begin{bconfig}{Incremental Pool} - Pool { - Name = Inc-Pool - Pool Type = Backup - Recycle = yes - AutoPrune = yes - Volume Retention = 20 days - Maximum Volume Jobs = 6 - Label Format = Inc- - Maximum Volumes = 7 - } - \end{bconfig} + {Incremental Pool} + Pool { + Name = Inc-Pool + Pool Type = Backup + Recycle = yes + AutoPrune = yes + Volume Retention = 20 days + Maximum Volume Jobs = 6 + Label Format = Inc- + Maximum Volumes = 7 + } We keep the data for 20 days rather than just a week as the needs require. To reduce the proliferation of volume names, we keep a week’s @@ -221,218 +214,216 @@ minor modifications to simplify things. The Director’s configuration file is as follows: -.. raw:: latex - - \begin{bconfig}{bareos-dir.conf} - Director { # define myself - Name = bareos-dir - QueryFile = "/usr/lib/bareos/scripts/query.sql" - Maximum Concurrent Jobs = 1 - Password = "*** CHANGE ME ***" - Messages = Standard - } - - JobDefs { - Name = "DefaultJob" - Type = Backup - Level = Incremental - Client = bareos-fd - FileSet = "Full Set" - Schedule = "WeeklyCycle" - Storage = File - Messages = Standard - Pool = Inc-Pool - Full Backup Pool = Full-Pool - Incremental Backup Pool = Inc-Pool - Differential Backup Pool = Diff-Pool - Priority = 10 - Write Bootstrap = "/var/lib/bareos/%c.bsr" - } - - Job { - Name = client - Client = client-fd - JobDefs = "DefaultJob" - FileSet = "Full Set" - } - - # Backup the catalog database (after the nightly save) - Job { - Name = "BackupCatalog" - Client = client-fd - JobDefs = "DefaultJob" - Level = Full - FileSet="Catalog" - Schedule = "WeeklyCycleAfterBackup" - # This creates an ASCII copy of the catalog - # Arguments to make_catalog_backup.pl are: - # make_catalog_backup.pl - RunBeforeJob = "/usr/lib/bareos/scripts/make_catalog_backup.pl MyCatalog" - # This deletes the copy of the catalog - RunAfterJob = "/usr/lib/bareos/scripts/delete_catalog_backup" - # This sends the bootstrap via mail for disaster recovery. - # Should be sent to another system, please change recipient accordingly - Write Bootstrap = "|/usr/sbin/bsmtp -h localhost -f \"\(Bareos\) \" -s \"Bootstrap for Job %j\" root@localhost" - Priority = 11 # run after main backup - } - - # Standard Restore template, to be changed by Console program - Job { - Name = "RestoreFiles" - Type = Restore - Client = client-fd - FileSet="Full Set" - Storage = File - Messages = Standard - Pool = Default - Where = /tmp/bareos-restores - } - - # List of files to be backed up - FileSet { - Name = "Full Set" - Include = { - Options { - signature=SHA1; - compression=GZIP9 - } - File = / - File = /usr - File = /home - File = /boot - File = /var - File = /opt - } - Exclude = { - File = /proc - File = /tmp - File = /.journal - File = /.fsck - ... - } - } - - Schedule { - Name = "WeeklyCycle" - Run = Level=Full 1st sun at 2:05 - Run = Level=Differential 2nd-5th sun at 2:05 - Run = Level=Incremental mon-sat at 2:05 - } - - # This schedule does the catalog. It starts after the WeeklyCycle - Schedule { - Name = "WeeklyCycleAfterBackup" - Run = Level=Full sun-sat at 2:10 - } - - # This is the backup of the catalog - FileSet { - Name = "Catalog" - Include { - Options { - signature = MD5 - } - File = "/var/lib/bareos/bareos.sql" # database dump - File = "/etc/bareos" # configuration - } - } - - Client { - Name = client-fd - Address = client - FDPort = 9102 - Password = " *** CHANGE ME ***" - AutoPrune = yes # Prune expired Jobs/Files - Job Retention = 6 months - File Retention = 60 days - } - - Storage { - Name = File - Address = localhost - Password = " *** CHANGE ME ***" - Device = FileStorage - Media Type = File - } - - Catalog { - Name = MyCatalog - dbname = bareos; user = bareos; password = "" - } - - Pool { - Name = Full-Pool - Pool Type = Backup - Recycle = yes # automatically recycle Volumes - AutoPrune = yes # Prune expired volumes - Volume Retention = 6 months - Maximum Volume Jobs = 1 - Label Format = Full- - Maximum Volumes = 9 - } - - Pool { - Name = Inc-Pool - Pool Type = Backup - Recycle = yes # automatically recycle Volumes - AutoPrune = yes # Prune expired volumes - Volume Retention = 20 days - Maximum Volume Jobs = 6 - Label Format = Inc- - Maximum Volumes = 7 - } - - Pool { - Name = Diff-Pool - Pool Type = Backup - Recycle = yes - AutoPrune = yes - Volume Retention = 40 days - Maximum Volume Jobs = 1 - Label Format = Diff- - Maximum Volumes = 10 - } - - Messages { - Name = Standard - mailcommand = "bsmtp -h mail.domain.com -f \"\(Bareos\) %r\" - -s \"Bareos: %t %e of %c %l\" %r" - operatorcommand = "bsmtp -h mail.domain.com -f \"\(Bareos\) %r\" - -s \"Bareos: Intervention needed for %j\" %r" - mail = root@domain.com = all, !skipped - operator = root@domain.com = mount - console = all, !skipped, !saved - append = "/home/bareos/bin/log" = all, !skipped - } - \end{bconfig} +:: + + {bareos-dir.conf} + Director { # define myself + Name = bareos-dir + QueryFile = "/usr/lib/bareos/scripts/query.sql" + Maximum Concurrent Jobs = 1 + Password = "*** CHANGE ME ***" + Messages = Standard + } + + JobDefs { + Name = "DefaultJob" + Type = Backup + Level = Incremental + Client = bareos-fd + FileSet = "Full Set" + Schedule = "WeeklyCycle" + Storage = File + Messages = Standard + Pool = Inc-Pool + Full Backup Pool = Full-Pool + Incremental Backup Pool = Inc-Pool + Differential Backup Pool = Diff-Pool + Priority = 10 + Write Bootstrap = "/var/lib/bareos/%c.bsr" + } + + Job { + Name = client + Client = client-fd + JobDefs = "DefaultJob" + FileSet = "Full Set" + } + + # Backup the catalog database (after the nightly save) + Job { + Name = "BackupCatalog" + Client = client-fd + JobDefs = "DefaultJob" + Level = Full + FileSet="Catalog" + Schedule = "WeeklyCycleAfterBackup" + # This creates an ASCII copy of the catalog + # Arguments to make_catalog_backup.pl are: + # make_catalog_backup.pl + RunBeforeJob = "/usr/lib/bareos/scripts/make_catalog_backup.pl MyCatalog" + # This deletes the copy of the catalog + RunAfterJob = "/usr/lib/bareos/scripts/delete_catalog_backup" + # This sends the bootstrap via mail for disaster recovery. + # Should be sent to another system, please change recipient accordingly + Write Bootstrap = "|/usr/sbin/bsmtp -h localhost -f \"\(Bareos\) \" -s \"Bootstrap for Job %j\" root@localhost" + Priority = 11 # run after main backup + } + + # Standard Restore template, to be changed by Console program + Job { + Name = "RestoreFiles" + Type = Restore + Client = client-fd + FileSet="Full Set" + Storage = File + Messages = Standard + Pool = Default + Where = /tmp/bareos-restores + } + + # List of files to be backed up + FileSet { + Name = "Full Set" + Include = { + Options { + signature=SHA1; + compression=GZIP9 + } + File = / + File = /usr + File = /home + File = /boot + File = /var + File = /opt + } + Exclude = { + File = /proc + File = /tmp + File = /.journal + File = /.fsck + ... + } + } + + Schedule { + Name = "WeeklyCycle" + Run = Level=Full 1st sun at 2:05 + Run = Level=Differential 2nd-5th sun at 2:05 + Run = Level=Incremental mon-sat at 2:05 + } + + # This schedule does the catalog. It starts after the WeeklyCycle + Schedule { + Name = "WeeklyCycleAfterBackup" + Run = Level=Full sun-sat at 2:10 + } + + # This is the backup of the catalog + FileSet { + Name = "Catalog" + Include { + Options { + signature = MD5 + } + File = "/var/lib/bareos/bareos.sql" # database dump + File = "/etc/bareos" # configuration + } + } + + Client { + Name = client-fd + Address = client + FDPort = 9102 + Password = " *** CHANGE ME ***" + AutoPrune = yes # Prune expired Jobs/Files + Job Retention = 6 months + File Retention = 60 days + } + + Storage { + Name = File + Address = localhost + Password = " *** CHANGE ME ***" + Device = FileStorage + Media Type = File + } + + Catalog { + Name = MyCatalog + dbname = bareos; user = bareos; password = "" + } + + Pool { + Name = Full-Pool + Pool Type = Backup + Recycle = yes # automatically recycle Volumes + AutoPrune = yes # Prune expired volumes + Volume Retention = 6 months + Maximum Volume Jobs = 1 + Label Format = Full- + Maximum Volumes = 9 + } + + Pool { + Name = Inc-Pool + Pool Type = Backup + Recycle = yes # automatically recycle Volumes + AutoPrune = yes # Prune expired volumes + Volume Retention = 20 days + Maximum Volume Jobs = 6 + Label Format = Inc- + Maximum Volumes = 7 + } + + Pool { + Name = Diff-Pool + Pool Type = Backup + Recycle = yes + AutoPrune = yes + Volume Retention = 40 days + Maximum Volume Jobs = 1 + Label Format = Diff- + Maximum Volumes = 10 + } + + Messages { + Name = Standard + mailcommand = "bsmtp -h mail.domain.com -f \"\(Bareos\) %r\" + -s \"Bareos: %t %e of %c %l\" %r" + operatorcommand = "bsmtp -h mail.domain.com -f \"\(Bareos\) %r\" + -s \"Bareos: Intervention needed for %j\" %r" + mail = root@domain.com = all, !skipped + operator = root@domain.com = mount + console = all, !skipped, !saved + append = "/home/bareos/bin/log" = all, !skipped + } and the Storage daemon’s configuration file is: -.. raw:: latex - - \begin{bconfig}{bareos-sd.conf} - Storage { # definition of myself - Name = bareos-sd - } - - Director { - Name = bareos-dir - Password = " *** CHANGE ME ***" - } - - Device { - Name = FileStorage - Media Type = File - Archive Device = /var/lib/bareos/storage - LabelMedia = yes; # lets Bareos label unlabeled media - Random Access = yes; - AutomaticMount = yes; # when device opened, read it - RemovableMedia = no; - AlwaysOpen = no; - } - - Messages { - Name = Standard - director = bareos-dir = all - } - \end{bconfig} +:: + + {bareos-sd.conf} + Storage { # definition of myself + Name = bareos-sd + } + + Director { + Name = bareos-dir + Password = " *** CHANGE ME ***" + } + + Device { + Name = FileStorage + Media Type = File + Archive Device = /var/lib/bareos/storage + LabelMedia = yes; # lets Bareos label unlabeled media + Random Access = yes; + AutomaticMount = yes; # when device opened, read it + RemovableMedia = no; + AlwaysOpen = no; + } + + Messages { + Name = Standard + director = bareos-dir = all + } diff --git a/docs/manuals/en/new_main_reference/source/programs.rst b/docs/manuals/en/new_main_reference/source/programs.rst index d5dab9d0575..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/programs.rst +++ b/docs/manuals/en/new_main_reference/source/programs.rst @@ -1,1877 +1 @@ -Bareos Programs -=============== -Bareos Daemons --------------- - -Daemon Command Line Options -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -.. index:: - triple: General; Daemon; Command Line Options - -.. index:: - triple: General; Command Line Options; Daemon - -Each of the three daemons (Director, File, Storage) accepts a small set -of options on the command line. In general, each of the daemons as well -as the Console program accepts the following options: - --c - Define the file or directory to use for the configuration. See - :ref:`sec:ConfigurationPathLayout`. - --d nnn - Set the debug level to **nnn**. Generally anything between 50 and - 200 is reasonable. The higher the number, the more output is - produced. The output is written to standard output. The debug level - can also be set during runtime, see section - :ref:`bconsole: setdebug bcommandSetdebug`. - --f - Run the daemon in the foreground. This option is needed to run the - daemon under the debugger. - --g - Run the daemon under this group. This must be a group name, not a - GID. - --s - Do not trap signals. This option is needed to run the daemon under - the debugger. - --t - Read the configuration file and print any error messages, then - immediately exit. Useful for syntax testing of new configuration - files. - --u - Run the daemon as this user. This must be a user name, not a UID. - --v - Be more verbose or more complete in printing error and informational - messages. - --xc - Print the current configuration and exit. - --xs - Print configuration schema in JSON format and exit. - --? - Print the version and list of options. - -bareos-dir -~~~~~~~~~~ - - -.. index:: - triple: General; Command; bareos-dir -:raw-latex:`\index[dir]{Command Line Options}` - - |bareosDir| . - -bareos-sd -~~~~~~~~~ - - -.. index:: - triple: General; Command; bareos-sd -.. index:: SD; Command Line Options - - |bareosSd| . - -bareos-fd -~~~~~~~~~ - - -.. index:: - triple: General; Command; bareos-fd -:raw-latex:`\index[fd]{Command Line Options}` - - |bareosFd| . - -Interactive Programs --------------------- - -bconsole -~~~~~~~~ - -There is an own chapter on :command:`bconsole`. Please refer -to chapter :ref:`sec:bconsole`. - -bareos-webui -~~~~~~~~~~~~ - -For further information regarding the Bareos Webui, please refer to -:ref:`sec:webui`. - -bat -~~~ - - -.. index:: - triple: General; Command; bat}` :raw-latex:`\label{bat - -The Bacula/Bareos Administration Tool (:command:`bat`) has -been a native GUI for Bareos. It has been marked deprecated since -15.2.0. Since -Bareos -17.2.0 -it is no longer part of Bareos. We encourage the use of - |bareosWebui| instead. - -Volume Utility Commands ------------------------ - -.. index:: General; Volume Utility Tools - -.. index:: - triple: General; Tools; Volume Utility -.. _sec:VolumeUtilityCommands: - -This document describes the utility programs written to aid Bareos users -and developers in dealing with Volumes external to Bareos and to perform -other useful tasks. - -Parameter -~~~~~~~~~ - -Specifying the Configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Each of the utilities that deal with Volumes require a valid - |bareosSd| configuration (actually, the only part of the -configuration file that these programs need is the -:raw-latex:`\resourcetype{Sd}{Device}` resource definitions). This -permits the programs to find the configuration parameters for your -Archive Device. Using -the **-c** option a custom - |bareosSd| configuration file or directory can be selected. - -Specifying a Device -^^^^^^^^^^^^^^^^^^^ - -Each of these programs require a **device-name** -where the Volume can be found. The device-name is either the name of the - |bareosSd| device -(Name) or its -Archive Device. - -Specifying a Device Name For a Tape -''''''''''''''''''''''''''''''''''' - -In the case of a tape, this is the physical device name such as -**/dev/nst0** or **/dev/rmt/0ubn** depending on your system. - -:raw-latex:`\warning{If you have Bareos running and you want to use -one of these programs, you will either need to stop the \bareosSd -or \bcommand{unmount}{} any tape drive you want to use, -otherwise the drive may get busy because Bareos is using it. -After this, you can use the command \command{mtx} or \ilink{mtx-changer script}{sec:MtxChangerManualUsage} -to load the required volume into the tape drive. -}` - -Specifying a Device Name For a File -''''''''''''''''''''''''''''''''''' - -If you are attempting to read or write an archive file rather than a -tape, the **device-name** can be the full path to -the archive location specified at -Archive Device or this -including the filename of the volume. The filename (last part of the -specification) will be stripped and used as the Volume name So, the path -is equivalent to the -Archive Device and the -filename is equivalent to the volume name. - -Specifying Volumes -^^^^^^^^^^^^^^^^^^ - - -.. index:: - triple: General; Volumes; Specifying -.. index:: General; Bootstrap - -Often you must specify the Volume name to the programs below. The best -method to do so is to specify a bootstrap file on the command line with -the **-b** option. As part of the bootstrap file, -you will then specify the Volume name or Volume names if more than one -volume is needed. For example, suppose you want to read tapes -:raw-latex:`\volume{tapevolume1}` and :raw-latex:`\volume{tapevolume2}`. -First construct a **bootstrap** file named say, -*list.bsr* which contains: - - - -:: - - Volume=tapevolume1|tapevolume2 - - - -where each Volume is separated by a vertical bar. Then simply use: - -.. raw:: latex - - \begin{commands}{} - bls -b list.bsr /dev/nst0 - \end{commands} - -In the case of Bareos Volumes that are on files, you may simply append -volumes as follows: - -.. raw:: latex - - \begin{commands}{} - bls /var/lib/bareos/storage/volume1\|volume2 - \end{commands} - -where the backslash (\\) was necessary as a shell escape to permit -entering the vertical bar ( \| ). - -And finally, if you feel that specifying a Volume name is a bit -complicated with a bootstrap file, you can use the -**-V** option (on all programs except -:command:`bcopy`) to specify one or more Volume names -separated by the vertical bar ( \| ). For example: - -.. raw:: latex - - \begin{commands}{} - bls /dev/nst0 -V tapevolume1 - \end{commands} - -You may also specify an asterisk (\*) to indicate that the program -should accept any volume. For example: - -.. raw:: latex - - \begin{commands}{} - bls /dev/nst0 -V* - \end{commands} - -If your |bareosSd| has following resource, - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-sd}{device}{FileStorage} - Device { - Name = FileStorage - Archive Device = /var/lib/bareos/storage - ... - } - \end{bareosConfigResource} - -following calls of :command:`bls` should behave identical: - -.. raw:: latex - - \begin{commands}{bls using Storage Device Name} - bls FileStorage -V Full1 - \end{commands} - -or - -.. raw:: latex - - \begin{commands}{bls using the Archive Device of a Storage Device} - bls /var/lib/bareos/storage -V Full1 - \end{commands} - -or - -.. raw:: latex - - \begin{commands}{bls using the Archive Device of a Storage Device and volume name} - bls /var/lib/bareos/storage/Full1 - \end{commands} - -Specifying Maximum Block Size -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you use Bareos with non-default block sizes defined in the pools -(Maximum Block Size), it -might be necessary to specify the -Maximum Block Size also -in the storage device resource, see -:ref:`Direct access to Volumes with non-default blocksizes direct-access-to-volumes-with-non-default-blocksizes`. - -bls -~~~ - -.. index:: General; bls - -.. index:: - triple: General; Command; bls - -:command:`bls` can be used to do an -:command:`ls` type listing of a Bareos tape or file. It is -called: - -.. raw:: latex - - \begin{commands}{} - Usage: bls [options] - -b specify a bootstrap file - -c specify a Storage configuration file - -D specify a director name specified in the Storage - configuration file for the Key Encryption Key selection - -d set debug level to - -dt print timestamp in debug output - -e exclude list - -i include list - -j list jobs - -k list blocks - (no j or k option) list saved files - -L dump label - -p proceed inspite of errors - -v be verbose - -V specify Volume names (separated by |) - -? print this message - \end{commands} - -Normally if no options are specified, :command:`bls` will -produce the equivalent output to the :command:`ls -l` -command for each volume. - -For example, to list the contents of a tape: - -.. raw:: latex - - \begin{commands}{} - bls -V Volume-name /dev/nst0 - \end{commands} - -Or to list the contents of a volume file: - -.. raw:: latex - - \begin{commands}{} - bls FileStorage -V Full1 - \end{commands} - -or - -.. raw:: latex - - \begin{commands}{} - bls /var/lib/bareos/storage -V Full1 - \end{commands} - -or - -.. raw:: latex - - \begin{commands}{} - bls /var/lib/bareos/storage/Full1 - \end{commands} - -For example: - -.. raw:: latex - - \begin{commands}{} - bls FileStorage -V Full1 - bls: butil.c:282-0 Using device: "/var/lib/bareos/storage" for reading. - 12-Sep 18:30 bls JobId 0: Ready to read from volume "Full1" on device "FileStorage" (/var/lib/bareos/storage). - bls JobId 1: -rwxr-xr-x 1 root root 4614 2013-01-22 22:24:11 /usr/sbin/service - bls JobId 1: -rwxr-xr-x 1 root root 13992 2013-01-22 22:24:12 /usr/sbin/rtcwake - bls JobId 1: -rwxr-xr-x 1 root root 6243 2013-02-06 11:01:29 /usr/sbin/update-fonts-scale - bls JobId 1: -rwxr-xr-x 1 root root 43240 2013-01-22 22:24:10 /usr/sbin/grpck - bls JobId 1: -rwxr-xr-x 1 root root 16894 2013-01-22 22:24:11 /usr/sbin/update-rc.d - bls JobId 1: -rwxr-xr-x 1 root root 9480 2013-01-22 22:47:43 /usr/sbin/gss_clnt_send_err - ... - bls JobId 456: -rw-r----- 1 root bareos 1008 2013-05-23 13:17:45 /etc/bareos/bareos-fd.conf - bls JobId 456: drwxr-xr-x 2 root root 4096 2013-07-04 17:40:21 /etc/bareos/ - 12-Sep 18:30 bls JobId 0: End of Volume at file 0 on device "FileStorage" (/var/lib/bareos/storage), Volume "Full1" - 12-Sep 18:30 bls JobId 0: End of all volumes. - 2972 files found. - \end{commands} - -Show Detailed File Information -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To retrieve information, about how a file is stored on the volume, you -can use :command:`bls` in verbose mode: - -.. raw:: latex - - \begin{commands}{} - bls FileStorage -V TestVolume001 -v - bls: butil.c:273-0 Using device: "FileStorage" for reading. - 22-Jun 19:34 bls JobId 0: Ready to read from volume "TestVolume001" on device "Storage1" (/var/lib/bareos/storage). - Volume Label Record: VolSessionId=1 VolSessionTime=1498152622 JobId=0 DataLen=168 - Begin Job Session Record: VolSessionId=1 VolSessionTime=1498152622 JobId=1 DataLen=169 - FileIndex=1 Stream=1 UATTR DataLen=129 | -rw-rw-r-- 1 root root 5 2017-06-22 19:30:21 - | /srv/data/test1.dat - FileIndex=1 Stream=29 COMPRESSED DataLen=25 | GZIP, level=9, version=1, length=13 - FileIndex=1 Stream=3 MD5 DataLen=16 | 2Oj8otwPiW/Xy0ywAxuiSQ (base64) - FileIndex=2 Stream=1 UATTR DataLen=123 | drwxrwxr-x 2 root root 4096 2017-06-22 19:30:21 - | /srv/data/ - ... - End Job Session Record: VolSessionId=1 VolSessionTime=1498152622 JobId=1 - DataLen=205 - 22-Jun 19:34 bls JobId 0: End of Volume at file 0 on device "FileStorage" (/var/lib/bareos/storage), Volume "TestVolume001" - 22-Jun 19:34 bls JobId 0: End of all volumes. - End of Physical Medium Record: VolSessionId=0 VolSessionTime=0 JobId=0 DataLen=0 - 9 files and directories found. - \end{commands} - -For details about the Volume format, see -:raw-latex:`\bareosDeveloperGuideStorageMediaOutputFormat`. - -Show Label Information -^^^^^^^^^^^^^^^^^^^^^^ - - -.. index:: - triple: General; bls; Label - -Using the **-L** the label information of a Volume -is shown: - -.. raw:: latex - - \begin{commands}{bls: show volume label} - bls -L /var/lib/bareos/storage/testvol - bls: butil.c:282-0 Using device: "/var/lib/bareos/storage" for reading. - 12-Sep 18:41 bls JobId 0: Ready to read from volume "testvol" on device "FileStorage" (/var/lib/bareos/storage). - - Volume Label: - Id : Bareos 0.9 mortal - VerNo : 10 - VolName : File002 - PrevVolName : - VolFile : 0 - LabelType : VOL_LABEL - LabelSize : 147 - PoolName : Default - MediaType : File - PoolType : Backup - HostName : debian6 - Date label written: 06-Mar-2013 17:21 - \end{commands} - -Listing Jobs -^^^^^^^^^^^^ - -.. index:: General; Listing Jobs with bls - -.. index:: - triple: General; bls; Listing Jobs - -If you are listing a Volume to determine what Jobs to restore, normally -the **-j** option provides you with most of what -you will need as long as you don’t have multiple clients. For example: - -.. raw:: latex - - \begin{commands}{bls: list jobs} - bls /var/lib/bareos/storage/testvol -j - bls: butil.c:282-0 Using device: "/var/lib/bareos/storage" for reading. - 12-Sep 18:33 bls JobId 0: Ready to read from volume "testvol" on device "FileStorage" (/var/lib/bareos/storage). - Volume Record: File:blk=0:193 SessId=1 SessTime=1362582744 JobId=0 DataLen=158 - Begin Job Session Record: File:blk=0:64705 SessId=1 SessTime=1362582744 JobId=1 - Job=BackupClient1.2013-03-06_17.22.48_05 Date=06-Mar-2013 17:22:51 Level=F Type=B - End Job Session Record: File:blk=0:6499290 SessId=1 SessTime=1362582744 JobId=1 - Date=06-Mar-2013 17:22:52 Level=F Type=B Files=162 Bytes=6,489,071 Errors=0 Status=T - Begin Job Session Record: File:blk=0:6563802 SessId=2 SessTime=1362582744 JobId=2 - Job=BackupClient1.2013-03-06_23.05.00_02 Date=06-Mar-2013 23:05:02 Level=I Type=B - End Job Session Record: File:blk=0:18832687 SessId=2 SessTime=1362582744 JobId=2 - Date=06-Mar-2013 23:05:02 Level=I Type=B Files=3 Bytes=12,323,791 Errors=0 Status=T - ... - Begin Job Session Record: File:blk=0:319219736 SessId=299 SessTime=1369307832 JobId=454 - Job=BackupClient1.2013-09-11_23.05.00_25 Date=11-Sep-2013 23:05:03 Level=I Type=B - End Job Session Record: File:blk=0:319219736 SessId=299 SessTime=1369307832 JobId=454 - Date=11-Sep-2013 23:05:03 Level=I Type=B Files=0 Bytes=0 Errors=0 Status=T - Begin Job Session Record: File:blk=0:319284248 SessId=301 SessTime=1369307832 JobId=456 - Job=BackupCatalog.2013-09-11_23.10.00_28 Date=11-Sep-2013 23:10:03 Level=F Type=B - End Job Session Record: File:blk=0:320694269 SessId=301 SessTime=1369307832 JobId=456 - Date=11-Sep-2013 23:10:03 Level=F Type=B Files=12 Bytes=1,472,681 Errors=0 Status=T - 12-Sep 18:32 bls JobId 0: End of Volume at file 0 on device "FileStorage" (/var/lib/bareos/storage), Volume "testvol" - 12-Sep 18:32 bls JobId 0: End of all volumes. - \end{commands} - -Adding the **-v** option will display virtually all -information that is available for each record. - -Listing Blocks -^^^^^^^^^^^^^^ - -.. index:: General; Listing Blocks with bls - -.. index:: - triple: General; bls; Listing Blocks - -Normally, except for debugging purposes, you will not need to list -Bareos blocks (the “primitive” unit of Bareos data on the Volume). -However, you can do so with: - -.. raw:: latex - - \begin{commands}{} - bls -k /tmp/File002 - bls: butil.c:148 Using device: /tmp - Block: 1 size=64512 - Block: 2 size=64512 - ... - Block: 65 size=64512 - Block: 66 size=19195 - bls: Got EOF on device /tmp - End of File on device - \end{commands} - -By adding the **-v** option, you can get more -information, which can be useful in knowing what sessions were written -to the volume: - -.. raw:: latex - - \begin{commands}{} - bls -k -v /tmp/File002 - Date label written: 2002-10-19 at 21:16 - Block: 1 blen=64512 First rec FI=VOL_LABEL SessId=1 SessTim=1035062102 Strm=0 rlen=147 - Block: 2 blen=64512 First rec FI=6 SessId=1 SessTim=1035062102 Strm=DATA rlen=4087 - Block: 3 blen=64512 First rec FI=12 SessId=1 SessTim=1035062102 Strm=DATA rlen=5902 - Block: 4 blen=64512 First rec FI=19 SessId=1 SessTim=1035062102 Strm=DATA rlen=28382 - ... - Block: 65 blen=64512 First rec FI=83 SessId=1 SessTim=1035062102 Strm=DATA rlen=1873 - Block: 66 blen=19195 First rec FI=83 SessId=1 SessTim=1035062102 Strm=DATA rlen=2973 - bls: Got EOF on device /tmp - End of File on device - \end{commands} - -Armed with the SessionId and the SessionTime, you can extract just about -anything. - -If you want to know even more, add a second **-v** -to the command line to get a dump of every record in every block. - -.. raw:: latex - - \begin{commands}{} - bls -k -vv /tmp/File002 - bls: block.c:79 Dump block 80f8ad0: size=64512 BlkNum=1 - Hdrcksum=b1bdfd6d cksum=b1bdfd6d - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=VOL_LABEL Strm=0 len=147 p=80f8b40 - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=SOS_LABEL Strm=-7 len=122 p=80f8be7 - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=1 Strm=UATTR len=86 p=80f8c75 - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=2 Strm=UATTR len=90 p=80f8cdf - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=3 Strm=UATTR len=92 p=80f8d4d - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=3 Strm=DATA len=54 p=80f8dbd - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=3 Strm=MD5 len=16 p=80f8e07 - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=4 Strm=UATTR len=98 p=80f8e2b - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=4 Strm=DATA len=16 p=80f8ea1 - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=4 Strm=MD5 len=16 p=80f8ec5 - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=5 Strm=UATTR len=96 p=80f8ee9 - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=5 Strm=DATA len=1783 p=80f8f5d - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=5 Strm=MD5 len=16 p=80f9668 - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=UATTR len=95 p=80f968c - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=DATA len=32768 p=80f96ff - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=DATA len=32768 p=8101713 - bls: block.c:79 Dump block 80f8ad0: size=64512 BlkNum=2 - Hdrcksum=9acc1e7f cksum=9acc1e7f - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=contDATA len=4087 p=80f8b40 - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=DATA len=31970 p=80f9b4b - bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=MD5 len=16 p=8101841 - ... - \end{commands} - -bextract -~~~~~~~~ - -.. index:: General; bextract - -.. index:: - triple: General; Command; bextract - -.. index:: - triple: General; Disaster!Recovery; bextract - -If you find yourself using :command:`bextract`, you probably -have done something wrong. For example, if you are trying to recover a -file but are having problems, please see the -:ref:`sec:RestoreCatalog` chapter. - -Normally, you will restore files by running a **Restore** Job from the -**Console** program. However, :command:`bextract` can be -used to extract a single file or a list of files from a Bareos tape or -file. In fact, :command:`bextract` can be a useful tool to -restore files to an empty system assuming you are able to boot, you have -statically linked :command:`bextract` and you have an -appropriate **bootstrap** file. - -Please note that some of the current limitations of -:command:`bextract` are: - -#. It cannot restore access control lists (ACL) that have been backed up - along with the file data. - -#. It cannot restore encrypted files. - -#. The command line length is relatively limited, which means that you - cannot enter a huge number of volumes. If you need to enter more - volumes than the command line supports, please use a bootstrap file - (see below). - -#. Extracting files from a Windows backup on a Linux system will only - extract the plain files, not the additional Windows file information. - If you have to extract files from a Windows backup, you should use - the Windows version of :command:`bextract`. - -It is called: - -.. raw:: latex - - \begin{commands}{} - Usage: bextract - -b specify a bootstrap file - -c specify a Storage configuration file - -D specify a director name specified in the Storage - configuration file for the Key Encryption Key selection - -d set debug level to - -dt print timestamp in debug output - -e exclude list - -i include list - -p proceed inspite of I/O errors - -v verbose - -V specify Volume names (separated by |) - -? print this message - \end{commands} - -where **device-name** is the Archive Device (raw device name or full -filename) of the device to be read, and **directory-to-store-files** is -a path prefix to prepend to all the files restored. - -:raw-latex:`\warning{On Windows systems, if you specify a prefix of say d:/tmp, any file that -would have been restored to \path|C:/My Documents| will be restored to \path|D:/tmp/My Documents|. -That is, the original drive specification will be -stripped. If no prefix is specified, the file will be restored to the original -drive.}` - -Extracting with Include or Exclude Lists -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Using the **-e** option, you can specify a file containing a list of -files to be excluded. Wildcards can be used in the exclusion list. This -option will normally be used in conjunction with the **-i** option (see -below). Both the **-e** and the **-i** options may be specified at the -same time as the **-b** option. The bootstrap filters will be applied -first, then the include list, then the exclude list. - -Likewise, and probably more importantly, with the **-i** option, you can -specify a file that contains a list (one file per line) of files and -directories to include to be restored. The list must contain the full -filename with the path. If you specify a path name only, all files and -subdirectories of that path will be restored. If you specify a line -containing only the filename (e.g. **my-file.txt**) it probably will not -be extracted because you have not specified the full path. - -For example, if the file **include-list** contains: - - - -:: - - /etc/bareos - /usr/sbin - - - -Then the command: - -.. raw:: latex - - \begin{commands}{} - bextract -i include-list -V Volume /dev/nst0 /tmp - \end{commands} - -will restore from the Bareos archive **/dev/nst0** all files and -directories in the backup from **/etc/bareos** and from **/usr/sbin**. -The restored files will be placed in a file of the original name under -the directory **/tmp** (i.e. /tmp/etc/bareos/... and /tmp/usr/sbin/...). - -Extracting With a Bootstrap File -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The **-b** option is used to specify a **bootstrap** file containing the -information needed to restore precisely the files you want. Specifying a -**bootstrap** file is optional but recommended because it gives you the -most control over which files will be restored. For more details on the -**bootstrap** file, please see -:ref:`Restoring Files with the Bootstrap File BootstrapChapter` -chapter of this document. Note, you may also use a bootstrap file -produced by the **restore** command. For example: - -.. raw:: latex - - \begin{commands}{} - bextract -b bootstrap-file /dev/nst0 /tmp - \end{commands} - -The bootstrap file allows detailed specification of what files you want -restored (extracted). You may specify a bootstrap file and include -and/or exclude files at the same time. The bootstrap conditions will -first be applied, and then each file record seen will be compared to the -include and exclude lists. - -Extracting From Multiple Volumes -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you wish to extract files that span several Volumes, you can specify -the Volume names in the bootstrap file or you may specify the Volume -names on the command line by separating them with a vertical bar. See -the section above under the **bls** program entitled **Listing Multiple -Volumes** for more information. The same techniques apply equally well -to the **bextract** program or read the -:ref:`Bootstrap BootstrapChapter` chapter of this -document. - -Extracting Under Windows -^^^^^^^^^^^^^^^^^^^^^^^^ - - -.. index:: - triple: General; Windows; bextract - - -.. warning:: - If you use \command{bextract} under Windows, the ordering of the parameters is essential. - -To use :command:`bextract`, the Bareos Storage Daemon must -be installed. As bextract works on tapes or disk volumes, these must be -configured in the Storage Daemon configuration file, normally found at -*C:\ProgrammData\Bareos\bareos-sd.conf*. However, it -is not required to start the Bareos Storage Daemon. Normally, if the -Storage Daemon would be able to run, :command:`bextract` -would not be required. - -After installing, :command:`bextract` can be called via -command line: - -.. raw:: latex - - \begin{commands}{Call of bextract} - C:\Program Files\Bareos .\bextract.exe -c "C:\ProgrammData\Bareos\bareos-sd.conf" -V - \end{commands} - -If you want to use exclude or include files you need to write them like -you do on Linux. That means each path begins with a “/” and not with -“yourdrive:/”. You need to specify the parameter **-e exclude.list** as -first parameter. For example: - -.. raw:: latex - - \begin{config}{Example exclude.list} - /Program Files/Bareos/bareos-dir.exe - /ProgramData/ - \end{config} - -.. raw:: latex - - \begin{commands}{Call bextract with exclude list} - C:\Program Files\Bareos .\bextract.exe -e exclude.list -c "C:\ProgrammData\Bareos\bareos-sd.conf" -V - \end{commands} - -bscan -~~~~~ - -.. index:: General; bscan - -.. index:: - triple: General; Command; bscan - -If you find yourself using this program, you have probably done -something wrong. For example, the best way to recover a lost or damaged -Bareos database is to reload the database by using the bootstrap file -that was written when you saved it (default Bareos-dir.conf file). - -The **bscan** program can be used to re-create a database (catalog) -records from the backup information written to one or more Volumes. This -is normally needed only if one or more Volumes have been pruned or -purged from your catalog so that the records on the Volume are no longer -in the catalog, or for Volumes that you have archived. Note, if you scan -in Volumes that were previously purged, you will be able to do restores -from those Volumes. However, unless you modify the Job and File -retention times for the Jobs that were added by scanning, the next time -you run any backup Job with the same name, the records will be pruned -again. Since it takes a long time to scan Volumes this can be very -frustrating. - -With some care, :command:`bscan` can also be used to -synchronize your existing catalog with a Volume. Although we have never -seen a case of bscan damaging a catalog, since bscan modifies your -catalog, we recommend that you do a simple ASCII backup of your database -before running :command:`bscan` just to be sure. See -:ref:`Compacting Your Database CompactingMySQL` for the -details of making a copy of your database. - -:command:`bscan` can also be useful in a disaster recovery -situation, after the loss of a hard disk, if you do not have a valid -**bootstrap** file for reloading your system, or if a Volume has been -recycled but not overwritten, you can use :command:`bscan` -to re-create your database, which can then be used to **restore** your -system or a file to its previous state. - -It is called: - -.. raw:: latex - - \begin{commands}{} - Usage: bscan [options] - -B specify the database driver name (default NULL) - -b bootstrap specify a bootstrap file - -c specify configuration file - -d set debug level to nn - -dt print timestamp in debug output - -m update media info in database - -D specify a director name specified in the Storage - configuration file for the Key Encryption Key selection - -n specify the database name (default Bareos) - -u specify database user name (default Bareos) - -P specify database password (default none) - -h specify database host (default NULL) - -t specify database port (default 0) - -p proceed inspite of I/O errors - -r list records - -s synchronize or store in database - -S show scan progress periodically - -v verbose - -V specify Volume names (separated by |) - -w specify working directory (default from conf file) - -? print this message - \end{commands} - -As Bareos supports loading its database backend dynamically you need to -specify the right database driver to use using the **-B** option. - -If you are using MySQL or PostgreSQL, there is no need to supply a -working directory since in that case, bscan knows where the databases -are. However, if you have provided security on your database, you may -need to supply either the database name (**-b** option), the user name -(**-u** option), and/or the password (**-p**) options. - -NOTE: before :command:`bscan` can work, it needs at least a -bare bones valid database. If your database exists but some records are -missing because they were pruned, then you are all set. If your database -was lost or destroyed, then you must first ensure that you have the SQL -program running (MySQL or PostgreSQL), then you must create the Bareos -database (normally named bareos), and you must create the Bareos tables. -This is explained in :ref:`sec:CreateDatabase` chapter -of the manual. Finally, before scanning into an empty database, you must -start and stop the Director with the appropriate Bareos-dir.conf file so -that it can create the Client and Storage records which are not stored -on the Volumes. Without these records, scanning is unable to connect the -Job records to the proper client. - -Forgetting for the moment the extra complications of a full rebuild of -your catalog, let’s suppose that you did a backup to Volumes “Vol001” -and “Vol002”, then sometime later all records of one or both those -Volumes were pruned or purged from the database. By using **bscan** you -can recreate the catalog entries for those Volumes and then use the -**restore** command in the Console to restore whatever you want. A -command something like: - -.. raw:: latex - - \begin{commands}{} - bscan -v -V Vol001|Vol002 /dev/nst0 - \end{commands} - -will give you an idea of what is going to happen without changing your -catalog. Of course, you may need to change the path to the Storage -daemon’s conf file, the Volume name, and your tape (or disk) device -name. This command must read the entire tape, so if it has a lot of -data, it may take a long time, and thus you might want to immediately -use the command listed below. Note, if you are writing to a disk file, -replace the device name with the path to the directory that contains the -Volumes. This must correspond to the Archive Device in the conf file. - -Then to actually write or store the records in the catalog, add the -**-s** option as follows: - -.. raw:: latex - - \begin{commands}{} - bscan -s -m -v -V Vol001|Vol002 /dev/nst0 - \end{commands} - -When writing to the database, if :command:`bscan` finds -existing records, it will generally either update them if something is -wrong or leave them alone. Thus if the Volumes you are scanning are all -or partially in the catalog already, no harm will be done to that -existing data. Any missing data will simply be added. - -If you have multiple tapes, you should scan them with: - -.. raw:: latex - - \begin{commands}{} - bscan -s -m -v -V Vol001|Vol002|Vol003 /dev/nst0 - \end{commands} - -Since there is a limit on the command line length (511 bytes) accepted -by :command:`bscan`, if you have too many Volumes, you will -need to manually create a bootstrap file. See the -:ref:`Bootstrap BootstrapChapter` chapter of this manual -for more details, in particular the section entitled -:ref:`Bootstrap for bscan bscanBootstrap`. Basically, the -.bsr file for the above example might look like: - - - -:: - - Volume=Vol001 - Volume=Vol002 - Volume=Vol003 - - - -Note: :command:`bscan` does not support supplying Volume -names on the command line and at the same time in a bootstrap file. -Please use only one or the other. - -You should, always try to specify the tapes in the order they are -written. If you do not, any Jobs that span a volume may not be fully or -properly restored. However, bscan can handle scanning tapes that are not -sequential. Any incomplete records at the end of the tape will simply be -ignored in that case. If you are simply repairing an existing catalog, -this may be OK, but if you are creating a new catalog from scratch, it -will leave your database in an incorrect state. If you do not specify -all necessary Volumes on a single bscan command, bscan will not be able -to correctly restore the records that span two volumes. In other words, -it is much better to specify two or three volumes on a single bscan -command (or in a .bsr file) rather than run bscan two or three times, -each with a single volume. - -Note, the restoration process using bscan is not identical to the -original creation of the catalog data. This is because certain data such -as Client records and other non-essential data such as volume reads, -volume mounts, etc is not stored on the Volume, and thus is not restored -by bscan. The results of bscanning are, however, perfectly valid, and -will permit restoration of any or all the files in the catalog using the -normal Bareos console commands. If you are starting with an empty -catalog and expecting bscan to reconstruct it, you may be a bit -disappointed, but at a minimum, you must ensure that your -Bareos-dir.conf file is the same as what it previously was – that is, it -must contain all the appropriate Client resources so that they will be -recreated in your new database **before** running bscan. Normally when -the Director starts, it will recreate any missing Client records in the -catalog. Another problem you will have is that even if the Volumes -(Media records) are recreated in the database, they will not have their -autochanger status and slots properly set. As a result, you will need to -repair that by using the :command:`update slots` command. -There may be other considerations as well. Rather than bscanning, you -should always attempt to recover you previous catalog backup. - -Using bscan to Compare a Volume to an existing Catalog -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - -.. index:: - triple: General; Catalog; Using bscan to Compare a Volume to an existing - -If you wish to compare the contents of a Volume to an existing catalog -without changing the catalog, you can safely do so if and only if you do -**not** specify either the **-m** or the **-s** options. However, the -comparison routines are not as good or as thorough as they should be, so -we don’t particularly recommend this mode other than for testing. - -Using bscan to Recreate a Catalog from a Volume -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - -.. index:: - triple: General; Catalog; Recreate Using bscan - -.. index:: - triple: General; bscan; Recreate Catalog - -This is the mode for which **bscan** is most useful. You can either -**bscan** into a freshly created catalog, or directly into your existing -catalog (after having made an ASCII copy as described above). Normally, -you should start with a freshly created catalog that contains no data. - -Starting with a single Volume named **TestVolume1**, you run a command -such as: - -.. raw:: latex - - \begin{commands}{} - bscan -V TestVolume1 -v -s -m /dev/nst0 - \end{commands} - -If there is more than one volume, simply append it to the first one -separating it with a vertical bar. You may need to precede the vertical -bar with a forward slash escape the shell – e.g. -**TestVolume1 \| TestVolume2**. The **-v** option was -added for verbose output (this can be omitted if desired). The **-s** -option that tells :command:`bscan` to store information in -the database. The physical device name **/dev/nst0** is specified after -all the options. - -For example, after having done a full backup of a directory, then two -incrementals, I reinitialized the SQLite database as described above, -and using the bootstrap.bsr file noted above, I entered the following -command: - -.. raw:: latex - - \begin{commands}{} - bscan -b bootstrap.bsr -v -s /dev/nst0 - \end{commands} - -which produced the following output: - -.. raw:: latex - - \begin{commands}{} - bscan: bscan.c:182 Using Database: Bareos, User: bacula - bscan: bscan.c:673 Created Pool record for Pool: Default - bscan: bscan.c:271 Pool type "Backup" is OK. - bscan: bscan.c:632 Created Media record for Volume: TestVolume1 - bscan: bscan.c:298 Media type "DDS-4" is OK. - bscan: bscan.c:307 VOL_LABEL: OK for Volume: TestVolume1 - bscan: bscan.c:693 Created Client record for Client: Rufus - bscan: bscan.c:769 Created new JobId=1 record for original JobId=2 - bscan: bscan.c:717 Created FileSet record "Users Files" - bscan: bscan.c:819 Updated Job termination record for new JobId=1 - bscan: bscan.c:905 Created JobMedia record JobId 1, MediaId 1 - bscan: Got EOF on device /dev/nst0 - bscan: bscan.c:693 Created Client record for Client: Rufus - bscan: bscan.c:769 Created new JobId=2 record for original JobId=3 - bscan: bscan.c:708 Fileset "Users Files" already exists. - bscan: bscan.c:819 Updated Job termination record for new JobId=2 - bscan: bscan.c:905 Created JobMedia record JobId 2, MediaId 1 - bscan: Got EOF on device /dev/nst0 - bscan: bscan.c:693 Created Client record for Client: Rufus - bscan: bscan.c:769 Created new JobId=3 record for original JobId=4 - bscan: bscan.c:708 Fileset "Users Files" already exists. - bscan: bscan.c:819 Updated Job termination record for new JobId=3 - bscan: bscan.c:905 Created JobMedia record JobId 3, MediaId 1 - bscan: Got EOF on device /dev/nst0 - bscan: bscan.c:652 Updated Media record at end of Volume: TestVolume1 - bscan: bscan.c:428 End of Volume. VolFiles=3 VolBlocks=57 VolBytes=10,027,437 - \end{commands} - -The key points to note are that **bscan** prints a line when each major -record is created. Due to the volume of output, it does not print a line -for each file record unless you supply the **-v** option twice or more -on the command line. - -In the case of a Job record, the new JobId will not normally be the same -as the original Jobid. For example, for the first JobId above, the new -JobId is 1, but the original JobId is 2. This is nothing to be concerned -about as it is the normal nature of databases. **bscan** will keep -everything straight. - -Although :command:`bscan` claims that it created a Client -record for Client: Rufus three times, it was actually only created the -first time. This is normal. - -You will also notice that it read an end of file after each Job (Got EOF -on device ...). Finally the last line gives the total statistics for the -bscan. - -If you had added a second **-v** option to the command line, Bareos -would have been even more verbose, dumping virtually all the details of -each Job record it encountered. - -Now if you start Bareos and enter a :command:`list jobs` -command to the console program, you will get: - -.. raw:: latex - - \begin{bconsole}{list jobs} - +-------+----------+------------------+------+-----+----------+----------+---------+ - | JobId | Name | StartTime | Type | Lvl | JobFiles | JobBytes | JobStat | - +-------+----------+------------------+------+-----+----------+----------+---------+ - | 1 | usersave | 2002-10-07 14:59 | B | F | 84 | 4180207 | T | - | 2 | usersave | 2002-10-07 15:00 | B | I | 15 | 2170314 | T | - | 3 | usersave | 2002-10-07 15:01 | B | I | 33 | 3662184 | T | - +-------+----------+------------------+------+-----+----------+----------+---------+ - \end{bconsole} - -which corresponds virtually identically with what the database contained -before it was re-initialized and restored with bscan. All the Jobs and -Files found on the tape are restored including most of the Media record. -The Volume (Media) records restored will be marked as **Full** so that -they cannot be rewritten without operator intervention. - -It should be noted that :command:`bscan` cannot restore a -database to the exact condition it was in previously because a lot of -the less important information contained in the database is not saved to -the tape. Nevertheless, the reconstruction is sufficiently complete, -that you can run **restore** against it and get valid results. - -An interesting aspect of restoring a catalog backup using -:command:`bscan` is that the backup was made while Bareos -was running and writing to a tape. At the point the backup of the -catalog is made, the tape Bareos is writing to will have say 10 files on -it, but after the catalog backup is made, there will be 11 files on the -tape Bareos is writing. This there is a difference between what is -contained in the backed up catalog and what is actually on the tape. If -after restoring a catalog, you attempt to write on the same tape that -was used to backup the catalog, Bareos will detect the difference in the -number of files registered in the catalog compared to what is on the -tape, and will mark the tape in error. - -There are two solutions to this problem. The first is possibly the -simplest and is to mark the volume as Used before doing any backups. The -second is to manually correct the number of files listed in the Media -record of the catalog. This procedure is documented elsewhere in the -manual and involves using the :command:`update volume` -command in :command:`bconsole`. - -Using bscan to Correct the Volume File Count -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - -.. index:: - triple: General; bscan; Correct Volume File Count - -.. index:: - triple: General; Volume; File Count - -If the Storage daemon crashes during a backup Job, the catalog will not -be properly updated for the Volume being used at the time of the crash. -This means that the Storage daemon will have written say 20 files on the -tape, but the catalog record for the Volume indicates only 19 files. - -Bareos refuses to write on a tape that contains a different number of -files from what is in the catalog. To correct this situation, you may -run a **bscan** with the **-m** option (but without the **-s** option) -to update only the final Media record for the Volumes read. - -After bscan -^^^^^^^^^^^ - - -.. index:: - triple: General; bscan; after - -If you use **bscan** to enter the contents of the Volume into an -existing catalog, you should be aware that the records you entered may -be immediately pruned during the next job, particularly if the Volume is -very old or had been previously purged. To avoid this, after running -**bscan**, you can manually set the volume status (VolStatus) to -**Read-Only** by using the **update** command in the catalog. This will -allow you to restore from the volume without having it immediately -purged. When you have restored and backed up the data, you can reset the -VolStatus to **Used** and the Volume will be purged from the catalog. - -bcopy -~~~~~ - -.. index:: General; bcopy - -.. index:: - triple: General; Command; bcopy - -The :command:`bcopy` program can be used to copy one Bareos -archive file to another. For example, you may copy a tape to a file, a -file to a tape, a file to a file, or a tape to a tape. For tape to tape, -you will need two tape drives. In the process of making the copy, no -record of the information written to the new Volume is stored in the -catalog. This means that the new Volume, though it contains valid backup -data, cannot be accessed directly from existing catalog entries. If you -wish to be able to use the Volume with the Console restore command, for -example, you must first bscan the new Volume into the catalog. - -.. raw:: latex - - \begin{commands}{} - Usage: bcopy [-d debug_level] - -b bootstrap specify a bootstrap file - -c specify configuration file - -D specify a director name specified in the Storage - configuration file for the Key Encryption Key selection - -dnn set debug level to nn - -dt print timestamp in debug output - -i specify input Volume names (separated by |) - -o specify output Volume names (separated by |) - -p proceed inspite of I/O errors - -v verbose - -w dir specify working directory (default /tmp) - -? print this message - \end{commands} - -By using a **bootstrap** file, you can copy parts of a Bareos archive -file to another archive. - -One of the objectives of this program is to be able to recover as much -data as possible from a damaged tape. However, the current version does -not yet have this feature. - -As this is a new program, any feedback on its use would be appreciated. -In addition, I only have a single tape drive, so I have never been able -to test this program with two tape drives. - -btape -~~~~~ - -.. index:: General; btape - -.. index:: - triple: General; Command; btape - -This program permits a number of elementary tape operations via a tty -command interface. It works only with tapes and not with other kinds of -Bareos storage media (DVD, File, ...). The **test** command, described -below, can be very useful for testing older tape drive compatibility -problems. Aside from initial testing of tape drive compatibility with -**Bareos**, **btape** will be mostly used by developers writing new tape -drivers. - -**btape** can be dangerous to use with existing **Bareos** tapes because -it will relabel a tape or write on the tape if so requested regardless -that the tape may contain valuable data, so please be careful and use it -only on blank tapes. - -To work properly, :command:`btape` needs to read the Storage -daemon’s configuration file. The physical device name must be specified -on the command line, and this same device name must be present in the -Storage daemon’s configuration file read by -:command:`btape`. - -.. raw:: latex - - \begin{commands}{} - Usage: btape - -b specify bootstrap file - -c set configuration file to file - -D specify a director name specified in the Storage - configuration file for the Key Encryption Key selection - -d set debug level to nn - -dt print timestamp in debug output - -p proceed inspite of I/O errors - -s turn off signals - -v be verbose - -? print this message. - \end{commands} - -Using btape to Verify your Tape Drive -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - -.. index:: - triple: General; Drive; Verify using btape - -An important reason for this program is to ensure that a Storage daemon -configuration file is defined so that Bareos will correctly read and -write tapes. - -It is highly recommended that you run the **test** command before -running your first Bareos job to ensure that the parameters you have -defined for your storage device (tape drive) will permit **Bareos** to -function properly. You only need to mount a blank tape, enter the -command, and the output should be reasonably self explanatory. Please -see the :ref:`Tape Testing TapeTestingChapter` Chapter of -this manual for the details. - -btape Commands -^^^^^^^^^^^^^^ - -The full list of commands are: - -.. raw:: latex - - \begin{bconsole}{btape commands} - Command Description - ======= =========== - autochanger test autochanger - bsf backspace file - bsr backspace record - cap list device capabilities - clear clear tape errors - eod go to end of Bareos data for append - eom go to the physical end of medium - fill fill tape, write onto second volume - unfill read filled tape - fsf forward space a file - fsr forward space a record - help print this command - label write a Bareos label to the tape - load load a tape - quit quit btape - rawfill use write() to fill tape - readlabel read and print the Bareos tape label - rectest test record handling functions - rewind rewind the tape - scan read() tape block by block to EOT and report - scanblocks Bareos read block by block to EOT and report - speed report drive speed - status print tape status - test General test Bareos tape functions - weof write an EOF on the tape - wr write a single Bareos block - rr read a single record - qfill quick fill command - \end{bconsole} - -The most useful commands are: - -- test – test writing records and EOF marks and reading them back. - -- fill – completely fill a volume with records, then write a few - records on a second volume, and finally, both volumes will be read - back. This command writes blocks containing random data, so your - drive will not be able to compress the data, and thus it is a good - test of the real physical capacity of your tapes. - -- readlabel – read and dump the label on a Bareos tape. - -- cap – list the device capabilities and status. - -The **readlabel** command can be used to display the details of a Bareos -tape label. This can be useful if the physical tape label was lost or -damaged. - -In the event that you want to relabel a Bareos volume, you can simply -use the **label** command which will write over any existing label. -However, please note for labeling tapes, we recommend that you use the -**label** command in the **Console** program since it will never -overwrite a valid Bareos tape. - -Testing your Tape Drive -''''''''''''''''''''''' - -To determine the best configuration of your tape drive, you can run the -new ``speed`` command available in the ``btape`` program. - -This command can have the following arguments: - -- Specify the - Maximum File Size - for this test. This counter is in GB. - -- Specify the number of file to be written. The amount of data should - be greater than your memory (:math:`file\_size*nb\_file`). - -- This flag permits to skip tests with constant data. - -- This flag permits to skip tests with random data. - -- This flag permits to skip tests with raw access. - -- This flag permits to skip tests with Bareos block access. - -.. raw:: latex - - \begin{bconsole}{btape speed} - *speed file_size=3 skip_raw - btape.c:1078 Test with zero data and Bareos block structure. - btape.c:956 Begin writing 3 files of 3.221 GB with blocks of 129024 bytes. - ++++++++++++++++++++++++++++++++++++++++++ - btape.c:604 Wrote 1 EOF to "Drive-0" (/dev/nst0) - btape.c:406 Volume bytes=3.221 GB. Write rate = 44.128 MB/s - ... - btape.c:383 Total Volume bytes=9.664 GB. Total Write rate = 43.531 MB/s - - btape.c:1090 Test with random data, should give the minimum throughput. - btape.c:956 Begin writing 3 files of 3.221 GB with blocks of 129024 bytes. - +++++++++++++++++++++++++++++++++++++++++++ - btape.c:604 Wrote 1 EOF to "Drive-0" (/dev/nst0) - btape.c:406 Volume bytes=3.221 GB. Write rate = 7.271 MB/s - +++++++++++++++++++++++++++++++++++++++++++ - ... - btape.c:383 Total Volume bytes=9.664 GB. Total Write rate = 7.365 MB/s - \end{bconsole} - -When using compression, the random test will give your the minimum -throughput of your drive . The test using constant string will give you -the maximum speed of your hardware chain. (cpu, memory, scsi card, -cable, drive, tape). - -You can change the block size in the Storage Daemon configuration file. - -bscrypto -~~~~~~~~ - -.. index:: General; bscrypto - -.. index:: - triple: General; Command; bscrypto - -:command:`bscrypto` is used in the process of encrypting -tapes (see also :ref:`LTOHardwareEncryptionGeneral`). -The |bareosSd| and the btools (:command:`bls`, -:command:`bextract}`, :raw-latex:`\command{bscan`, -:command:`btape}`, :raw-latex:`\command{bextract`) will use -a so called |bareosSd| plugin to perform the setting and -clearing of the encryption keys. To bootstrap the encryption support and -for populating things like the crypto cache with encryption keys of -volumes that you want to scan, you need to use the bscrypto tool. The -bscrypto tool has the following capabilities: - -- Generate a new passphrase - - - | to be used as a so called Key Encryption Key (KEK) for wrapping - a passphrase using RFC3394 key wrapping with aes-wrap - | - or - - - - for usage as a clear text encryption key loaded into the tape - drive. - -- Base64-encode a key if requested - -- Generate a wrapped passphrase which performs the following steps: - - - generate a semi random clear text passphrase - - - wrap the passphrase using the Key Encryption Key using RFC3394 - - - base64-encode the wrapped key (as the wrapped key is binary, we - always need to base64-encode it in order to be able to pass the - data as part of the director to storage daemon protocol - -- | show the content of a wrapped or unwrapped keyfile. - | This can be used to reveal the content of the passphrase when a - passphrase is stored in the database and you have the urge to - change the Key Encryption Key. Normally it is unwise to change the - Key Encryption Key, as this means that you have to redo all your - stored encryption keys, as they are stored in the database wrapped - using the Key Encryption Key available in the config during the - label phase of the volume. - -- Clear the crypto cache on the machine running the bareos-sd, which - keeps a cache of used encryption keys, which can be used when the - bareos-sd is restarted without the need to connect to the bareos-dir - to retrieve the encryption keys. - -- Set the encryption key of the drive - -- Clear the encryption key of the drive - -- Show the encryption status of the drive - -- Show the encryption status of the next block (e.g. volume) - -- Populate the crypto cache with data - -Other Programs --------------- - -The following programs are general utility programs and in general do -not need a configuration file nor a device name. - -bsmtp -~~~~~ - -.. index:: General; bsmtp - -.. index:: - triple: General; Command; bsmtp - -:command:`bsmtp` is a simple mail transport program that -permits more flexibility than the standard mail programs typically found -on Unix systems. It can even be used on Windows machines. - -It is called: - -.. raw:: latex - - \begin{commands}{bsmtp} - Usage: bsmtp [-f from] [-h mailhost] [-s subject] [-c copy] [recipient ...] - -4 forces bsmtp to use IPv4 addresses only. - -6 forces bsmtp to use IPv6 addresses only. - -8 set charset to UTF-8 - -a use any ip protocol for address resolution - -c set the Cc: field - -d set debug level to - -dt print a timestamp in debug output - -f set the From: field - -h use mailhost:port as the SMTP server - -s set the Subject: field - -r set the Reply-To: field - -l set the maximum number of lines to send (default: unlimited) - -? print this message. - \end{commands} - -If the **-f** option is not specified, :command:`bsmtp` will -use your userid. If the option **-h** is not specified -:command:`bsmtp` will use the value in the environment -variable **bsmtpSERVER** or if there is none **localhost**. By default -port 25 is used. - -If a line count limit is set with the **-l** option, -:command:`bsmtp` will not send an email with a body text -exceeding that number of lines. This is especially useful for large -restore job reports where the list of files restored might produce very -long mails your mail-server would refuse or crash. However, be aware -that you will probably suppress the job report and any error messages -unless you check the log file written by the Director (see the messages -resource in this manual for details). - -**recipients** is a space separated list of email recipients. - -The body of the email message is read from standard input. - -An example of the use of :command:`bsmtp` would be to put -the following statement in the -:ref:`Messages resource MessagesChapter` of your - |bareosDir| configuration. - -.. raw:: latex - - \begin{bconfig}{bsmtp in Message resource} - Mail Command = "bsmtp -h mail.example.com -f \"\(Bareos\) %r\" -s \"Bareos: %t %e of %c %l\" %r" - Operator Command = "bsmtp -h mail.example.com -f \"\(Bareos\) %r\" -s \"Bareos: Intervention needed for %j\" %r" - \end{bconfig} - -You have to replace **mail.example.com** with the fully qualified name -of your SMTP (email) server, which normally listens on port 25. For more -details on the substitution characters (e.g. %r) used in the above line, -please see the documentation of the -:ref:`MailCommand in the Messages Resource mailcommand` -chapter of this manual. - -It is HIGHLY recommended that you test one or two cases by hand to make -sure that the **mailhost** that you specified is correct and that it -will accept your email requests. Since **bsmtp** always uses a TCP -connection rather than writing in the spool file, you may find that your -**from** address is being rejected because it does not contain a valid -domain, or because your message is caught in your spam filtering rules. -Generally, you should specify a fully qualified domain name in the -**from** field, and depending on whether your bsmtp gateway is Exim or -Sendmail, you may need to modify the syntax of the from part of the -message. Please test. - -When running :command:`bsmtp` by hand, you will need to -terminate the message by entering a ctrl-d in column 1 of the last line. -If you are getting incorrect dates (e.g. 1970) and you are running with -a non-English language setting, you might try adding a -:command:`LANG=C` immediately before the -:command:`bsmtp` call. - -In general, :command:`bsmtp` attempts to cleanup email -addresses that you specify in the from, copy, mailhost, and recipient -fields, by adding the necessary < and > characters around the address -part. However, if you include a **display-name** (see RFC 5332), some -SMTP servers such as Exchange may not accept the message if the -**display-name** is also included in < and >. As mentioned above, you -must test, and if you run into this situation, you may manually add the -< and > to the Bareos -Mail Command or -Operator Command and -when :command:`bsmtp` is formatting an address if it already -contains a < or > character, it will leave the address unchanged. - -bareos-dbcheck -~~~~~~~~~~~~~~ - -.. _dbcheck: -.. index:: General; bareos-dbcheck - -.. index:: - triple: General; Command; bareos-dbcheck - -.. index:: - triple: General; Catalog; database check - -:command:`bareos-dbcheck` is a simple program that will -search for logical inconsistencies in the Bareos tables in your -database, and optionally fix them. It is a database maintenance routine, -in the sense that it can detect and remove unused rows, but it is not a -database repair routine. To repair a database, see the tools furnished -by the database vendor. Normally :command:`bareos-dbcheck` -should never need to be run, but if Bareos has crashed or you have a lot -of Clients, Pools, or Jobs that you have removed, it could be useful. - -:command:`bareos-dbcheck` is best started as the same user, -as the |bareosDir| is running, normally -**bareos}`. If you are :raw-latex:`\user{root** on -Linux, use the following command to switch to user -**bareos**: - -.. raw:: latex - - \begin{commands}{Substitute user to bareos} - su -s /bin/bash - bareos - \end{commands} - -If not, problems of reading the Bareos configuration or accessing the -database can arise. - -:command:`bareos-dbcheck` supports following command line -options: - -.. raw:: latex - - \begin{commands}{} - Usage: bareos-dbcheck [-c config ] [-B] [-C catalog name] [-d debug level] [-D driver name] [] [] - -b batch mode - -C catalog name in the director conf file - -c Director configuration filename or configuration directory (e.g. /etc/bareos) - -B print catalog configuration and exit - -d set debug level to - -dt print a timestamp in debug output - -D specify the database driver name (default NULL) - -f fix inconsistencies - -v verbose - -? print this message - \end{commands} - -When using the default configuration paths, it is not necessary to -specify any options. Optionally, as Bareos supports loading its database -backend dynamically you may specify the right database driver to use -using the **-D** option. - -If the **-B** option is specified, -:command:`bareos-dbcheck` will print out catalog information -in a simple text based format: - -.. raw:: latex - - \begin{commands}{} - # bareos-dbcheck -B - catalog=MyCatalog - db_type=SQLite - db_name=bareos - db_driver= - db_user=bareos - db_password= - db_address= - db_port=0 - db_socket= - \end{commands} - -If the **-c** option is given with the - |bareosDir| configuration, there is no need to enter any of -the command line arguments, in particular the working directory as -:command:`bareos-dbcheck` will read them from the file. - -If the **-f** option is specified, -:command:`bareos-dbcheck` will repair (**fix**) the -inconsistencies it finds. Otherwise, it will report only. - -If the **-b** option is specified, -:command:`bareos-dbcheck` will run in batch mode, and it -will proceed to examine and fix (if **-f** is set) -all programmed inconsistency checks. If the **-b** -option is not specified, :command:`bareos-dbcheck` will -enter interactive mode and prompt with the following: - -.. raw:: latex - - \begin{commands}{} - Hello, this is the database check/correct program. - Modify database is off. Verbose is off. - Please select the function you want to perform. - 1) Toggle modify database flag - 2) Toggle verbose flag - 3) Repair bad Filename records - 4) Repair bad Path records - 5) Eliminate duplicate Filename records - 6) Eliminate duplicate Path records - 7) Eliminate orphaned Jobmedia records - 8) Eliminate orphaned File records - 9) Eliminate orphaned Path records - 10) Eliminate orphaned Filename records - 11) Eliminate orphaned FileSet records - 12) Eliminate orphaned Client records - 13) Eliminate orphaned Job records - 14) Eliminate all Admin records - 15) Eliminate all Restore records - 16) All (3-15) - 17) Quit - Select function number: - \end{commands} - -By entering 1 or 2, you can toggle the modify database flag -(**-f** option) and the verbose flag -(**-v**). It can be helpful and reassuring to turn -off the modify database flag, then select one or more of the consistency -checks (items 3 through 13) to see what will be done, then toggle the -modify flag on and re-run the check. - -Since Bareos 16.2.5, -when running :command:`bareos-dbcheck` with -**-b}` and :raw-latex:`\parameter{-v**, it will not -interactively ask if results should be printed or not. Instead, it does -not print any detail results. - -The inconsistencies examined are the following: - -- Duplicate Filename records. This can happen if you accidentally run - two copies of Bareos at the same time, and they are both adding - filenames simultaneously. It is a rare occurrence, but will create an - inconsistent database. If this is the case, you will receive error - messages during Jobs warning of duplicate database records. If you - are not getting these error messages, there is no reason to run this - check. - -- Repair bad Filename records. This checks and corrects filenames that - have a trailing slash. They should not. - -- Repair bad Path records. This checks and corrects path names that do - not have a trailing slash. They should. - -- Duplicate Path records. This can happen if you accidentally run two - copies of Bareos at the same time, and they are both adding filenames - simultaneously. It is a rare occurrence, but will create an - inconsistent database. See the item above for why this occurs and how - you know it is happening. - -- Orphaned JobMedia records. This happens when a Job record is deleted - (perhaps by a user issued SQL statement), but the corresponding - JobMedia record (one for each Volume used in the Job) was not - deleted. Normally, this should not happen, and even if it does, these - records generally do not take much space in your database. However, - by running this check, you can eliminate any such orphans. - -- Orphaned File records. This happens when a Job record is deleted - (perhaps by a user issued SQL statement), but the corresponding File - record (one for each Volume used in the Job) was not deleted. Note, - searching for these records can be **very** time consuming (i.e. it - may take hours) for a large database. Normally this should not happen - as Bareos takes care to prevent it. Just the same, this check can - remove any orphaned File records. It is recommended that you run this - once a year since orphaned File records can take a large amount of - space in your database. You might want to ensure that you have - indexes on JobId, FilenameId, and PathId for the File table in your - catalog before running this command. - -- Orphaned Path records. This condition happens any time a directory is - deleted from your system and all associated Job records have been - purged. During standard purging (or pruning) of Job records, Bareos - does not check for orphaned Path records. As a consequence, over a - period of time, old unused Path records will tend to accumulate and - use space in your database. This check will eliminate them. It is - recommended that you run this check at least once a year. - -- Orphaned Filename records. This condition happens any time a file is - deleted from your system and all associated Job records have been - purged. This can happen quite frequently as there are quite a large - number of files that are created and then deleted. In addition, if - you do a system update or delete an entire directory, there can be a - very large number of Filename records that remain in the catalog but - are no longer used. - - During standard purging (or pruning) of Job records, Bareos does not - check for orphaned Filename records. As a consequence, over a period - of time, old unused Filename records will accumulate and use space in - your database. This check will eliminate them. It is strongly - recommended that you run this check at least once a year, and for - large database (more than 200 Megabytes), it is probably better to - run this once every 6 months. - -- Orphaned Client records. These records can remain in the database - long after you have removed a client. - -- Orphaned Job records. If no client is defined for a job or you do not - run a job for a long time, you can accumulate old job records. This - option allow you to remove jobs that are not attached to any client - (and thus useless). - -- All Admin records. This command will remove all Admin records, - regardless of their age. - -- All Restore records. This command will remove all Restore records, - regardless of their age. - -If you are using MySQL, :command:`bareos-dbcheck` in -interactive mode will ask you if you want to create temporary indexes to -speed up orphaned Path and Filename elimination. In batch mode -(**-b**) the temporary indexes will be created -without asking. - -If you are using bvfs (e.g. used by -:ref:`bareos-webui sec:webui`), don’t eliminate orphaned -path, else you will have to rebuild -**brestore_pathvisibility** and -**brestore_pathhierarchy** indexes. - -Normally you should never need to run -:command:`bareos-dbcheck` in spite of the recommendations -given above, which are given so that users don’t waste their time -running :command:`bareos-dbcheck` too often. - -bregex -~~~~~~ - -.. index:: General; bregex - -.. index:: - triple: General; Command; bregex - -:command:`bregex` is a simple program that will allow you to -test regular expressions against a file of data. This can be useful -because the regex libraries on most systems differ, and in addition, -regex expressions can be complicated. - -To run it, use: - -:: - - Usage: bregex [-d debug_level] -f - -f specify file of data to be matched - -l suppress line numbers - -n print lines that do not match - -? print this message. - -The is a filename that contains lines of data to be matched -(or not) against one or more patterns. When the program is run, it will -prompt you for a regular expression pattern, then apply it one line at a -time against the data in the file. Each line that matches will be -printed preceded by its line number. You will then be prompted again for -another pattern. - -Enter an empty line for a pattern to terminate the program. You can -print only lines that do not match by using the -n option, and you can -suppress printing of line numbers with the -l option. - -This program can be useful for testing regex expressions to be applied -against a list of filenames. - -bwild -~~~~~ - -.. index:: General; bwild - -.. index:: - triple: General; Command; bwild - -:command:`bwild` is a simple program that will allow you to -test wild-card expressions against a file of data. - -To run it, use: - -:: - - Usage: bwild [-d debug_level] -f - -f specify file of data to be matched - -l suppress line numbers - -n print lines that do not match - -? print this message. - -The is a filename that contains lines of data to be matched -(or not) against one or more patterns. When the program is run, it will -prompt you for a wild-card pattern, then apply it one line at a time -against the data in the file. Each line that matches will be printed -preceded by its line number. You will then be prompted again for another -pattern. - -Enter an empty line for a pattern to terminate the program. You can -print only lines that do not match by using the -n option, and you can -suppress printing of line numbers with the -l option. - -This program can be useful for testing wild expressions to be applied -against a list of filenames. - -bpluginfo -~~~~~~~~~ - -.. index:: General; bpluginfo - -.. index:: - triple: General; Command; bpluginfo - -The main purpose of bpluginfo is to display different information about -Bareos plugin. You can use it to check a plugin name, author, license -and short description. You can use -f option to display API implemented -by the plugin. Some plugins may require additional ’-a’ option for val- -idating a Bareos Daemons API. In most cases it is not required. diff --git a/docs/manuals/en/new_main_reference/source/quickstart.rst b/docs/manuals/en/new_main_reference/source/quickstart.rst index 8c9d0d5fc4f..5f38800c3d3 100644 --- a/docs/manuals/en/new_main_reference/source/quickstart.rst +++ b/docs/manuals/en/new_main_reference/source/quickstart.rst @@ -1,13 +1,8 @@ Understanding Jobs and Schedules ================================ -.. index:: - triple: General; Schedule; Understanding Schedules -.. _`Schedule`: - - - -.. _`JobsandSchedules`: JobsandSchedules +:raw-latex:`\index[general]{Schedule!Understanding Schedules}` +:raw-latex:`\label{JobsandSchedules}` In order to make Bareos as flexible as possible, the directions given to Bareos are specified in several pieces. The main instruction is the job @@ -39,23 +34,12 @@ verify, and admin jobs, which have different requirements. Understanding Pools, Volumes and Labels ======================================= -.. index:: - triple: General; Pools; Understanding -.. _`Pools`: - -.. index:: - triple: General; Volumes; Understanding -.. _`Volumes`: - -.. index:: - triple: General; Label; Understanding Labels -.. _`Label`: +:raw-latex:`\index[general]{Pools!Understanding}` +:raw-latex:`\index[general]{Volumes!Understanding}` +:raw-latex:`\index[general]{Label!Understanding Labels}` +:raw-latex:`\label{PoolsVolsLabels}` - - -.. _`PoolsVolsLabels`: PoolsVolsLabels - -If you have been using a program such as :command:`tar` to +If you have been using a program such as :raw-latex:`\command{tar}` to backup your system, Pools, Volumes, and labeling may be a bit confusing at first. A Volume is a single physical tape (or possibly a single file) on which Bareos will write your backup data. Pools group together @@ -65,7 +49,7 @@ your Job, you specify a Pool, and Bareos will select the next appendable Volume from the Pool and mounts it. Although the basic Pool options are specified in the Director’s -:ref:`DirectorResourcePool Pool` resource, the real Pool +:raw-latex:`\ilink{Pool}{DirectorResourcePool}` resource, the real Pool is maintained in the Bareos Catalog. It contains information taken from the Pool resource (configuration file) as well as information on all the Volumes that have been added to the Pool. @@ -79,7 +63,7 @@ Before Bareos will read or write a Volume, the physical Volume must have a Bareos software label so that Bareos can be sure the correct Volume is mounted. Depending on your configuration, this is either done automatically by Bareos or manually using the -:command:`label ` command in the Console program. +:raw-latex:`\bcommand{label}{}` command in the Console program. The steps for creating a Pool, adding Volumes to it, and writing software labels to the Volumes, may seem tedious at first, but in fact, @@ -92,7 +76,7 @@ Pool in the daily and weekly backup Jobs, you thereby insure that no daily Job ever writes to a Volume in the Weekly Pool and vice versa, and Bareos will tell you what tape is needed and when. -For more on Pools, see the :ref:`DirectorResourcePool` +For more on Pools, see the :raw-latex:`\nameref{DirectorResourcePool}` section of the Director Configuration chapter, or simply read on, and we will come back to this subject later. @@ -101,50 +85,43 @@ will come back to this subject later. Setting Up Bareos Configuration Files ===================================== -.. index:: - triple: General; Configuration; Files -.. _`Configuration`: - +:raw-latex:`\index[general]{Configuration!Files}` On Unix, Bareos configuration files are usually located in the -*/etc/bareos/* +:raw-latex:`\path`\|/etc/bareos/\| directory and are named accordingly to the programs that use it. Since Bareos -16.2.4 +:raw-latex:`\sinceVersion{Dir}{Subdirectory Configuration Scheme used as Default}{16.2.4}` the default configuration is stored as one file per resource in -subdirectories under *bareos-dir.d*, -*bareos-sd.d* or -*bareos-fd.d*. For details, see -:ref:`ConfigureChapter` and -:ref:`sec:SubdirectoryConfigurationScheme`. +subdirectories under :raw-latex:`\directory{bareos-dir.d}`, +:raw-latex:`\directory{bareos-sd.d}` or +:raw-latex:`\directory{bareos-fd.d}`. For details, see +:raw-latex:`\nameref{ConfigureChapter}` and +:raw-latex:`\nameref{sec-SubdirectoryConfigurationScheme}`. Testing your Configuration Files ================================ -.. index:: - triple: General; Testing; Configuration Files -.. _`Testing`: - +:raw-latex:`\index[general]{Testing!Configuration Files}` You can test if your configuration file is syntactically correct by -running the appropriate daemon with the **-t** +running the appropriate daemon with the :raw-latex:`\parameter{-t}` option. The daemon will process the configuration file and print any error messages then terminate. As the |bareosDir| and |bareosSd| runs as user -**bareos**, testing the configuration should be done as -**bareos**. +:raw-latex:`\user{bareos}`, testing the configuration should be done as +:raw-latex:`\user{bareos}`. This is especially required to test the |bareosDir|, as it also connects to the database and checks if the catalog schema version is correct. Depending on your database, only the -**bareos** has permission to access it. +:raw-latex:`\user{bareos}` has permission to access it. -.. raw:: latex +:: - \begin{commands}{Testing Configuration Files} - su bareos -s /bin/sh -c "/usr/sbin/bareos-dir -t" - su bareos -s /bin/sh -c "/usr/sbin/bareos-sd -t" - bareos-fd -t - bconsole -t - bareos-tray-monitor -t - \end{commands} + {Testing Configuration Files} + su bareos -s /bin/sh -c "/usr/sbin/bareos-dir -t" + su bareos -s /bin/sh -c "/usr/sbin/bareos-sd -t" + bareos-fd -t + bconsole -t + bareos-tray-monitor -t diff --git a/docs/manuals/en/new_main_reference/source/recycling.rst b/docs/manuals/en/new_main_reference/source/recycling.rst index ef122eeec9f..0fa54ceaec4 100644 --- a/docs/manuals/en/new_main_reference/source/recycling.rst +++ b/docs/manuals/en/new_main_reference/source/recycling.rst @@ -3,14 +3,8 @@ Automatic Volume Recycling ========================== -.. index:: - triple: General; Recycle; Automatic Volume -.. _`Recycle`: - -.. index:: - triple: General; Volume!Recycle; Automatic -.. _`Volume!Recycle`: - +:raw-latex:`\index[general]{Recycle!Automatic Volume}` +:raw-latex:`\index[general]{Volume!Recycle!Automatic}` By default, once Bareos starts writing a Volume, it can append to the volume, but it will not overwrite the existing data thus destroying it. @@ -24,7 +18,7 @@ rewritten. You may not want Bareos to automatically recycle (reuse) tapes. This would require a large number of tapes though, and in such a case, it is possible to manually recycle tapes. For more on manual recycling, see -the :ref:`manualrecycling` chapter. +the :raw-latex:`\nameref{manualrecycling}` chapter. Most people prefer to have a Pool of tapes that are used for daily backups and recycled once a week, another Pool of tapes that are used @@ -41,7 +35,7 @@ Automatic recycling of Volumes is controlled by four records in the :raw-latex:`\resourcetype{Dir}{Pool}` resource definition. These four records are: -- **Auto Prune** (Dir configuration, Pool resource) = yes +- :raw-latex:`\linkResourceDirective{Dir}{Pool}{Auto Prune}` = yes - @@ -49,7 +43,7 @@ records are: \linkResourceDirective{Dir}{Pool}{Volume Retention} -- **Recycle** (Dir configuration, Pool resource) = yes +- :raw-latex:`\linkResourceDirective{Dir}{Pool}{Recycle}` = yes - @@ -81,27 +75,27 @@ is full, you can use one or more additional directives such as: \linkResourceDirective{Dir}{Pool}{Maximum Volume Bytes} Please see below and the -:ref:`DiskChapter Basic Volume Management` chapter of +:raw-latex:`\ilink{Basic Volume Management}{DiskChapter}` chapter of this manual for complete examples. Automatic recycling of Volumes is performed by Bareos only when it wants a new Volume and no appendable Volumes are available in the Pool. It will then search the Pool for any Volumes with the **Recycle** flag set -and the Volume Status is **Purged**. At that +and the Volume Status is :raw-latex:`\volumestatus{Purged}`. At that point, it will choose the oldest purged volume and recycle it. -If there are no volumes with status **Purged**, +If there are no volumes with status :raw-latex:`\volumestatus{Purged}`, then the recycling occurs in two steps: #. The Catalog for a Volume must be pruned of all Jobs (i.e. Purged). #. The actual recycling of the Volume. -Only Volumes marked **Full** or -**Used** will be considerd for pruning. The +Only Volumes marked :raw-latex:`\volumestatus{Full}` or +:raw-latex:`\volumestatus{Used}` will be considerd for pruning. The Volume will be purged if the :raw-latex:`\volumeparameter{Volume Retention}{}` period has expired. -When a Volume is marked as **Purged**, it means +When a Volume is marked as :raw-latex:`\volumestatus{Purged}`, it means that no Catalog records reference that Volume and the Volume can be recycled. @@ -122,7 +116,7 @@ this is that Bareos wants to preserve the data on your old tapes (even though purged from the catalog) as long as absolutely possible before overwriting it. There are also a number of directives such as :raw-latex:`\volumeparameter{Volume Use Duration}{}` that will -automatically mark a volume as **Used** and thus +automatically mark a volume as :raw-latex:`\volumestatus{Used}` and thus no longer appendable. .. _AutoPruning: @@ -130,14 +124,8 @@ no longer appendable. Automatic Pruning ----------------- -.. index:: - triple: General; Automatic; Pruning -.. _`Automatic`: - -.. index:: - triple: General; Pruning; Automatic -.. _`Pruning`: - +:raw-latex:`\index[general]{Automatic!Pruning}` +:raw-latex:`\index[general]{Pruning!Automatic}` As Bareos writes files to tape, it keeps a list of files, jobs, and volumes in a database called the catalog. Among other things, the @@ -155,7 +143,7 @@ removed automatically. Once a job has been pruned, you can still restore it from the backup tape, but one additional step is required: scanning the volume with -:command:`bscan`. +:raw-latex:`\command{bscan}`. The alternative to Automatic Pruning is Manual Pruning, in which you explicitly tell Bareos to erase the catalog entries for a volume. You’d @@ -163,15 +151,12 @@ usually do this when you want to reuse a Bareos volume, because there’s no point in keeping a list of files that USED TO BE on a tape. Or, if the catalog is starting to get too big, you could prune the oldest jobs to save space. Manual pruning is done with the -:ref:`ManualPruning prune command` in the console. +:raw-latex:`\ilink{prune command}{ManualPruning}` in the console. Pruning Directives ------------------ -.. index:: - triple: General; Pruning; Directives -.. _`Pruning`: - +:raw-latex:`\index[general]{Pruning!Directives}` There are three pruning durations. All apply to catalog database records and not to the actual data in a Volume. The pruning (or retention) @@ -191,7 +176,7 @@ the files. When a Job record is pruned, the Volume (Media record) for that Job can still remain in the database, and if you do a -:command:`list volumes`, you will see the volume +:raw-latex:`\bcommand{list}{volumes}`, you will see the volume information, but the Job records (and its File records) will no longer be available. @@ -200,26 +185,26 @@ but it also prevents the catalog from growing to be too large. You choose the retention periods in function of how many files you are backing up and the time periods you want to keep those records online, and the size of the database. It is possible to re-insert the records -(with 98% of the original data) by using :command:`bscan` to +(with 98% of the original data) by using :raw-latex:`\command{bscan}` to scan in a whole Volume or any part of the volume that you want. -By setting **Auto Prune** (Dir configuration, Pool resource) = +By setting :raw-latex:`\linkResourceDirective{Dir}{Pool}{Auto Prune}` = yes you will permit the |bareosDir| to automatically prune all Volumes in the Pool when a Job needs another Volume. Volume pruning means removing records from the catalog. It does not shrink the size of the Volume or affect the Volume data until the Volume gets overwritten. When a Job requests another volume and there are no Volumes with Volume -status **Append** available, Bareos will begin +status :raw-latex:`\volumestatus{Append}` available, Bareos will begin volume pruning. This means that all Jobs that are older than the :raw-latex:`\volumeparameter{Volume Retention}{}` period will be pruned from every Volume that has Volume status -**Full}` or :raw-latex:`\volumestatus{Used** and +:raw-latex:`\volumestatus{Full}` or :raw-latex:`\volumestatus{Used}` and has :raw-latex:`\volumeparameter{Recycle}{yes}`. Pruning consists of deleting the corresponding Job, File, and JobMedia records from the catalog database. No change to the physical data on the Volume occurs during the pruning process. When all files are pruned from a Volume (i.e. no records in the catalog), the Volume will be marked as -**Purged** implying that no Jobs remain on the +:raw-latex:`\volumestatus{Purged}` implying that no Jobs remain on the volume. The Pool records that control the pruning are described below. .. raw:: latex @@ -282,42 +267,29 @@ volume. The Pool records that control the pruning are described below. Recycling Algorithm ------------------- -.. index:: - triple: General; Algorithm; Recycling -.. _`Algorithm`: - -.. index:: - triple: General; Recycle; Algorithm -.. _`Recycle`: - - - -.. _`RecyclingAlgorithm}` :raw-latex:`\label{Recycling`: RecyclingAlgorithm}` :raw-latex:`\label{Recycling +:raw-latex:`\index[general]{Algorithm!Recycling}` +:raw-latex:`\index[general]{Recycle!Algorithm}` +:raw-latex:`\label{RecyclingAlgorithm}` :raw-latex:`\label{Recycling}` After all Volumes of a Pool have been pruned (as mentioned above, this happens when a Job needs a new Volume and no appendable Volumes are available), Bareos will look for the oldest Volume that is -**Purged** (all Jobs and Files expired), and if +:raw-latex:`\volumestatus{Purged}` (all Jobs and Files expired), and if the :raw-latex:`\volumeparameter{Recycle}{yes}` for that Volume, Bareos will relabel it and write new data on it. As mentioned above, there are two key points for getting a Volume to be recycled. First, the Volume must no longer be marked -**Append** (there are a number of directives to +:raw-latex:`\volumestatus{Append}` (there are a number of directives to automatically make this change), and second since the last write on the Volume, one or more of the Retention periods must have expired so that there are no more catalog backup job records that reference that Volume. Once both those conditions are satisfied, the volume can be marked -**Purged** and hence recycled. +:raw-latex:`\volumestatus{Purged}` and hence recycled. The full algorithm that Bareos uses when it needs a new Volume is: -.. index:: General; New Volume Algorithm -.. _`New Volume Algorithm`: - -.. index:: - triple: General; Algorithm; New Volume -.. _`Algorithm`: - +:raw-latex:`\index[general]{New Volume Algorithm}` +:raw-latex:`\index[general]{Algorithm!New Volume}` The algorithm described below assumes that :raw-latex:`\configdirective{Auto Prune}` is enabled, that Recycling is @@ -329,12 +301,12 @@ used the defaults for all these items. Storage device). #. Search the Pool for a Volume with Volume - status=**Append** (if there is more than one, + status=:raw-latex:`\volumestatus{Append}` (if there is more than one, the Volume with the oldest date last written is chosen. If two have the same date then the one with the lowest MediaId is chosen). #. Search the Pool for a Volume with Volume - status=**Recycle** and the InChanger flag is + status=:raw-latex:`\volumestatus{Recycle}` and the InChanger flag is set true (if there is more than one, the Volume with the oldest date last written is chosen. If two have the same date then the one with the lowest MediaId is chosen). @@ -348,11 +320,11 @@ used the defaults for all these items. #. Search the Pool for a Volume with VolStatus=Purged -#. If a Pool named **Scratch** exists, search for a +#. If a Pool named :raw-latex:`\pool{Scratch}` exists, search for a Volume and if found move it to the current Pool for the Job and use it. Note, when the Scratch Volume is moved into the current Pool, the basic Pool defaults are applied as if it is a newly labeled Volume - (equivalent to an :command:`update volume from pool` + (equivalent to an :raw-latex:`\bcommand{update}{volume from pool}` command). #. If we were looking for Volumes in the Autochanger, go back to step 2 @@ -364,13 +336,13 @@ used the defaults for all these items. Volume will be created. #. Prune the oldest Volume if - **Recycle Oldest Volume** (Dir configuration, Pool resource)=yes + :raw-latex:`\linkResourceDirective{Dir}{Pool}{Recycle Oldest Volume}`=yes (the Volume with the oldest LastWritten date and VolStatus equal to Full, Recycle, Purged, Used, or Append is chosen). This record ensures that all retention periods are properly respected. #. Purge the oldest Volume if - **Purge Oldest Volume** (Dir configuration, Pool resource)=yes + :raw-latex:`\linkResourceDirective{Dir}{Pool}{Purge Oldest Volume}`=yes (the Volume with the oldest LastWritten date and VolStatus equal to Full, Recycle, Purged, Used, or Append is chosen). :raw-latex:`\warning{We strongly recommend against the use of \configdirective{Purge Oldest Volume} as it can quite easily lead to loss of current backup @@ -385,20 +357,20 @@ On the other hand, if you have inserted a different Volume after the last job, and Bareos recognizes the Volume as valid, it will request authorization from the Director to use this Volume. In this case, if you have set -**Recycle Current Volume** (Dir configuration, Pool resource) = +:raw-latex:`\linkResourceDirective{Dir}{Pool}{Recycle Current Volume}` = yes and the Volume is marked as Used or Full, Bareos will prune the volume and if all jobs were removed during the pruning (respecting the retention periods), the Volume will be recycled and used. The recycling algorithm in this case is: -- If the Volume status is **Append** or - **Recycle**, the volume will be used. +- If the Volume status is :raw-latex:`\volumestatus{Append}` or + :raw-latex:`\volumestatus{Recycle}`, the volume will be used. - If - **Recycle Current Volume** (Dir configuration, Pool resource) - = yes and the volume is marked **Full** or - **Used**, Bareos will prune the volume + :raw-latex:`\linkResourceDirective{Dir}{Pool}{Recycle Current Volume}` + = yes and the volume is marked :raw-latex:`\volumestatus{Full}` or + :raw-latex:`\volumestatus{Used}`, Bareos will prune the volume (applying the retention period). If all Jobs are pruned from the volume, it will be recycled. @@ -409,21 +381,19 @@ used. A few points from Alan Brown to keep in mind: -- If **Maximum Volumes** (Dir configuration, Pool resource) is +- If :raw-latex:`\linkResourceDirective{Dir}{Pool}{Maximum Volumes}` is not set, Bareos will prefer to demand new volumes over forcibly purging older volumes. - If volumes become free through pruning and the Volume retention period has expired, then they get marked as - **Purged** and are immediately available for + :raw-latex:`\volumestatus{Purged}` and are immediately available for recycling - these will be used in preference to creating new volumes. Recycle Status -------------- -.. index:: General; Recycle Status -.. _`Recycle Status`: - +:raw-latex:`\index[general]{Recycle Status}` Each Volume inherits the Recycle status (yes or no) from the Pool resource record when the Media record is created (normally when the @@ -656,22 +626,10 @@ scheme? Automatic Pruning and Recycling Example --------------------------------------- -.. index:: - triple: General; Automatic; Pruning and Recycling Example -.. _`Automatic`: - -.. index:: - triple: General; Example; Automatic Pruning and Recycling -.. _`Example`: - -.. index:: - triple: General; Pruning!Automatic; Example -.. _`Pruning!Automatic`: - -.. index:: - triple: General; Recycle!Automatic; Example -.. _`Recycle!Automatic`: - +:raw-latex:`\index[general]{Automatic!Pruning and Recycling Example}` +:raw-latex:`\index[general]{Example!Automatic Pruning and Recycling}` +:raw-latex:`\index[general]{Pruning!Automatic!Example}` +:raw-latex:`\index[general]{Recycle!Automatic!Example}` Perhaps the best way to understand the various resource records that come into play during automatic pruning and recycling is to run a Job @@ -781,35 +739,29 @@ comment out the **Schedule** record in the **Job** resource. Manually Recycling Volumes -------------------------- -.. index:: - triple: General; Volume!Recycle; Manual -.. _`Volume!Recycle`: - -.. index:: - triple: General; Recycle; Manual -.. _`Recycle`: - +:raw-latex:`\index[general]{Volume!Recycle!Manual}` +:raw-latex:`\index[general]{Recycle!Manual}` Although automatic recycling of Volumes is implemented (see the -:ref:`RecyclingChapter` chapter of this manual), you may +:raw-latex:`\nameref{RecyclingChapter}` chapter of this manual), you may want to manually force reuse (recycling) of a Volume. Assuming that you want to keep the Volume name, but you simply want to write new data on the tape, the steps to take are: -- Use the :command:`update volume` command in the Console +- Use the :raw-latex:`\bcommand{update}{volume}` command in the Console to ensure that :raw-latex:`\volumeparameter{Recycle}{yes}`. -- Use the :command:`purge jobs volume` command in the - Console to mark the Volume as **Purged**. - Check by using :command:`list volumes`. +- Use the :raw-latex:`\bcommand{purge}{jobs volume}` command in the + Console to mark the Volume as :raw-latex:`\volumestatus{Purged}`. + Check by using :raw-latex:`\bcommand{list}{volumes}`. Once the Volume is marked Purged, it will be recycled the next time a Volume is needed. If you wish to reuse the tape by giving it a new name, use the -:command:`relabel ` instead of the -:command:`purge ` command. +:raw-latex:`\bcommand{relabel}{}` instead of the +:raw-latex:`\bcommand{purge}{}` command. .. raw:: latex diff --git a/docs/manuals/en/new_main_reference/source/releasenotes.rst b/docs/manuals/en/new_main_reference/source/releasenotes.rst index f6ccd62c46b..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/releasenotes.rst +++ b/docs/manuals/en/new_main_reference/source/releasenotes.rst @@ -1,787 +1 @@ - -.. _`releasenotes`: releasenotes .. index:: General; Releases - - -.. _`releasenotes`: releasenotes .. _`Releases`: - - -.. _`releasenotes`: releasenotes - -The technical changelog is automatically generated from the Bareos bug -tracking system, see http://bugs.bareos.org/changelog_page.php. - -Please note, that some of the subreleases are only internal development -releases. - -Open issues for a specific version are shown at -http://bugs.bareos.org/roadmap_page.php. - -The overview about new feature of a release are shown at -https://github.com/bareos/bareos and in the :ref:`index` -of this document. - -This chapter concentrates on things to do when updating an existing -Bareos installation. - -.. raw:: latex - - \warning{While all the source code is published on \elink{GitHub}{https://github.com/bareos/bareos}, the releases of packages on \url{http://download.bareos.org} is limited to the initial versions of a major release. Later maintenance releases are only published on \url{https://download.bareos.com}.} - -.. raw:: latex - - \releasenoteSection{Bareos-17.2} - -.. raw:: latex - - \releasenote{17.2.7}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2018-07-13\\ - Database Version & 2171 (unchanged)\\ - Release Ticket & \ticket{966}\\ - Url & \releaseUrlDownloadBareosCom{17.2} \\ - \end{tabular} - - This release contains several bugfixes and enhancements. Excerpt: - \begin{itemize} - \item \ticket{892} \package{bareos-storage-droplet}: improve error handling on unavailable backend. - \item \ticket{902} \package{bareos-storage-droplet}: improve job status handling (terminate job after all data is written). - \item \ticket{967} \os{Windows}{}: overwrite symbolic links on restore. - \item \ticket{983} \bareosSd: prevent sporadic crash when \linkResourceDirectiveValue{Sd}{Storage}{Collect Job Statistics}{yes}. - \item \os{SLES}{12sp2} and \os{SLES}{12sp3}: provide \package{bareos-storage-ceph} and \package{bareos-filedaemon-ceph-plugin} packages. - - \end{itemize} - - } - -.. raw:: latex - - \releasenote{17.2.6}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2018-06-21\\ - Database Version & 2171 (unchanged)\\ - Release Ticket & \ticket{916}\\ - Url & \releaseUrlDownloadBareosCom{17.2} \\ - \end{tabular} - - This release contains several bugfixes and enhancements. Excerpt: - \begin{itemize} - \item added platforms: \os{Fedora}{27}, \os{Fedora}{28}, \os{openSUSE}{15.0}, \os{Ubuntu}{18.04} and \os{Univention}{4.3}. - \item \os{Univention}{4.3}: fixes integration. - \item \ticket{872} adapted to new Ceph API. - \item \ticket{943} use \package{tirpc} if Sun-RPC is not provided. - \item \ticket{964} fixes the predefined queries. - \item \ticket{969} fixes a problem of restoring more files then selected in \bareosWebui/BVFS. - \item \bareosDir: fixes for a crash after reload in the statistics thread (\ticket{695}, \ticket{903}). - \item \command{bareos-dbcheck}: cleanup and speedup for some some of the checks. - \item adapted for \postgresql 10. - \item gfapi: stale file handles are treated as warnings - \end{itemize} - - } - -.. raw:: latex - - \releasenote{17.2.5}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2018-02-16\\ - Database Version & 2171 (unchanged)\\ - Release Ticket & \ticket{910}\\ - Url & \releaseUrlDownloadBareosCom{17.2} \\ - \end{tabular} - - This release contains several bugfixes and enhancements. Excerpt: - \begin{itemize} - \item \bareosFd is ready for \os{AIX}{7.1.0.0}. - \item \nameref{VMwarePlugin} is also provided for \os{Debian}{9}. - \item NDMP fixes - \item Virtual Backup fixes - \item \package{bareos-storage-droplet}: improvements - \item \command{bareos-dbcheck} improvements and fixes: with older versions it could happen, that it destroys structures required by \bcommand{.bvfs_*}{}. - \item \ticket{850} fixes a bug on \os{Univention}{}: fixes a problem of regenerating passwords when resyncing settings. - \item \ticket{890} \bcommand{.bvfs_update}{} fix. Before there have been cases where it did not update the cache. - \item \bcommand{.bvfs_lsdirs}{} make limit- and offset-option work correctly. - \item \bcommand{.bvfs_lsdirs}{} show special directory (like \path|@bpipe@/|) on the same level as \path|/|. - \item \ticket{895} added description to the output of \bcommand{show}{filesets}. - \item \bareosWebui: Restore Browser fixes - \begin{itemize} - \item There was the possibility of an endless loop if the BVFS API delivers unexpected results. This has been fixed. See bugreports \ticket{887} and \ticket{893} for details. - \item \ticket{905} fixes a problem with file names containing quotes. - \end{itemize} - \item \linkResourceDirective{Dir}{Client}{NDMP Block Size} changed type from \dt{Pint32} to \dt{Size32}. This should not affect any configuration, but is more consistent with other block size configuration directives. - \end{itemize} - - } - -.. raw:: latex - - \releasenote{17.2.4}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2017-12-14\\ - Database Version & 2171\\ - Release Ticket & \ticket{861}\\ - Url & \releaseUrlDownloadBareosOrg{17.2} \\ - & \releaseUrlDownloadBareosCom{17.2} \\ - \end{tabular} - - This release contains several enhancements. Excerpt: - \begin{itemize} - \item Bareos Distribution (packages) - \begin{itemize} - \item \package{python-bareos} is included in the core distribution. - \item \package{bareos-storage-droplet} is a storage backend for the droplet library. - Most notably it allows backup and restores to a S3 environment. - \betaSince{sd}{bareos-storage-droplet}{17.2.4} - \item \package{bat} has been removed, see section \nameref{bat}. - \item platforms: - \begin{itemize} - \item Windows Clients are still supported since Windows Vista. - \item MacOS: added to build chain. - \item \bareosFd is ready for HP-UX 11.31 (ia64). - \item Linux Distribution: Bareos tries to provide packages for all current platforms. For details, refer to \nameref{sec:packages}. - \end{itemize} - \item Linux RPM packages: allow read access to /etc/bareos/ for all users (however, relevant files are still only readable for the user \user{bareos}). - This allows other programs associated with Bareos to also use this directory. - \end{itemize} - - \item Denormalization of the \dbtable{File} database table - \begin{itemize} - \item The denormalization of the \dbtable{File} database table leads to enormous performance improvements in installation, which covering a lot of file (millions and more). - \item For the denormalization the database schema must be modified. - \warning{Updating the database to schema version $\geq$ 2170 will increase the required disk space. - Especially it will require around twice the amount of the current database disk space during the migration.} - \item The \dbtable{Filename} database table does no longer exists. Therefore the \bcommand{.bvfs_*}{} commands do no longer output the \dbcolumn{FilenameId} column. - \end{itemize} - - \item NDMP\_NATIVE support has been added. This include the NDMP features DAR and DDAR. For details see \nameref{sec:NdmpNative}. - \item Updated the package \package{bareos-vmware-plugin} to utilize the Virtual Disk Development Kit (VDDK) 6.5.x. This includes support for \vSphere 6.5 and the next major release (except new features) and backward compatible with \vSphere 5.5 and 6.0. For details see \nameref{VMwarePlugin}. - \item Soft Quota: automatic quota grace period reset if a job does not exceed the quota. - \item \command{bareos-dbcheck}: disable all interactive questions in batch mode. - \item \bcommand{list}{files}: also show deleted files (accurate mode). - \item \bcommand{list}{jobstatastics}: added. - \item \bcommand{purge}{}: added confirmation. - \item \bcommand{list}{volumes}: fix limit and offset handling. - \item \ticket{629} Windows: restore directory attributes. - \item \ticket{639} tape: fix block size handling, AWS VTL iSCSI devices - \item \ticket{705} support for MySQL 5.7 - \item \ticket{719} allow long JSON messages (has been increased from 100KB to 2GB). - \item \ticket{793} Virtual Backups: skip jobs with no files. - \end{itemize} - - } - -.. raw:: latex - - \releasenoteSection{Bareos-16.2} - -.. raw:: latex - - \releasenote{16.2.8}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2018-07-06\\ - Database Version & 2004 (unchanged)\\ - Release Ticket & \ticket{863}\\ - Url & \releaseUrlDownloadBareosCom{16.2} \\ - \end{tabular} - - This release contains several bugfixes and enhancements. Excerpt: - \begin{itemize} - \item gfapi-fd Plugin - \begin{itemize} - \item Allow to use non-accurate backups with glusterfind - \item Fix backups with empty glusterfind filelist. - \item Explicitly close glfs fd on IO-open - \item Don't reinitialize the connection to gluster - \item Fix parsing of missing basedir argument - \item Handle non-fatal Gluster problems properly - \end{itemize} - \item Reset JobStatus to previous JobStatus in status SD and FD loops to fix status all output - \item Backport ceph: ported cephfs-fd and \command{cephfs_device} to new api - \item \ticket{967} Windows: Symbolic links are now replaceable during restore - \end{itemize} - } - -.. raw:: latex - - \releasenote{16.2.7}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2017-10-09\\ - Database Version & 2004 (unchanged)\\ - Release Ticket & \ticket{836}\\ - Url & \releaseUrlDownloadBareosCom{16.2} \\ - \end{tabular} - - This release contains several bugfixes and enhancements. Excerpt: - \begin{itemize} - \item Fixes a Director crash, when enabling debugging output - \item \bcommand{.bvfs_lsdirs}{}: improve performance, especially when having a large number of directories - \begin{itemize} - \item To optimize the performance of the SQL query used by \bcommand{.bvfs_lsdirs}{}, it is important to - have the following indexes: - \item PostgreSQL - \begin{itemize} - \item \sqlcommand{CREATE INDEX file_jpfnidpart_idx ON File(PathId,JobId,FilenameId) WHERE FileIndex = 0;} - \item If the index \sqlcommand{file_jfnidpart_idx} mentioned in 16.2.6 release notes exist, drop it:\\ - \sqlcommand{DROP INDEX file_jfnidpart_idx;} - \end{itemize} - \item MySQL/MariaDB - \begin{itemize} - \item \sqlcommand{CREATE INDEX PathId_JobId_FileNameId_FileIndex ON File(PathId,JobId,FilenameId,FileIndex);} - \item If the index \sqlcommand{PathId_JobId_FileIndex_FileNameId} mentioned in 16.2.6 release notes exist, drop it:\\ - \sqlcommand{DROP INDEX PathId_JobId_FileIndex_FileNameId ON File;} - \end{itemize} - \end{itemize} - \item Utilize OpenSSL $\geq$ 1.1 if available - \item Windows: fixes silent upgrade (\command{winbareos-*.exe /S}) - \item Windows: restore attributes also on directories (not only on files) - \item Fixes problem with SHA1 signature when compiled without OpenSSL (not relevant for bareos.org/bareos.com packages) - \item Packages for openSUSE Leap 42.3 and Fedora 26 have been added. - \item Packages for AIX and current HP-UX 11.31 - \end{itemize} - - } - -.. raw:: latex - - \releasenote{16.2.6}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2017-06-22\\ - Database Version & 2004 (unchanged)\\ - Release Ticket & \ticket{794}\\ - Url & \releaseUrlDownloadBareosCom{16.2} \\ - \end{tabular} - - This release contains several bugfixes and enhancements. Excerpt: - \begin{itemize} - \item Prevent from director crash when using incorrect paramaters of \bcommand{.bvfs_*}{} commands. - \item Director now closes all configuration files when reloading failed. - \item Storage daemon now closes the network connection when MaximumConcurrentJobs reached. - \item New directive \configdirective{LanAddress} was added to the Client and Storage Resources of the director to facilitate a network topology where client and storage are situated inside of a LAN, but the Director is outside of that LAN. See \nameref{LanAddress} for details. - \item A Problem in the storage abstraction layer was fixed where the director picked the wrong storage daemon when multiple storages/storage daemons were used. - \item The device spool size calculation when using secure erase was fixed. - \item \bcommand{.bvfs_lsdirs}{} no longer shows empty directories from accurate jobs. - \begin{itemize} - \item \warning{This decreases performance if your environment has a large numbers of directories. Creating an index improves the performance.} - %In Bareos 16.2.6 the SQL Query used by \bcommand{.bvfs_lsdirs}{} was changed to not show - %empty directories from accurate jobs. It turned out that that the changed - %query causes performance issues when larger amounts of directories were backed up.\\ - \item \postgresql - \begin{itemize} - \item When using PostgreSQL, creating the following partial improves the performance sufficiently:\\ - \sqlcommand{CREATE INDEX file_jfnidpart_idx ON File(JobId, FilenameId) WHERE FileIndex = 0;} - - \item Run following command to create the partial index:\\ - \path!su - postgres -c 'echo "CREATE INDEX file_jfnidpart_idx ON File(JobId, FilenameId) WHERE FileIndex = 0; ANALYZE File;" | psql bareos'! - - \end{itemize} - \item \mysql - \begin{itemize} - \item When using MySQL or MariaDB, creating the following index improves the performance:\\ - \sqlcommand{CREATE INDEX PathId_JobId_FileIndex_FileNameId ON File(PathId,JobId,FileIndex,FilenameId);} - - \item Run following command to create the index:\\ - \path!echo "CREATE INDEX PathId_JobId_FileIndex_FileNameId ON File(PathId,JobId,FileIndex,FilenameId);" | mysql -u root bareos! - - \item However, with larger amounts of directories and/or involved jobs, even with this index - the performance of \bcommand{.bvfs_lsdirs}{} may still be insufficient. We are working on optimizing - the SQL query for MySQL/MariaDB to solve this problem. - \end{itemize} - \end{itemize} - - \item Packages for Univention UCS 4.2 have been added. - \item Packages for Debian 9 (Stretch) have been added. - \item WebUI: The post install script of the bareos-webui RPM package for RHEL/CentOS was fixed, it no longer tries to run a2enmod which does not exist on RHEL/CentOS. - \item WebUI: The login form no longer allows redirects to arbitrary URLs - \item WebUI: The used ZendFramework components were updated from version 2.4.10 to 2.4.11. - \item WebUI: jQuery was updated from version 1.12.4 to version 3.2.0., some outdated browsers like Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ will no longer be supported, see \elink{jQuery Browser Support}{http://jquery.com/browser-support/} for details. - \end{itemize} - - } - -.. raw:: latex - - \releasenote{16.2.5}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2017-03-03\\ - Database Version & 2004 (unchanged)\\ - Release Ticket & \ticket{734}\\ - Url & \releaseUrlDownloadBareosCom{16.2} \\ - \end{tabular} - - This release contains several bugfixes and enhancements. Excerpt: - \begin{itemize} - \item NDMP: critical bugfix when restoring large files. - \item truncate command allows to free space on disk storages (replaces an purged volume by an empty volume). - \item Some fixes were added regarding director crashes, Windows backups (VSS), soft-quota reset and API (bvfs) problems. - \item WebUI: handle file names containing special characters, hostnames starting with numbers and long logfiles. - \item WebUI: adds translations for Chinese, Italian and Spanish. - \end{itemize} - - } - -.. raw:: latex - - \releasenote{16.2.4}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2016-10-28\\ - Database Version & 2004 (unchanged)\\ - Release Ticket & \ticket{698}\\ - Url & \releaseUrlDownloadBareosOrg{16.2} \\ - & \releaseUrlDownloadBareosCom{16.2} \\ - \end{tabular} - - First stable release of the Bareos 16.2 branch. - - \begin{itemize} - \item Configuration - \begin{itemize} - \item Bareos packages contain the default configuration in \nameref{sec:ConfigurationSubdirectories}. Please read \nameref{sec:UpdateToConfigurationSubdirectories} before updating (make a copy of your configuration directories for your \bareosDir and \bareosSd before updating). Note: as the old configuration files are still supported, in most cases no changes are required. - \item The default configuration does no longer name the \resourcetype{Dir}{Director} and \resourcetype{Sd}{Storage} resources after the systems hostname (\path|$HOSTNAME-dir| resp. \path|$HOSTNAME-sd|) but use \resourcename{Dir}{Director}{bareos-dir} resp. \resourcename{Sd}{Storage}{bareos-sd} as defaults. The prior solution had the disadvantage, that \path|$HOSTNAME-dir|\hide{$} has also been set on \bareosFd not running on the \bareosDir, which almost ever did require changing this setting. Also the new approach aligns better with \nameref{sec:ConfigurationSubdirectories}. - \item Due to limitation of the build system, the default resource \resourcename{Dir}{FileSet}{Linux All} have been renamed to \resourcename{Dir}{FileSet}{LinuxAll} (no space between Linux and All). - \item The configuration of the \package{bareos-traymonitor} has also been split into resource files. - Additional, these resource files are now packaged in other packages: - \begin{itemize} - \item \path|$CONFIGDIR/tray-monitor.d/monitor/bareos-mon.conf|: \package{bareos-traymonitor} - \item \path|$CONFIGDIR/tray-monitor.d/client/FileDaemon-local.conf|: \package{bareos-filedaemon} - \item \path|$CONFIGDIR/tray-monitor.d/storage/StorageDaemon-local.conf|: \package{bareos-storage} - \item \path|$CONFIGDIR/tray-monitor.d/director/Director-local.conf|: \file{bareos-director} - \end{itemize} - This way, the \package{bareos-traymonitor} will be configured automatically for the installed components. - \end{itemize} - \item Strict ACL handling - \begin{itemize} - \item Bareos Console \dt{Acl}s do no longer automatically matches substrings - (to avoid that e.g. \linkResourceDirectiveValue{Dir}{Console}{Pool ACL}{Full} also matches \pool{VirtualFull}). - To configure the ACL to work as before, \linkResourceDirectiveValue{Dir}{Console}{Pool ACL}{.*Full.*} must be set. - Unfortunately the \bareosWebui 15.2 \resourcename{Dir}{Profile}{webui} did use \linkResourceDirectiveValue{Dir}{Console}{Command ACL}{.bvfs*}, which is also no longer works as intended. Moreover, to use all of \bareosWebui 16.2 features, some additional commands must be permitted, so best use the new \resourcename{Dir}{Profile}{webui-admin}. - \end{itemize} - \item \bareosWebui - \begin{itemize} - \item Updating from Bareos 15.2: Adapt \resourcename{Dir}{Profile}{webui} (from bareos 15.2) to allow all commands of \resourcename{Dir}{Profile}{webui-admin} (\linkResourceDirective{Dir}{Console}{Command ACL}). - Alternately modify all \resourcetype{Dir}{Console}s currently using \resourcename{Dir}{Profile}{webui} to use \resourcename{Dir}{Profile}{webui-admin} instead. - \item While RHEL 6 and CentOS 6 are still platforms supported by Bareos, the package \package{bareos-webui} is not available for these platforms, as the required ZendFramework 2.4 do require PHP $>=$ 5.3.17 (5.3.23). However, it is possible to use \package{bareos-webui} 15.2 against \package{bareos-director} 16.2. Also here, the profile must be adapted. - \end{itemize} - \end{itemize} - } - -.. raw:: latex - - \releasenoteSection{Bareos-15.2} - -.. raw:: latex - - \releasenote{15.2.4}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2016-06-10\\ - Database Version & 2004 (unchanged)\\ - Release Ticket & \ticket{641} \\ - Url & \releaseUrlDownloadBareosCom{15.2} \\ - \end{tabular} - - For upgrading from 14.2, please see release notes for 15.2.1. - - This release contains several bugfixes and enhancements. Excerpt: - \begin{itemize} - \item Automatic mount of disks by SD - \item NDMP performance enhancements - \item Windows: sparse file restore - \item Director memory leak caused by frequent bconsole calls - \end{itemize} - } - -.. raw:: latex - - \releasenote{15.2.3}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2016-03-11\\ - Database Version & 2004 (unchanged)\\ - Release Ticket & \ticket{625} \\ - Url & \releaseUrlDownloadBareosCom{15.2} \\ - \end{tabular} - - For upgrading from 14.2, please see releasenotes for 15.2.1. - - This release contains several bugfixes and enhancements. Excerpt: - \begin{itemize} - \item VMWare plugin can now restore to VMDK file - \item Ceph support for SLES12 included - \item Multiple gfapi and ceph enhancements - \item NDMP enhancements and bugfixes - \item Windows: multiple VSS Jobs can now run concurrently in one FD, installer fixes - \item bpipe: fix stderr/stdout problems - \item reload command enhancements (limitations eliminated) - \item label barcodes now can run without interaction - \end{itemize} - } - -.. raw:: latex - - \releasenote{15.2.2}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2015-11-19\\ - Database Version & 2004\\ - & Database update required (if coming from bareos-14.2). See the \nameref{bareos-update} section.\\ - Release Ticket & \ticket{554} \\ - Url & \releaseUrlDownloadBareosOrg{15.2} \\ - & \releaseUrlDownloadBareosCom{15.2} \\ - \end{tabular} - - First stable release of the Bareos 15.2 branch. - - When coming from bareos-14.2.x, the following things have changed (same as in bareos-15.2.1): - \begin{itemize} - \item The default setting for the Bacula Compatbile mode in \linkResourceDirective{Fd}{Client}{Compatible} and \linkResourceDirective{Sd}{Storage}{Compatible} have been changed from \argument{yes} to \argument{no}. - \item The configuration syntax for Storage Daemon Cloud Backends Ceph and GlusterFS have changed. - Before bareos-15.2, options have been configured as part of the \linkResourceDirective{Sd}{Device}{Archive Device} directive, while now the Archive Device contains only information text and options are defined via the \linkResourceDirective{Sd}{Device}{Device Options} directive. See examples in \linkResourceDirective{Sd}{Device}{Device Options}. - \end{itemize} - - } - -.. raw:: latex - - \releasenoteUnstable{15.2.1}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2015-09-16\\ - Database Version & 2004\\ - & Database update required, see the \nameref{bareos-update} section.\\ - Release Ticket & \ticket{501} \\ - Url & \releaseUrlDownloadBareosOrg{15.2} \\ - \end{tabular} - - Beta release. - - \begin{itemize} - \item The default setting for the Bacula Compatbile mode in \linkResourceDirective{Fd}{Client}{Compatible} and \linkResourceDirective{Sd}{Storage}{Compatible} have been changed from \argument{yes} to \argument{no}. - \item The configuration syntax for Storage Daemon Cloud Backends Ceph and GlusterFS have changed. - Before bareos-15.2, options have been configured as part of the \linkResourceDirective{Sd}{Device}{Archive Device} directive, while now the Archive Device contains only information text and options are defined via the \linkResourceDirective{Sd}{Device}{Device Options} directive. See examples in \linkResourceDirective{Sd}{Device}{Device Options}. - % # Old syntax: - % # Archive Device = /etc/ceph/ceph.conf:poolname - % # - % # New syntax: - % # Archive Device = - % # Device Options = "conffile=/etc/ceph/ceph.conf,poolname=poolname" - \end{itemize} - - } - -.. raw:: latex - - \releasenoteSection{Bareos-14.2} - -It is known, that :command:`drop_database` scripts will not -longer work on PostgreSQL :math:`<` 8.4. However, as -:command:`drop_database` scripts are very seldom needed, -package dependencies do not yet enforce PostgreSQL :math:`>=` 8.4. We -plan to ensure this in future version of Bareos. - -.. raw:: latex - - \releasenote{14.2.7}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2016-07-11\\ - Database Version & 2003 (unchanged)\\ - Release Ticket & \ticket{584} \\ - Url & \releaseUrlDownloadBareosCom{14.2} \\ - \end{tabular} - - This release contains several bugfixes. Excerpt: - \begin{itemize} - \item bareos-dir - \begin{itemize} - \item Fixes pretty printing of Fileset options block \\ - \ticket{591}: config pretty-printer does not print filesets correctly - \item run command: fixes changing the pool when changing the backup level in interactive mode \\ - \ticket{633}: Interactive run doesn't update pool on level change - \item Ignore the Fileset option DriveType on non Windows systems \\ - \ticket{644}: Setting DriveType causes empty backups on Linux - \item Suppress already queued jobs for disabled schedules \\ - \ticket{659}: Suppress already queued jobs for disabled schedules - \end{itemize} - \item NDMP - \begin{itemize} - \item Fixes cancel of NDMP jobs\\ - \ticket{604}: Cancel a NDMP Job causes the sd to crash - \end{itemize} - \item bpipe-fd plugin - \begin{itemize} - \item Only take stdout into account, ignore stderr (like earlier versions) \\ - \ticket{632}: fd-bpipe plugin merges stderr with stdout, which can result in corrupted backups - \end{itemize} - \item win32 - \begin{itemize} - \item Fix symlink and junction support\\ - \ticket{575}: charset problem in symlinks/junctions windows restore \\ - \ticket{615}: symlinks/junctions wrong target path on restore (wide chars) - \item Fixes quoting for bmail.exe in bareos-dir.conf \\ - \ticket{581}: Installer is setting up a wrong path to bmail.exe without quotes / bmail not called - \item Fix crash on restore of sparse files \\ - \ticket{640}: File daemon crashed after restoring sparse file on windows - \end{itemize} - \item win32 mssql plugin - \begin{itemize} - \item Allow connecting to non default instance \\ - \ticket{383}: mssqldvi problem with connection to mssql not default instance - \item Fix backup/restore of incremental backups \\ - \ticket{588}: Incremental MSSQL backup fails when database name contains spaces - \end{itemize} - \end{itemize} - } - -.. raw:: latex - - \releasenote{14.2.6}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2015-12-03\\ - Database Version & 2003 (unchanged)\\ - Release Ticket & \ticket{474} \\ - Url & \releaseUrlDownloadBareosCom{14.2} \\ - \end{tabular} - - This release contains several bugfixes. - } - -.. raw:: latex - - \releasenote{14.2.5}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2015-06-01\\ - Database Version & 2003 (unchanged)\\ - Release Ticket & \ticket{447} \\ - Url & \releaseUrlDownloadBareosCom{14.2} \\ - \end{tabular} - - This release contains several bugfixes and added the platforms \os{Debian}{8} and \os{Fedora}{21}. - } - -.. raw:: latex - - \releasenote{14.2.4}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2015-03-23 \\ - Database Version & 2003 (unchanged)\\ - Release Ticket & \ticket{420} \\ - Url & \releaseUrlDownloadBareosCom{14.2} \\ - \end{tabular} - - This release contains several bugfixes, including one major bugfix (\ticket{437}), relevant for those of you using backup to disk with autolabeling enabled. - - It can lead to loss of a 64k block of data when all of this conditions apply: - \begin{itemize} - \item backups are written to disk (tape backups are not affected) - \item autolabelling is enabled - \item a backup spans over multiple volumes - \item the additional volumes are newly created and labeled during the backup - \end{itemize} - If existing volumes are used for backups spanning over multiple volumes, the problem does not occur. - - We recommend to update to the latest packages as soon as possible. - - If an update is not possible immediately, - autolabeling should be disabled and volumes should be labelled manually - until the update can be installed. - - If you are affected by the 64k bug, we recommend that you schedule a full backup after fixing the problem in order to get a - proper full backup of all files. - } - -.. raw:: latex - - \releasenote{14.2.3}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2015-02-02 \\ - Database Version & 2003 (unchanged)\\ - Release Ticket & \ticket{393}\\ - Url & \releaseUrlDownloadBareosCom{14.2} \\ - \end{tabular} - - } - -.. raw:: latex - - \releasenote{14.2.2}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2014-12-12 \\ - Database Version & 2003 (unchanged)\\ - & Database update required if updating from version $<$ 14.2.\\ - & See the \nameref{bareos-update} section for details.\\ - Url & \releaseUrlDownloadBareosOrg{14.2} \\ - & \releaseUrlDownloadBareosCom{14.2} \\ - \end{tabular} - - First stable release of the Bareos 14.2 branch. - } - -.. raw:: latex - - \releasenoteUnstable{14.2.1}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2014-09-22 \\ - Database Version & 2003\\ - & Database update required, see the \nameref{bareos-update} section.\\ - Url & \releaseUrlDownloadBareosOrg{14.2} \\ - \end{tabular} - - Beta release. - } - -.. raw:: latex - - \releasenoteSection{Bareos-13.2} - -.. raw:: latex - - \releasenote{13.2.5}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2015-12-03 \\ - Database Version & 2002 (unchanged)\\ - Url & \releaseUrlDownloadBareosCom{13.2} \\ - \end{tabular} - - This release contains several bugfixes. - } - -.. raw:: latex - - \releasenote{13.2.4}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2014-11-05 \\ - Database Version & 2002 (unchanged)\\ - Url & \releaseUrlDownloadBareosCom{13.2} \\ - \end{tabular} - } - -.. raw:: latex - - \releasenote{13.2.3}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2014-03-11 \\ - Database Version & 2002\\ - & Database update required, see the \nameref{bareos-update} section.\\ - Url & \releaseUrlDownloadBareosCom{13.2} \\ - \end{tabular} - - It is known, that \command{drop_database} scripts will not longer work on PostgreSQL $<$ 8.4. However, as \command{drop_database} scripts are very seldom needed, package dependencies do not yet enforce PostgreSQL $>=$ 8.4. We plan to ensure this in future version of Bareos. - } - -.. raw:: latex - - \releasenote{13.2.2}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2013-11-19 \\ - Database Version & 2001 (unchanged)\\ - Url & \releaseUrlDownloadBareosOrg{13.2} \\ - & \releaseUrlDownloadBareosCom{13.2} \\ - \end{tabular} - } - -.. raw:: latex - - \releasenoteSection{Bareos-12.4} - -.. raw:: latex - - \releasenote{12.4.8}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2015-11-18 \\ - Database Version & 2001 (unchanged)\\ - Url & \releaseUrlDownloadBareosCom{12.4} \\ - \end{tabular} - - This release contains several bugfixes. - } - -.. raw:: latex - - \releasenote{12.4.6}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2013-11-19 \\ - Database Version & 2001 (unchanged)\\ - Url & \releaseUrlDownloadBareosOrg{12.4} \\ - & \releaseUrlDownloadBareosCom{12.4} \\ - \end{tabular} - } - -.. raw:: latex - - \releasenote{12.4.5}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2013-09-10 \\ - Database Version & 2001 (unchanged)\\ - Url & \releaseUrlDownloadBareosCom{12.4} \\ - \end{tabular} - } - -.. raw:: latex - - \releasenote{12.4.4}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2013-06-17 \\ - Database Version & 2001 (unchanged)\\ - Url & \releaseUrlDownloadBareosOrg{12.4} \\ - & \releaseUrlDownloadBareosCom{12.4} \\ - \end{tabular} - } - -.. raw:: latex - - \releasenote{12.4.3}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2013-04-15 \\ - Database Version & 2001 (unchanged)\\ - Url & \releaseUrlDownloadBareosOrg{12.4} \\ - & \releaseUrlDownloadBareosCom{12.4} \\ - \end{tabular} - } - -.. raw:: latex - - \releasenote{12.4.2}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2013-03-03 \\ - Database Version & 2001 (unchanged)\\ - \end{tabular} - } - -.. raw:: latex - - \releasenote{12.4.1}{ - - \begin{tabular}{p{0.2\textwidth} p{0.8\textwidth}} - Code Release & 2013-02-06 \\ - Database Version & 2001 (initial)\\ - \end{tabular} - - This have been the initial release of Bareos. - - Information about migrating from Bacula to Bareos are available at \elink{Howto upgrade from Bacula to Bareos}{http://www.bareos.org/en/HOWTO/articles/upgrade_bacula_bareos.html} and in section \nameref{compat-bacula}. - } diff --git a/docs/manuals/en/new_main_reference/source/requirements.rst b/docs/manuals/en/new_main_reference/source/requirements.rst index 7307c99b2f9..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/requirements.rst +++ b/docs/manuals/en/new_main_reference/source/requirements.rst @@ -1,47 +1 @@ -.. _SysReqs: -System Requirements -=================== - -.. index:: General; System Requirements -.. _`System Requirements`: - -.. index:: - triple: General; Requirements; System -.. _`Requirements`: - - -- The minimum versions for each of the databases supported by Bareos - are: - - - PostgreSQL 8.4 (since Bareos 13.2.3) - - - MySQL 4.1 - 5.6 or compatible fork (e.g. MariaDB), see - :ref:`sec:MysqlSupport` - - - SQLite 3 - -- Windows release is cross-compiled on Linux - -- Bareos requires a good implementation of pthreads to work. This is - not the case on some of the BSD systems. - -- The source code has been written with portability in mind and is - mostly POSIX compatible. Thus porting to any POSIX compatible - operating system should be relatively easy. - -- Jansson library: - -.. _`jansson`: jansson - .. index:: General; JSON - .. _`JSON`: - - .. index:: - triple: General; Jansson; \see{JSON} - .. _`Jansson`: - Bareos - 15.2.0 offers a - JSON API mode, see :raw-latex:`\bareosDeveloperGuideApiModeJson`. On - some platform, the Jansson library is directory available. On others - it can easly be added. For some older platforms, we compile Bareos - without JSON API mode. diff --git a/docs/manuals/en/new_main_reference/source/rescue.rst b/docs/manuals/en/new_main_reference/source/rescue.rst index 9a9e0d9c706..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/rescue.rst +++ b/docs/manuals/en/new_main_reference/source/rescue.rst @@ -1,415 +1 @@ -.. _`Disaster Recovery`: -Disaster Recovery Using Bareos -============================== -.. index:: - triple: General; Disaster; Recovery - -.. index:: - triple: General; Recovery; Disaster Recovery - -General -------- - -When disaster strikes, you must have a plan, and you must have prepared -in advance, otherwise the work of recovering your system and your files -will be considerably greater. For example, if you have not previously -saved the partitioning information for your hard disk, how can you -properly rebuild it if the disk must be replaced? - -Unfortunately, many of the steps one must take before and immediately -after a disaster are very much dependent on the operating system in use. -As a consequence, this chapter will discuss in detail disaster recovery -only for selected operating systems. - -Important Considerations -~~~~~~~~~~~~~~~~~~~~~~~~ - -Here are a few important considerations concerning disaster recovery -that you should take into account before a disaster strikes. - -- If the building which houses your computers burns down or is - otherwise destroyed, do you have off-site backup data? - -- Disaster recovery is much easier if you have several machines. If you - have a single machine, how will you handle unforeseen events if your - only machine is down? - -- Do you want to protect your whole system and use Bareos to recover - everything? Or do you want to try to restore your system from the - original installation disks, apply any other updates and only restore - the user files? - -Steps to Take Before Disaster Strikes -------------------------------------- - - -.. index:: - triple: General; Disaster; Before - -- Create a rescue or CDROM for your systems. Generally, they are - offered by each distribution, and there are many good rescue disks on - the Web - -- Ensure that you always have a valid bootstrap file for your backup - and that it is saved to an alternate machine. This will permit you to - easily do a full restore of your system. - -- If possible copy your catalog nightly to an alternate machine. If you - have a valid bootstrap file, this is not necessary, but can be very - useful if you do not want to reload everything. - -- Ensure that you always have a valid - :ref:`bootstrap BootstrapChapter` file for your - catalog backup that is saved to an alternate machine. This will - permit you to restore your catalog more easily if needed. - -- Try out how to use the Rescue CDROM before you are forced to use it - in an emergency situation. - -- Make a copy of your Bareos .conf files, particularly your - bareos-dir.conf, and your bareos-sd.conf files, because if your - server goes down, these files will be needed to get it back up and - running, and they can be difficult to rebuild from memory. - -Bare Metal Recovery of Bareos Clients -------------------------------------- - -A so called “Bare Metal” recovery is one where you start with an empty -hard disk and you restore your machine. - -Generally, following components are required for a Bare Metal Recovery: - -- A rescue CDROM containing a copy of your OS and including the Bareos - File daemon, including all libraries - -- The Bareos client configuration files - -- Useful: a copy of your hard disk information - -- A full Bareos backup of your system - -Linux -~~~~~ - - -.. index:: - triple: General; Disaster!Recovery; Linux - -From the Relax-and-Recover web site -(http://relax-and-recover.org): - - Relax-and-Recover is a setup-and-forget Linux bare metal disaster - recovery solution. It is easy to set up and requires no maintenance - so there is no excuse for not using it. - -Relax-and-Recover (ReaR) is quite easy to use with Bareos. - -Installation -^^^^^^^^^^^^ - -Bareos is a supported backend for ReaR :math:`>=` 1.15. To use the -**BAREOS_CLIENT** option, ReaR :math:`>=` 1.17 is -required. If ReaR :math:`>=` 1.17 is not part of your distribution, -check the :raw-latex:`\elink{download section on the -ReaR website}{http://relax-and-recover.org/download/}`. - -Configuration -^^^^^^^^^^^^^ - -Assuming you have a working Bareos configuration on the system you want -to protect with ReaR and Bareos references this system by the name -**bareosclient-fd**, the only configuration for -ReaR is: - -.. raw:: latex - - \begin{config}{} - BACKUP=BAREOS - BAREOS_CLIENT=bareosclient-fd - \end{config} - -You also need to specify in your ReaR configuration file -(*/etc/rear/local.conf*) where you want to store your -recovery images. Please refer to the -http://relax-and-recover.org/documentation/ -for details. - -For example, if you want to create an ISO image and store it to an NFS -server with the IP Address 192.168.10.1, you can use the following -configuration: - -.. raw:: latex - - \begin{config}{Full Rear configuration in /etc/rear/local.conf} - # This is default: - #OUTPUT=ISO - # Where to write the iso image - # You can use NFS, if you want to write your iso image to a nfs server - # If you leave this blank, it will - # be written to: /var/lib/rear/output/ - OUTPUT_URL=nfs://192.168.10.1/rear - BACKUP=BAREOS - BAREOS_CLIENT=bareosclient-fd - \end{config} - -Backup -^^^^^^ - -If you have installed and configured ReaR on your system, type - -.. raw:: latex - - \begin{commands}{Create Rescue Image} - rear -v mkrescue - \end{commands} - -to create the rescue image. If you used the configuration example above, -you will get a bootable ISO image which can be burned onto a CD. - -:raw-latex:`\warning{This will not create a Bareos backup on your system! You will have to do that by -other means, e.g. by a regular Bareos backup schedule. -Also \command{rear mkbackup} will not create a backup. -In this configuration it will only create the rescue ISO -(same as the \command{rear mkrescue} command).}` - -Recovery -^^^^^^^^ - -In case, you want to recover your system, boot it using the generated -ReaR recovery ISO. After booting log in as user **root** -and type - -.. raw:: latex - - \begin{commands}{Restore your system using Rear and Bareos} - rear recover - \end{commands} - -ReaR will now use the most recent backup from Bareos to restore your -system. When the restore job has finished, ReaR will start a new shell -which you can use to verify if the system has been restored correctly. -The restored system can be found under the -*/mnt/local* -verification, type ’exit’ to leave the shell, getting back to the -recovery process. Finally, you will be asked to confirm that everything -is correct. Type ’yes’ to continue. After that, ReaR will restore your -bootloader. Recovery is complete. - -:raw-latex:`\hide{ -\subsection{FreeBSD} -\label{FreeBSD1} -\index[general]{Disaster!Recovery!FreeBSD} -\index[general]{FreeBSD!Disaster Recovery} - -The same basic techniques described above also apply to FreeBSD. Although we -don't yet have a fully automated procedure, Alex Torres Molina has provided us -with the following instructions with a few additions from Jesse Guardiani and -Dan Langille: - -\begin{enumerate} -\item Boot with the FreeBSD installation disk -\item Go to Custom, Partition and create your slices and go to Label and - create the partitions that you want. Apply changes. -\item Go to Fixit to start an emergency console. -\item Create devs ad0 .. .. if they don't exist under /mnt2/dev (in my situation) - with MAKEDEV. The device or devices you create depend on what hard drives you - have. ad0 is your first ATA drive. da0 would by your first SCSI drive. Under -OS version 5 and greater, your device files are most likely automatically -created for you. -\item mkdir /mnt/disk - this is the root of the new disk -\item mount /mnt2/dev/ad0s1a /mnt/disk - mount /mnt2/dev/ad0s1c /mnt/disk/var - mount /mnt2/dev/ad0s1d /mnt/disk/usr -..... -The same hard drive issues as above apply here too. Note, under OS version 5 -or higher, your disk devices may be in /dev not /mnt2/dev. -\item Network configuration (ifconfig xl0 ip/mask + route add default - ip-gateway) -\item mkdir /mnt/disk/tmp -\item cd /mnt/disk/tmp -\item Copy bareos-fd and bareos-fd.conf to this path -\item If you need to, use sftp to copy files, after which you must do this: - ln -s /mnt2/usr/bin /usr/bin -\item chmod u+x bareos-fd -\item Modify bareos-fd.conf to fit this machine -\item Copy /bin/sh to /mnt/disk, necessary for chroot -\item Don't forget to put your bareos-dir's IP address and domain name in - /mnt/disk/etc/hosts if it's not on a public net. Otherwise the FD on the - machine you are restoring to won't be able to contact the SD and DIR on the -remote machine. -\item mkdir -p /mnt/disk/var/db/bareos -\item chroot /mnt/disk /tmp/bareos-fd -c /tmp/bareos-fd.conf - to start bareos-fd -\item Now you can go to bareos-dir and restore the job with the entire - contents of the broken server. -\item You must create /proc -\end{enumerate} -}` - -:raw-latex:`\hide{ -\subsection{Solaris} -\label{solaris} -\index[general]{Solaris!Disaster Recovery} -\index[general]{Disaster!Recovery!Solaris} - -The same basic techniques described above apply to Solaris: - -\begin{itemize} -\item the same restrictions as those given for Linux apply -\item you will need to create a Rescue disk - \end{itemize} - -However, during the recovery phase, the boot and disk preparation procedures -are different: - -\begin{itemize} -\item there is no need to create an emergency boot disk since it is an - integrated part of the Solaris boot. -\item you must partition and format your hard disk by hand following manual - procedures as described in W. Curtis Preston's book "Unix Backup \& - Recovery" -\end{itemize} - -Once the disk is partitioned, formatted and mounted, you can continue with -bringing up the network and reloading Bareos. - -\subsubsection{Preparing Solaris Before a Disaster} - -As mentioned above, before a disaster strikes, you should prepare the -information needed in the case of problems. To do so, in the {\bf -rescue/solaris} subdirectory enter: - -\footnotesize -\begin{verbatim} -su -./getdiskinfo -./make_rescue_disk -\end{verbatim} -\normalsize - -The {\bf getdiskinfo} script will, as in the case of Linux described above, -create a subdirectory {\bf diskinfo} containing the output from several system -utilities. In addition, it will contain the output from the {\bf SysAudit} -program as described in Curtis Preston's book. This file {\bf -diskinfo/sysaudit.bsi} will contain the disk partitioning information that -will allow you to manually follow the procedures in the "Unix Backup \& -Recovery" book to repartition and format your hard disk. In addition, the -{\bf getdiskinfo} script will create a {\bf start\_network} script. - -Once you have your disks repartitioned and formatted, do the following: - -\begin{itemize} -\item Start Your Network with the {\bf start\_network} script -\item Restore the Bareos File daemon as documented above -\item Perform a Bareos restore of all your files using the same commands as - described above for Linux -\item Re-install your boot loader using the instructions outlined in the - "Unix Backup \& Recovery" book using installboot -\end{itemize} -}` - -:raw-latex:`\hide{ -\subsection{Windows} -\label{Win3233} -\index[general]{Disaster!Recovery!Windows} -\index[general]{Windows!Disaster Recovery} - -Due to open system files, and registry problems, Bareos cannot save and -restore a complete Win2K/XP/NT environment. - -A suggestion by Damian Coutts using Microsoft's NTBackup utility in -conjunction with Bareos should permit a Full bare metal restore of Win2K/XP -(and possibly NT systems). His suggestion is to do an NTBackup of the critical -system state prior to running a Bareos backup with the following command: - -\footnotesize -\begin{verbatim} -ntbackup backup systemstate /F c:\systemstate.bkf -\end{verbatim} -\normalsize - -The {\bf backup} is the command, the {\bf systemstate} says to backup only the -system state and not all the user files, and the {\bf /F -c:\textbackslash{}systemstate.bkf} specifies where to write the state file. -this file must then be saved and restored by Bareos. This command -can be put in a Client Run Before Job directive so that it is automatically -run during each backup, and thus saved to a Bareos Volume. - -To restore the system state, you first reload a base operating system, then -you would use Bareos to restore all the users files and to recover the {\bf -c:\textbackslash{}systemstate.bkf} file, and finally, run {\bf NTBackup} and -{\bf catalogue} the system statefile, and then select it for restore. The -documentation says you can't run a command line restore of the systemstate. - -This procedure has been confirmed to work by Ludovic Strappazon -- many -thanks! -}` - -Restoring a Bareos Server -------------------------- - - -.. index:: - triple: General; Restore; Bareos Server -.. _sec:RestoreServer: - -Above, we considered how to recover a client machine where a valid -Bareos server was running on another machine. However, what happens if -your server goes down and you no longer have a running Director, -Catalog, or Storage daemon? There are several solutions: - -#. Bring up static versions of your Director, Catalog, and Storage - daemon on the damaged machine. - -#. Move your server to another machine. - -#. Use a Hot Spare Server on another Machine. - -The first option, is very difficult because it requires you to have -created a static version of the Director and the Storage daemon as well -as the Catalog. If the Catalog uses MySQL or PostgreSQL, this may or may -not be possible. In addition, to loading all these programs on a bare -system (quite possible), you will need to make sure you have a valid -driver for your tape drive. - -The second suggestion is probably a much simpler solution, and one I -have done myself. To do so, you might want to consider the following -steps: - -- Install the same database server as on the original system. - -- Install Bareos and initialize the Bareos database. - -- Ideally, you will have a copy of all the Bareos conf files that were - being used on your server. If not, you will at a minimum need create - a bareos-dir.conf that has the same Client resource that was used to - backup your system. - -- If you have a valid saved Bootstrap file as created for your damaged - machine with WriteBootstrap, use it to restore the files to the - damaged machine, where you have loaded a static Bareos File daemon - using the Rescue disk). This is done by using the restore command and - at the yes/mod/no prompt, selecting **mod** then specifying the path - to the bootstrap file. - -- If you have the Bootstrap file, you should now be back up and - running, if you do not have a Bootstrap file, continue with the - suggestions below. - -- Using **bscan** scan the last set of backup tapes into your MySQL, - PostgreSQL or SQLite database. - -- Start Bareos, and using the Console **restore** command, restore the - last valid copy of the Bareos database and the Bareos configuration - files. - -- Move the database to the correct location. - -- Start the database, and restart Bareos. Then use the Console - **restore** command, restore all the files on the damaged machine, - where you have loaded a Bareos File daemon using the Rescue disk. - -For additional details of restoring your database, please see the -:ref:`sec:RestoreCatalog` chapter. diff --git a/docs/manuals/en/new_main_reference/source/restore.rst b/docs/manuals/en/new_main_reference/source/restore.rst index 6da73ed1238..6b07d82f8d9 100644 --- a/docs/manuals/en/new_main_reference/source/restore.rst +++ b/docs/manuals/en/new_main_reference/source/restore.rst @@ -3,9 +3,7 @@ The Restore Command =================== -.. index:: General; Restore -.. _`Restore`: - +:raw-latex:`\index[general]{Restore}` General ------- @@ -16,7 +14,7 @@ not possible to restore files by automatically starting a job as you do with Backup, Verify, ... jobs. However, in addition to the console restore command, there is a standalone program named **bextract**, which also permits restoring files. For more information on this program, -please see the :ref:`bextract Bareos Utility Programs` +please see the :raw-latex:`\ilink{Bareos Utility Programs}{bextract}` chapter of this manual. We don’t particularly recommend the **bextract** program because it lacks many of the features of the normal Bareos restore, such as the ability to restore Win32 files to Unix systems, and @@ -28,7 +26,7 @@ You may also want to look at the **bls** program in the same chapter, which allows you to list the contents of your Volumes. Finally, if you have an old Volume that is no longer in the catalog, you can restore the catalog entries using the program named **bscan**, documented in the -same :ref:`bscan Bareos Utility Programs` chapter. +same :raw-latex:`\ilink{Bareos Utility Programs}{bscan}` chapter. In general, to restore a file or a set of files, you must run a **restore** job. That is a job with **Type = Restore**. As a @@ -57,10 +55,7 @@ you to run the job by selecting the **mod** option. The Restore Command ------------------- -.. index:: - triple: General; Console!Command; restore -.. _`Console!Command`: - +:raw-latex:`\index[general]{Console!Command!restore}` Since Bareos maintains a catalog of your files and on which Volumes (disk or tape), they are stored, it can do most of the bookkeeping work, @@ -80,37 +75,36 @@ If a Job’s file records have been pruned from the catalog, the **restore** command will be unable to find any files to restore. Bareos will ask if you want to restore all of them or if you want to use a regular expression to restore only a selection while reading media. See -:ref:`FileRegex FileRegex option` and below for more +:raw-latex:`\ilink{FileRegex option}{FileRegex}` and below for more details on this. Within the Console program, after entering the **restore** command, you are presented with the following selection prompt: -.. raw:: latex +:: - \begin{bconsole}{restore} - * restore - First you select one or more JobIds that contain files - to be restored. You will be presented several methods - of specifying the JobIds. Then you will be allowed to - select which files from those JobIds are to be restored. - - To select the JobIds, you have the following choices: - 1: List last 20 Jobs run - 2: List Jobs where a given File is saved - 3: Enter list of comma separated JobIds to select - 4: Enter SQL list command - 5: Select the most recent backup for a client - 6: Select backup for a client before a specified time - 7: Enter a list of files to restore - 8: Enter a list of files to restore before a specified time - 9: Find the JobIds of the most recent backup for a client - 10: Find the JobIds for a backup for a client before a specified time - 11: Enter a list of directories to restore for found JobIds - 12: Select full restore to a specified Job date - 13: Cancel - Select item: (1-13): - \end{bconsole} + {restore} + * restore + First you select one or more JobIds that contain files + to be restored. You will be presented several methods + of specifying the JobIds. Then you will be allowed to + select which files from those JobIds are to be restored. + + To select the JobIds, you have the following choices: + 1: List last 20 Jobs run + 2: List Jobs where a given File is saved + 3: Enter list of comma separated JobIds to select + 4: Enter SQL list command + 5: Select the most recent backup for a client + 6: Select backup for a client before a specified time + 7: Enter a list of files to restore + 8: Enter a list of files to restore before a specified time + 9: Find the JobIds of the most recent backup for a client + 10: Find the JobIds for a backup for a client before a specified time + 11: Enter a list of directories to restore for found JobIds + 12: Select full restore to a specified Job date + 13: Cancel + Select item: (1-13): There are a lot of options, and as a point of reference, most people will want to select item 5 (the most recent backup for a client). The @@ -198,9 +192,7 @@ details of the above options are: before date (as with item 6). These JobIds will then be retained internally. - .. index:: General; Restore Directories - .. _`Restore Directories`: - + :raw-latex:`\index[general]{Restore Directories}` - Item 11 allows you to enter a list of JobIds from which you can select directories to be restored. The list of JobIds can have been @@ -220,22 +212,21 @@ state). If you have not specified a client=xxx on the command line, it it will then ask for the desired Client, which on my system, will print all the Clients found in the database as follows: -.. raw:: latex +:: - \begin{bconsole}{restore: select client} - Select item: (1-13): 5 - Defined clients: - 1: Rufus - 2: Matou - 3: Polymatou - 4: Minimatou - 5: Minou - 6: MatouVerify - 7: PmatouVerify - 8: RufusVerify - 9: Watchdog - Select Client (File daemon) resource (1-9): 1 - \end{bconsole} + {restore: select client} + Select item: (1-13): 5 + Defined clients: + 1: Rufus + 2: Matou + 3: Polymatou + 4: Minimatou + 5: Minou + 6: MatouVerify + 7: PmatouVerify + 8: RufusVerify + 9: Watchdog + Select Client (File daemon) resource (1-9): 1 The listed clients are only examples, yours will look differently. If you have only one Client, it will be automatically selected. In this @@ -464,10 +455,7 @@ If you now enter **yes**, Bareos will run the restore Job. Selecting Files by Filename --------------------------- -.. index:: - triple: General; Restore; by filename -.. _`Restore`: - +:raw-latex:`\index[general]{Restore!by filename}` If you have a small number of files to restore, and you know the filenames, you can either put the list of filenames in a file to be read @@ -477,31 +465,30 @@ include the full path and filename. No wild cards are used. To enter the files, after the **restore**, you select item number 7 from the prompt list: -.. raw:: latex +:: - \begin{bconsole}{restore list of files} - * restore - First you select one or more JobIds that contain files - to be restored. You will be presented several methods - of specifying the JobIds. Then you will be allowed to - select which files from those JobIds are to be restored. - - To select the JobIds, you have the following choices: - 1: List last 20 Jobs run - 2: List Jobs where a given File is saved - 3: Enter list of comma separated JobIds to select - 4: Enter SQL list command - 5: Select the most recent backup for a client - 6: Select backup for a client before a specified time - 7: Enter a list of files to restore - 8: Enter a list of files to restore before a specified time - 9: Find the JobIds of the most recent backup for a client - 10: Find the JobIds for a backup for a client before a specified time - 11: Enter a list of directories to restore for found JobIds - 12: Select full restore to a specified Job date - 13: Cancel - Select item: (1-13): 7 - \end{bconsole} + {restore list of files} + * restore + First you select one or more JobIds that contain files + to be restored. You will be presented several methods + of specifying the JobIds. Then you will be allowed to + select which files from those JobIds are to be restored. + + To select the JobIds, you have the following choices: + 1: List last 20 Jobs run + 2: List Jobs where a given File is saved + 3: Enter list of comma separated JobIds to select + 4: Enter SQL list command + 5: Select the most recent backup for a client + 6: Select backup for a client before a specified time + 7: Enter a list of files to restore + 8: Enter a list of files to restore before a specified time + 9: Find the JobIds of the most recent backup for a client + 10: Find the JobIds for a backup for a client before a specified time + 11: Enter a list of directories to restore for found JobIds + 12: Select full restore to a specified Job date + 13: Cancel + Select item: (1-13): 7 which then prompts you for the client name: @@ -592,9 +579,7 @@ Bareos asks you to enter a Job number, this is because you have not yet specified either a Job number or a Bootstrap file. Simply entering zero will allow you to continue and to select another option to be modified. - - -.. _`Replace`: Replace +:raw-latex:`\label{Replace}` Replace Options --------------- @@ -700,7 +685,7 @@ The full list of possible command line arguments are: - **regexwhere=!a.pdf!a.bkp.pdf!** – do complex filename manipulation like with sed unix command. Will overwrite other filename manipulation. For details, see the - :ref:`regexwhere regexwhere` section. + :raw-latex:`\ilink{regexwhere}{regexwhere}` section. - **restorejob=jobname** – Pre-chooses a restore job. Bareos can be configured with multiple restore jobs ("Type = Restore" in the job @@ -712,16 +697,9 @@ The full list of possible command line arguments are: Using File Relocation --------------------- -.. index:: - triple: General; File Relocation; using -.. _`File Relocation`: - - - -.. _`filerelocation`: filerelocation - - -.. _`restorefilerelocation`: restorefilerelocation +:raw-latex:`\index[general]{File Relocation!using}` +:raw-latex:`\label{filerelocation}` +:raw-latex:`\label{restorefilerelocation}` Introduction ~~~~~~~~~~~~ @@ -747,11 +725,11 @@ However, case, you could use the **strip_prefix=/.snap** and original location – that is ``/home/eric/mbox``. To use this feature, there are command line options as described in the -:ref:`restorefilerelocation restore section` of this +:raw-latex:`\ilink{restore section}{restorefilerelocation}` of this manual; you can modify your restore job before running it; or you can add options to your restore job in as described in -**Strip Prefix** (Dir configuration, Job resource) and -**Add Prefix** (Dir configuration, Job resource). +:raw-latex:`\linkResourceDirective{Dir}{Job}{Strip Prefix}` and +:raw-latex:`\linkResourceDirective{Dir}{Job}{Add Prefix}`. :: @@ -823,13 +801,8 @@ Examples Restoring Directory Attributes ------------------------------ -.. index:: - triple: General; Attributes; Restoring Directory -.. _`Attributes`: - -.. index:: General; Restoring Directory Attributes -.. _`Restoring Directory Attributes`: - +:raw-latex:`\index[general]{Attributes!Restoring Directory}` +:raw-latex:`\index[general]{Restoring Directory Attributes}` Depending how you do the restore, you may or may not get the directory entries back to their original state. Here are a few of the problems you @@ -874,18 +847,13 @@ can encounter, and for same machine restores, how to avoid them. (one at a time) to be restored if you want the directory entries properly restored. -.. _sec:RestoreOnWindows: +.. _sec-RestoreOnWindows: Restoring on Windows -------------------- -.. index:: General; Restoring on Windows -.. _`Restoring on Windows`: - -.. index:: - triple: General; Windows; Restoring on -.. _`Windows`: - +:raw-latex:`\index[general]{Restoring on Windows}` +:raw-latex:`\index[general]{Windows!Restoring on}` If you are restoring on Windows systems, Bareos will restore the files with the original ownerships and permissions as would be expected. This @@ -916,13 +884,8 @@ resolves the problem. Restore Errors -------------- -.. index:: - triple: General; Errors; Restore -.. _`Errors`: - -.. index:: General; Restore Errors -.. _`Restore Errors`: - +:raw-latex:`\index[general]{Errors!Restore}` +:raw-latex:`\index[general]{Restore Errors}` There are a number of reasons why there may be restore errors or warning messages. Some of the more common ones are: @@ -953,10 +916,7 @@ file size error Example Restore Job Resource ---------------------------- -.. index:: - triple: General; Resource; Example Restore Job -.. _`Resource`: - +:raw-latex:`\index[general]{Resource!Example Restore Job}` .. raw:: latex @@ -980,20 +940,13 @@ Example Restore Job Resource \normalsize If **Where** is not specified, the default location for restoring files -will be their original locations. - -.. _`Selection`: Selection +will be their original locations. :raw-latex:`\label{Selection}` File Selection Commands ----------------------- -.. index:: - triple: General; Console; File Selection -.. _`Console`: - -.. index:: General; File Selection Commands -.. _`File Selection Commands`: - +:raw-latex:`\index[general]{Console!File Selection}` +:raw-latex:`\index[general]{File Selection Commands}` After you have selected the Jobs to be restored and Bareos has created the in-memory directory tree, you will enter file selection mode as @@ -1008,10 +961,7 @@ restore by marking them with the **mark** command. The available commands are: cd - .. index:: - triple: General; Console!File Selection; cd - .. _`Console!File Selection`: - The **cd** + :raw-latex:`\index[general]{Console!File Selection!cd}` The **cd** command changes the current directory to the argument specified. It operates much like the Unix **cd** command. Wildcard specifications are not permitted. @@ -1023,40 +973,28 @@ cd the first directory. dir - .. index:: - triple: General; Console!File Selection; dir - .. _`Console!File Selection`: - The **dir** + :raw-latex:`\index[general]{Console!File Selection!dir}` The **dir** command is similar to the **ls** command, except that it prints it in long format (all details). This command can be a bit slower than the **ls** command because it must access the catalog database for the detailed information for each file. estimate - .. index:: - triple: General; Console!File Selection; estimate - .. _`Console!File Selection`: - The + :raw-latex:`\index[general]{Console!File Selection!estimate}` The **estimate** command prints a summary of the total files in the tree, how many are marked to be restored, and an estimate of the number of bytes to be restored. This can be useful if you are short on disk space on the machine where the files will be restored. find - .. index:: - triple: General; Console!File Selection; find - .. _`Console!File Selection`: - The + :raw-latex:`\index[general]{Console!File Selection!find}` The **find** command accepts one or more arguments and displays all files in the tree that match that argument. The argument may have wildcards. It is somewhat similar to the Unix command **find / -name arg**. ls - .. index:: - triple: General; Console!File Selection; ls - .. _`Console!File Selection`: - The **ls** + :raw-latex:`\index[general]{Console!File Selection!ls}` The **ls** command produces a listing of all the files contained in the current directory much like the Unix **ls** command. You may specify an argument containing wildcards, in which case only those files will @@ -1067,19 +1005,13 @@ ls forward slash (**/**) to distinguish them from filenames. lsmark - .. index:: - triple: General; Console!File Selection; lsmark - .. _`Console!File Selection`: - The + :raw-latex:`\index[general]{Console!File Selection!lsmark}` The **lsmark** command is the same as the **ls** except that it will print only those files marked for extraction. The other distinction is that it will recursively descend into any directory selected. mark - .. index:: - triple: General; Console!File Selection; mark - .. _`Console!File Selection`: - The + :raw-latex:`\index[general]{Console!File Selection!mark}` The **mark** command allows you to mark files to be restored. It takes a single argument which is the filename or directory name in the current directory to be marked for extraction. The argument may be a @@ -1125,10 +1057,7 @@ mark if some files are marked. unmark - .. index:: - triple: General; Console!File Selection; unmark - .. _`Console!File Selection`: - The + :raw-latex:`\index[general]{Console!File Selection!unmark}` The **unmark** is identical to the **mark** command, except that it unmarks the specified file or files so that they will not be restored. Note: the **unmark** command works from the current @@ -1137,55 +1066,34 @@ unmark everything. pwd - .. index:: - triple: General; Console!File Selection; pwd - .. _`Console!File Selection`: - The **pwd** + :raw-latex:`\index[general]{Console!File Selection!pwd}` The **pwd** command prints the current working directory. It accepts no arguments. count - .. index:: - triple: General; Console!File Selection; count - .. _`Console!File Selection`: - The + :raw-latex:`\index[general]{Console!File Selection!count}` The **count** command prints the total files in the directory tree and the number of files marked to be restored. done - .. index:: - triple: General; Console!File Selection; done - .. _`Console!File Selection`: - This + :raw-latex:`\index[general]{Console!File Selection!done}` This command terminates file selection mode. exit - .. index:: - triple: General; Console!File Selection; exit - .. _`Console!File Selection`: - This + :raw-latex:`\index[general]{Console!File Selection!exit}` This command terminates file selection mode (the same as done). quit - .. index:: - triple: General; Console!File Selection; quit - .. _`Console!File Selection`: - This + :raw-latex:`\index[general]{Console!File Selection!quit}` This command terminates the file selection and does not run the restore job. help - .. index:: - triple: General; Console!File Selection; help - .. _`Console!File Selection`: - This + :raw-latex:`\index[general]{Console!File Selection!help}` This command prints a summary of the commands available. ? - .. index:: - triple: General; Console!File Selection; ? - .. _`Console!File Selection`: - This command + :raw-latex:`\index[general]{Console!File Selection!?}` This command is the same as the **help** command. If your filename contains some weird caracters, you can use ``?``, ``*`` diff --git a/docs/manuals/en/new_main_reference/source/security.rst b/docs/manuals/en/new_main_reference/source/security.rst index 32af72b5fde..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/security.rst +++ b/docs/manuals/en/new_main_reference/source/security.rst @@ -1,366 +1 @@ -Bareos Security Issues -====================== -.. index:: General; Security - -- Security means being able to restore your files, so read the - :ref:`Critical Items Chapter Critical` of this manual. - -- The clients (**bareos-fd**) must run as root to be able to access all - the system files. - -- It is not necessary to run the Director as root. - -- It is not necessary to run the Storage daemon as root, but you must - ensure that it can open the tape drives, which are often restricted - to root access by default. In addition, if you do not run the Storage - daemon as root, it will not be able to automatically set your tape - drive parameters on most OSes since these functions, unfortunately - require root access. - -- You should restrict access to the Bareos configuration files, so that - the passwords are not world-readable. The **Bareos** daemons are - password protected using CRAM-MD5 (i.e. the password is not sent - across the network). This will ensure that not everyone can access - the daemons. It is a reasonably good protection, but can be cracked - by experts. - -- If you are using the recommended ports 9101, 9102, and 9103, you will - probably want to protect these ports from external access using a - firewall and/or using tcp wrappers (**etc/hosts.allow**). - -- By default, all data that is sent across the network is unencrypted. - However, Bareos does support TLS (transport layer security) and can - encrypt transmitted data. Please read the - :ref:`TLS (SSL) Communications Encryption CommEncryption` - section of this manual. - -- You should ensure that the Bareos working directories are readable - and writable only by the Bareos daemons. - -- The default Bareos :command:`grant_bareos_privileges` - script grants all permissions to use the MySQL (and PostgreSQL) - database without a password. If you want security, please tighten - this up! - -- Don’t forget that Bareos is a network program, so anyone anywhere on - the network with the console program and the Director’s password can - access Bareos and the backed up data. - -- You can restrict what IP addresses Bareos will bind to by using the - appropriate **DirAddress**, **FDAddress**, or **SDAddress** records - in the respective daemon configuration files. - -Configuring and Testing TCP Wrappers ------------------------------------- - -.. index:: General; TCP Wrappers - -.. index:: - triple: General; Wrappers; TCP -.. index:: General; libwrappers - -The TCP wrapper functionality is available on different platforms. Be -default, it is activated on Bareos for Linux. With this enabled, you may -control who may access your daemons. This control is done by modifying -the file: **/etc/hosts.allow**. The program name that **Bareos** uses -when applying these access restrictions is the name you specify in the -daemon configuration file (see below for examples). You must not use the -**twist** option in your **/etc/hosts.allow** or it will terminate the -Bareos daemon when a connection is refused. - -:raw-latex:`\hide{ -Dan Langille has provided the following information on configuring and -testing TCP wrappers with Bareos. - -If you read hosts\_options(5), you will see an option called twist. This -option replaces the current process by an instance of the specified shell -command. Typically, something like this is used: - -\footnotesize -\begin{verbatim} -ALL : ALL \ - : severity auth.info \ - : twist /bin/echo "You are not welcome to use %d from %h." -\end{verbatim} -\normalsize - -The libwrap code tries to avoid {\bf twist} if it runs in a resident process, -but that test will not protect the first hosts\_access() call. This will -result in the process (e.g. bareos-fd, bareos-sd, bareos-dir) being terminated -if the first connection to their port results in the twist option being -invoked. The potential, and I stress potential, exists for an attacker to -prevent the daemons from running. This situation is eliminated if your -/etc/hosts.allow file contains an appropriate rule set. The following example -is sufficient: - -\footnotesize -\begin{verbatim} -undef-fd : localhost : allow -undef-sd : localhost : allow -undef-dir : localhost : allow -undef-fd : ALL : deny -undef-sd : ALL : deny -undef-dir : ALL : deny -\end{verbatim} -\normalsize - -You must adjust the names to be the same as the Name directives found -in each of the daemon configuration files. They are, in general, not the -same as the binary daemon names. It is not possible to use the -daemon names because multiple daemons may be running on the same machine -but with different configurations. - -In these examples, the Director is undef-dir, the -Storage Daemon is undef-sd, and the File Daemon is undef-fd. Adjust to suit -your situation. The above example rules assume that the SD, FD, and DIR all -reside on the same box. If you have a remote FD client, then the following -rule set on the remote client will suffice: - -\footnotesize -\begin{verbatim} -undef-fd : director.example.org : allow -undef-fd : ALL : deny -\end{verbatim} -\normalsize - -where director.example.org is the host which will be contacting the client -(ie. the box on which the Bareos Director daemon runs). The use of "ALL : -deny" ensures that the twist option (if present) is not invoked. To properly -test your configuration, start the daemon(s), then attempt to connect from an -IP address which should be able to connect. You should see something like -this: - -\footnotesize -\begin{verbatim} -$ telnet undef 9103 -Trying 192.168.0.56... -Connected to undef.example.org. -Escape character is '^]'. -Connection closed by foreign host. -$ -\end{verbatim} -\normalsize - -This is the correct response. If you see this: - -\footnotesize -\begin{verbatim} -$ telnet undef 9103 -Trying 192.168.0.56... -Connected to undef.example.org. -Escape character is '^]'. -You are not welcome to use undef-sd from xeon.example.org. -Connection closed by foreign host. -$ -\end{verbatim} -\normalsize - -then twist has been invoked and your configuration is not correct and you need -to add the deny statement. It is important to note that your testing must -include restarting the daemons after each connection attempt. You can also -tcpdchk(8) and tcpdmatch(8) to validate your /etc/hosts.allow rules. Here is a -simple test using tcpdmatch: - -\footnotesize -\begin{verbatim} -$ tcpdmatch undef-dir xeon.example.org -warning: undef-dir: no such process name in /etc/inetd.conf -client: hostname xeon.example.org -client: address 192.168.0.18 -server: process undef-dir -matched: /etc/hosts.allow line 40 -option: allow -access: granted -\end{verbatim} -\normalsize - -If you are running Bareos as a standalone daemon, the warning above can be -safely ignored. Here is an example which indicates that your rules are missing -a deny statement and the twist option has been invoked. - -\footnotesize -\begin{verbatim} -$ tcpdmatch undef-dir 10.0.0.1 -warning: undef-dir: no such process name in /etc/inetd.conf -client: address 10.0.0.1 -server: process undef-dir -matched: /etc/hosts.allow line 91 -option: severity auth.info -option: twist /bin/echo "You are not welcome to use - undef-dir from 10.0.0.1." -access: delegated -\end{verbatim} -\normalsize -}` - -:raw-latex:`\hide{ -\section{Running as non-root} -\index[general]{Running as non-root} - -Security advice from Dan Langille: -% TODO: don't use specific name - -% TODO: don't be too specific on operating system - -% TODO: maybe remove personalization? - -It is a good idea to run daemons with the lowest possible privileges. In -other words, if you can, don't run applications as root which do not have to -be root. The Storage Daemon and the Director Daemon do not need to be root. -The File Daemon needs to be root in order to access all files on your system. -In order to run as non-root, you need to create a user and a group. Choosing -{\tt bareos} as both the user name and the group name sounds like a good idea -to me. - -The FreeBSD port creates this user and group for you. -Here is what those entries looked like on my FreeBSD laptop: - -\footnotesize -\begin{verbatim} -bareos:*:1002:1002::0:0:Bareos Daemon:/var/db/bareos:/sbin/nologin -\end{verbatim} -\normalsize - -I used vipw to create this entry. I selected a User ID and Group ID of 1002 -as they were unused on my system. - -I also created a group in /etc/group: - -\footnotesize -\begin{verbatim} -bareos:*:1002: -\end{verbatim} -\normalsize - -The bareos user (as opposed to the Bareos daemon) will have a home directory -of {\tt /var/db/bareos} which is the default location for the Bareos -database. - -Now that you have both a bareos user and a bareos group, you can secure the -bareos home directory by issuing this command: - -\footnotesize -\begin{verbatim} -chown -R bareos:bareos /var/db/bareos/ -\end{verbatim} -\normalsize - -This ensures that only the bareos user can access this directory. It also -means that if we run the Director and the Storage daemon as bareos, those -daemons also have restricted access. This would not be the case if they were -running as root. - -It is important to note that the storage daemon actually needs to be in the -operator group for normal access to tape drives etc (at least on a FreeBSD -system, that's how things are set up by default) Such devices are normally -chown root:operator. It is easier and less error prone to make Bareos a -member of that group than it is to play around with system permissions. - -Starting the Bareos daemons - -To start the bareos daemons on a FreeBSD system, issue the following command: - -\footnotesize -\begin{verbatim} -/usr/local/etc/rc.d/bareos-dir start -/usr/local/etc/rc.d/bareos-sd start -/usr/local/etc/rc.d/bareos-fd start -\end{verbatim} -\normalsize - -To confirm they are all running: - -\footnotesize -\begin{verbatim} -$ ps auwx | grep bareos -root 63418 0.0 0.3 1856 1036 ?? Ss 4:09PM 0:00.00 - /usr/local/sbin/bareos-fd -v -c /usr/local/etc/bareos-fd.conf -bareos 63416 0.0 0.3 2040 1172 ?? Ss 4:09PM 0:00.01 - /usr/local/sbin/bareos-sd -v -c /usr/local/etc/bareos-sd.conf -bareos 63422 0.0 0.4 2360 1440 ?? Ss 4:09PM 0:00.00 - /usr/local/sbin/bareos-dir -v -c /usr/local/etc/bareos-dir.conf -\end{verbatim} -\normalsize -}` - -Secure Erase Command --------------------- - -From -https://en.wikipedia.org/w/index.php?title=Data_erasure&oldid=675388437: - - Strict industry standards and government regulations are in place - that force organizations to mitigate the risk of unauthorized - exposure of confidential corporate and government data. Regulations - in the United States include HIPAA (Health Insurance Portability and - Accountability Act); FACTA (The Fair and Accurate Credit - Transactions Act of 2003); GLB (Gramm-Leach Bliley); Sarbanes-Oxley - Act (SOx); and Payment Card Industry Data Security Standards (PCI - DSS) and the Data Protection Act in the United Kingdom. Failure to - comply can result in fines and damage to company reputation, as well - as civil and criminal liability. - -Bareos supports the secure erase of files that usually are simply -deleted. Bareos uses an external command to do the secure erase itself. - -This makes it easy to choose a tool that meets the secure erase -requirements. - -To configure this functionality, a new configuration directive with the -name :raw-latex:`\configdirective{Secure Erase Command}` has been -introduced. - -This directive is optional and can be configured in: - -- Secure Erase Command - -- Secure Erase Command - -- Secure Erase Command - -This directive configures the secure erase command globally for the -daemon it was configured in. - -If set, the secure erase command is used to delete files instead of the -normal delete routine. - -If files are securely erased during a job, the secure delete command -output will be shown in the job log. - -.. raw:: latex - - \begin{logging}{bareos.log} - 08-Sep 12:58 win-fd JobId 10: secure_erase: executing C:/cygwin64/bin/shred.exe "C:/temp/bareos-restores/C/Program Files/Bareos/Plugins/bareos_fd_consts.py" - 08-Sep 12:58 win-fd JobId 10: secure_erase: executing C:/cygwin64/bin/shred.exe "C:/temp/bareos-restores/C/Program Files/Bareos/Plugins/bareos_sd_consts.py" - 08-Sep 12:58 win-fd JobId 10: secure_erase: executing C:/cygwin64/bin/shred.exe "C:/temp/bareos-restores/C/Program Files/Bareos/Plugins/bpipe-fd.dll" - \end{logging} - -The current status of the secure erase command is also shown in the -output of status director, status client and status storage. - -If the secure erase command is configured, the current value is printed. - -Example: - -.. raw:: latex - - \begin{bconsole}{} - * status dir - backup1.example.com-dir Version: 15.3.0 (24 August 2015) x86_64-suse-linux-gnu suse openSUSE 13.2 (Harlequin) (x86_64) - Daemon started 08-Sep-15 12:50. Jobs: run=0, running=0 mode=0 db=sqlite3 - Heap: heap=290,816 smbytes=89,166 max_bytes=89,166 bufs=334 max_bufs=335 - secure erase command='/usr/bin/wipe -V' - \end{bconsole} - -Example for Secure Erase Command Settings: - -Linux: - :raw-latex:`\configdirective{Secure Erase Command = "/usr/bin/wipe -V"}` - -Windows: - :raw-latex:`\configdirective{Secure Erase Command = "C:/cygwin64/bin/shred.exe"}` - -Our tests with the :command:`sdelete` command was not -successful, as :command:`sdelete` seems to stay active in -the background. diff --git a/docs/manuals/en/new_main_reference/source/spooling.rst b/docs/manuals/en/new_main_reference/source/spooling.rst index e804fb5c18b..e8f2423b363 100644 --- a/docs/manuals/en/new_main_reference/source/spooling.rst +++ b/docs/manuals/en/new_main_reference/source/spooling.rst @@ -3,16 +3,9 @@ Data Spooling ============= - - -.. _`sec:spooling}` :raw-latex:`\label{sec:DataSpooling`: sec:spooling}` :raw-latex:`\label{sec:DataSpooling -.. index:: General; Data Spooling -.. _`Data Spooling`: - -.. index:: - triple: General; Spooling; Data -.. _`Spooling`: - +:raw-latex:`\label{sec-spooling}` :raw-latex:`\label{sec-DataSpooling}` +:raw-latex:`\index[general]{Data Spooling}` +:raw-latex:`\index[general]{Spooling!Data}` Bareos allows you to specify that you want the Storage daemon to initially write your data to disk and then subsequently to tape. This @@ -44,7 +37,7 @@ until it is written to tape. Bareos also supports writing a backup to disk then later migrating or moving it to a tape (or any other medium). For details on this, please -see the :ref:`MigrationChapter` chapter of this manual +see the :raw-latex:`\nameref{MigrationChapter}` chapter of this manual for more details. The remainder of this chapter explains the various directives that you @@ -53,41 +46,38 @@ can use in the spooling process. Data Spooling Directives ------------------------ -.. index:: - triple: General; Data Spooling; Directives -.. _`Data Spooling`: - +:raw-latex:`\index[general]{Data Spooling!Directives}` The following directives can be used to control data spooling. - Turn data spooling on/off at the Job level: - **Spool Data** (Dir configuration, Job resource) = - YesNo + :raw-latex:`\linkResourceDirective{Dir}{Job}{Spool Data}` = + :raw-latex:`\dtYesNo` - This setting can be overwritten in a Schedule - **Run** (Dir configuration, Schedule resource) directive: - **SpoolData=**YesNo + :raw-latex:`\linkResourceDirective{Dir}{Schedule}{Run}` directive: + :raw-latex:`\parameter{SpoolData=}`:raw-latex:`\dtYesNo` - To override the Job specification in a bconsole session using the :raw-latex:`\bcommand{run}` command: - **SpoolData=**YesNo + :raw-latex:`\parameter{SpoolData=}`:raw-latex:`\dtYesNo` Please note that this does not refer to a configuration statement, but to an argument for the run command. - To limit the the maximum spool file size for a particular job: - **Spool Size** (Dir configuration, Job resource) + :raw-latex:`\linkResourceDirective{Dir}{Job}{Spool Size}` - To limit the maximum total size of the spooled data for a particular device: - **Maximum Spool Size** (Sd configuration, Device resource) + :raw-latex:`\linkResourceDirective{Sd}{Device}{Maximum Spool Size}` - To limit the maximum total size of the spooled data for a particular device for a single job: - **Maximum Job Spool Size** (Sd configuration, Device resource) + :raw-latex:`\linkResourceDirective{Sd}{Device}{Maximum Job Spool Size}` - To specify the spool directory for a particular device: - **Spool Directory** (Sd configuration, Device resource) + :raw-latex:`\linkResourceDirective{Sd}{Device}{Spool Directory}` Additional Notes ~~~~~~~~~~~~~~~~ @@ -103,7 +93,7 @@ Additional Notes and so on ad infinitum.} - Another advice is to always specify the - **Maximum Spool Size** (Sd configuration, Device resource) + :raw-latex:`\linkResourceDirective{Sd}{Device}{Maximum Spool Size}` so that your disk doesn’t completely fill up. In principle, data spooling will properly detect a full disk, and despool data allowing the job to continue. However, attribute spooling is not so kind to diff --git a/docs/manuals/en/new_main_reference/source/state.rst b/docs/manuals/en/new_main_reference/source/state.rst index 2ac110eb7d0..ba95f7c8901 100644 --- a/docs/manuals/en/new_main_reference/source/state.rst +++ b/docs/manuals/en/new_main_reference/source/state.rst @@ -6,16 +6,13 @@ The Current State of Bareos What is Implemented ------------------- -.. index:: - triple: General; Implementation; What is implemented -.. _`Implementation`: - +:raw-latex:`\index[general]{Implementation!What is implemented}` - Job Control - Network backup/restore with centralized Director. - - Internal scheduler for automatic :ref:`JobDef Job` + - Internal scheduler for automatic :raw-latex:`\ilink{Job}{JobDef}` execution. - Scheduling of multiple Jobs at the same time. @@ -25,7 +22,7 @@ What is Implemented - Job sequencing using priorities. - - :ref:`UADef Console` interface to the Director + - :raw-latex:`\ilink{Console}{UADef}` interface to the Director allowing complete control. Some GUIs are also available. - Security @@ -36,11 +33,11 @@ What is Implemented - CRAM-MD5 password authentication between each component (daemon). - Configurable - :ref:`CommEncryption TLS (SSL) communications encryption` + :raw-latex:`\ilink{TLS (SSL) communications encryption}{CommEncryption}` between each component. - Configurable - :ref:`DataEncryption Data (on Volume) encryption` + :raw-latex:`\ilink{Data (on Volume) encryption}{DataEncryption}` on a Client by Client basis. - Computation of MD5 or SHA1 signatures of the file data if @@ -52,7 +49,7 @@ What is Implemented current backup or a backup prior to a specified time and date. - Listing and Restoration of files using stand-alone - :command:`bls` and :command:`bextract` + :raw-latex:`\command{bls}` and :raw-latex:`\command{bextract}` tool programs. Among other things, this permits extraction of files when Bareos and/or the catalog are not available. Note, the recommended way to restore files is using the restore command in @@ -62,7 +59,7 @@ What is Implemented files (previously saved). - Ability to recreate the catalog database by scanning backup - Volumes using the :command:`bscan` program. + Volumes using the :raw-latex:`\command{bscan}` program. - SQL Catalog @@ -86,7 +83,7 @@ What is Implemented - Multi-volume saves. When a Volume is full, **Bareos** automatically requests the next Volume and continues the backup. - - :ref:`DirectorResourcePool Pool and Volume` library + - :raw-latex:`\ilink{Pool and Volume}{DirectorResourcePool}` library management providing Volume flexibility (e.g. monthly, weekly, daily Volume sets, Volume sets segregated by Client, ...). @@ -97,7 +94,7 @@ What is Implemented - The Volume data format is upwards compatible so that old Volumes can always be read. - - A flexible :ref:`MessagesChapter message` handler + - A flexible :raw-latex:`\ilink{message}{MessagesChapter}` handler including routing of messages from any daemon back to the Director and automatic email reporting. @@ -109,7 +106,7 @@ What is Implemented - Autochanger support using a simple shell interface that can interface to virtually any autoloader program. A script for - :command:`mtx` is provided. + :raw-latex:`\command{mtx}` is provided. - Support for autochanger barcodes – automatic tape labeling from barcodes. @@ -187,14 +184,9 @@ Advantages Over Other Backup Programs Current Implementation Restrictions ----------------------------------- -.. index:: - triple: General; Restrictions; Current Implementation -.. _`Restrictions`: - - -- +:raw-latex:`\index[general]{Restrictions!Current Implementation}` -.. _`MultipleCatalogs`: MultipleCatalogs It is possible to configure the +- :raw-latex:`\label{MultipleCatalogs}` It is possible to configure the Bareos Director to use multiple Catalogs. However, this is neither advised, nor supported. Multiple catalogs require more management because in general you must know what catalog contains what data, @@ -208,19 +200,13 @@ Current Implementation Restrictions with 64 bit machines does not always read correctly on a 32 bit machine). -.. _sec:DesignLimitations: +.. _sec-DesignLimitations: Design Limitations or Restrictions ---------------------------------- -.. index:: - triple: General; Restrictions; Design Limitations -.. _`Restrictions`: - -.. index:: - triple: General; Design; Limitations -.. _`Design`: - +:raw-latex:`\index[general]{Restrictions!Design Limitations}` +:raw-latex:`\index[general]{Design!Limitations}` - Names (resource names, volume names, and such) defined in Bareos configuration files are limited to a fixed number of characters. @@ -228,10 +214,10 @@ Design Limitations or Restrictions apply to filenames, which may be arbitrarily long. - Command line input to some of the stand alone tools – e.g. - :command:`btape`, :command:`bconsole` is + :raw-latex:`\command{btape}`, :raw-latex:`\command{verbatim}` is restricted to several hundred characters maximum. Normally, this is not a restriction, except in the case of listing multiple Volume - names for programs such as :command:`bscan`. To avoid + names for programs such as :raw-latex:`\command{bscan}`. To avoid this command line length restriction, please use a **.bsr** file to specify the Volume names. @@ -245,20 +231,18 @@ Design Limitations or Restrictions Items to Note ------------- -.. index:: General; Items to Note -.. _`Items to Note`: - +:raw-latex:`\index[general]{Items to Note}` - Bareos’s Differential and Incremental *normal* backups are based on time stamps. Consequently, if you move files into an existing directory or move a whole directory into the backup fileset after a Full backup, those files will probably not be backed up by an Incremental save because they will have old dates. This problem is - corrected by using :ref:`accuratemode Accurate mode` + corrected by using :raw-latex:`\ilink{Accurate mode}{accuratemode}` backups or by explicitly updating the date/time stamp on all moved files. - In non Accurate mode, files deleted after a Full save will be included in a restoration. This is typical for most similar backup programs. To avoid this, use - :ref:`accuratemode Accurate mode` backup. + :raw-latex:`\ilink{Accurate mode}{accuratemode}` backup. diff --git a/docs/manuals/en/new_main_reference/source/storedconf.rst b/docs/manuals/en/new_main_reference/source/storedconf.rst index c02620f2b27..32687d951fc 100644 --- a/docs/manuals/en/new_main_reference/source/storedconf.rst +++ b/docs/manuals/en/new_main_reference/source/storedconf.rst @@ -3,15 +3,9 @@ Storage Daemon Configuration ============================ -.. index:: SD; Configuration -.. index:: - triple: General; Storage Daemon; Configuration -.. _`Storage Daemon`: - -.. index:: - triple: General; Configuration; Storage Daemon -.. _`Configuration`: - +:raw-latex:`\index[sd]{Configuration}` +:raw-latex:`\index[general]{Storage Daemon!Configuration}` +:raw-latex:`\index[general]{Configuration!Storage Daemon}` The |bareosSd| configuration file has relatively few resource definitions. However, due to the great variation in backup @@ -24,27 +18,27 @@ and very few directives are actually needed. For a general discussion of configuration file and resources including the data types recognized by **Bareos**, please see the -:ref:`ConfigureChapter Configuration` chapter of this +:raw-latex:`\ilink{Configuration}{ConfigureChapter}` chapter of this manual. The following Storage Resource definitions must be defined: -- :ref:`StorageResourceStorage Storage` – to define the +- :raw-latex:`\ilink{Storage}{StorageResourceStorage}` – to define the name of the Storage daemon. -- :ref:`StorageResourceDirector Director` – to define +- :raw-latex:`\ilink{Director}{StorageResourceDirector}` – to define the Director’s name and his access password. -- :ref:`StorageResourceDevice Device` – to define the +- :raw-latex:`\ilink{Device}{StorageResourceDevice}` – to define the characteristics of your storage device (tape drive). -- :ref:`MessagesChapter Messages` – to define where +- :raw-latex:`\ilink{Messages}{MessagesChapter}` – to define where error and information messages are to be sent. Following resources are optional: -- :ref:`StorageResourceAutochanger` – to define +- :raw-latex:`\nameref{StorageResourceAutochanger}` – to define Autochanger devices. -- :ref:`StorageResourceNDMP` – to define the NDMP +- :raw-latex:`\nameref{StorageResourceNDMP}` – to define the NDMP authentication context. .. _StorageResourceStorage: @@ -52,8 +46,8 @@ Following resources are optional: Storage Resource ---------------- -.. index:: SD; Resource!Storage -.. index:: SD; Storage!Resource +:raw-latex:`\index[sd]{Resource!Storage}` +:raw-latex:`\index[sd]{Storage!Resource}` In general, the properties specified under the Storage resource define global properties of the Storage daemon. Each Storage daemon @@ -62,26 +56,25 @@ definition. The following is a typical Storage daemon storage resource definition. -.. raw:: latex +:: - \begin{bconfig}{Storage daemon storage definition} - # - # "Global" Storage daemon configuration specifications appear - # under the Storage resource. - # - Storage { - Name = "Storage daemon" - Address = localhost - } - \end{bconfig} + {Storage daemon storage definition} + # + # "Global" Storage daemon configuration specifications appear + # under the Storage resource. + # + Storage { + Name = "Storage daemon" + Address = localhost + } .. _StorageResourceDirector: Director Resource ----------------- -.. index:: SD; Resource!Director -.. index:: SD; Director!Resource +:raw-latex:`\index[sd]{Resource!Director}` +:raw-latex:`\index[sd]{Director!Resource}` The Director resource specifies the Name of the Director which is permitted to use the services of the Storage daemon. There may be @@ -90,25 +83,22 @@ the corresponding values in the Director’s configuration file. The following is an example of a valid Director resource definition: -.. raw:: latex +:: - \begin{bconfig}{Storage daemon Director definition} - Director { - Name = MainDirector - Password = my\_secret\_password - } - \end{bconfig} + {Storage daemon Director definition} + Director { + Name = MainDirector + Password = my\_secret\_password + } .. _NDMPResource: NDMP Resource ------------- - - -.. _`StorageResourceNDMP`: StorageResourceNDMP -.. index:: SD; Resource!NDMP -.. index:: SD; NDMP!Resource +:raw-latex:`\label{StorageResourceNDMP}` +:raw-latex:`\index[sd]{Resource!NDMP}` +:raw-latex:`\index[sd]{NDMP!Resource}` The NDMP Resource specifies the authentication details of each NDMP client. There may be multiple NDMP resources for a single Storage @@ -120,8 +110,8 @@ are specific to one client. Device Resource --------------- -.. index:: SD; Resource!Device -.. index:: SD; Device!Resource +:raw-latex:`\index[sd]{Resource!Device}` +:raw-latex:`\index[sd]{Device!Resource}` The Device Resource specifies the details of each device (normally a tape drive) that can be used by the Storage daemon. There may be @@ -132,15 +122,9 @@ Device. Edit Codes for Mount and Unmount Directives ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. index:: General; Edit Codes for Mount and Unmount Directives -.. _`Edit Codes for Mount and Unmount Directives`: - -.. index:: General; Mount and Unmount: use variables in directives -.. _`Mount and Unmount: use variables in directives`: - - - -.. _`mountcodes`: mountcodes +:raw-latex:`\index[general]{Edit Codes for Mount and Unmount Directives}` +:raw-latex:`\index[general]{Mount and Unmount: use variables in directives}` +:raw-latex:`\label{mountcodes}` Before submitting the **Mount Command**, or **Unmount Command** directives to the operating system, Bareos performs character @@ -166,9 +150,7 @@ substitution of the following characters: Devices that require a mount (USB) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. index:: General; Devices that require a mount (USB) -.. _`Devices that require a mount (USB)`: - +:raw-latex:`\index[general]{Devices that require a mount (USB)}` .. raw:: latex @@ -193,26 +175,26 @@ Devices that require a mount (USB) Most frequently, you will define it as follows: - \begin{bconfig}{} + \begin{verbatim}{} Mount Command = "/bin/mount -t iso9660 -o ro %a %m" - \end{bconfig} + \end{verbatim} For some media, you may need multiple commands. If so, it is recommended that you use a shell script instead of putting them all into the Mount Command. For example, instead of this: - \begin{bconfig}{} + \begin{verbatim}{} Mount Command = "/usr/local/bin/mymount" - \end{bconfig} + \end{verbatim} Where that script contains: - \begin{commands}{} + \begin{verbatim}{} #!/bin/sh ndasadmin enable -s 1 -o w sleep 2 mount /dev/ndas-00323794-0p1 /backup - \end{commands} + \end{verbatim} Similar consideration should be given to all other Command parameters. @@ -223,9 +205,9 @@ Devices that require a mount (USB) Most frequently, you will define it as follows: - \begin{bconfig}{} + \begin{verbatim}{} Unmount Command = "/bin/umount %m" - \end{bconfig} + \end{verbatim} If you need to specify multiple commands, create a shell script. @@ -236,17 +218,11 @@ Devices that require a mount (USB) Messages Resource ----------------- -.. index:: - triple: General; Resource; Messages -.. _`Resource`: - -.. index:: - triple: General; Messages; Resource -.. _`Messages`: - +:raw-latex:`\index[general]{Resource!Messages}` +:raw-latex:`\index[general]{Messages!Resource}` For a description of the Messages Resource, please see the -:ref:`MessagesChapter` chapter of this manual. +:raw-latex:`\nameref{MessagesChapter}` chapter of this manual. .. _ExampleStorageConfiguration: diff --git a/docs/manuals/en/new_main_reference/source/supportedoses.rst b/docs/manuals/en/new_main_reference/source/supportedoses.rst index 39d4dfc4535..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/supportedoses.rst +++ b/docs/manuals/en/new_main_reference/source/supportedoses.rst @@ -1,820 +1 @@ -The Bareos project provides and supports packages that have been -released at http://download.bareos.org/bareos/release/ -However, the following tabular gives an overview, what components are -expected on which platforms to run: - -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| **Operating Systems** | **Version** | **Client Daemon** | **Director Daemon** | **Storage Daemon** | -+================================================================================================+====================+=================================================================================+=================================================================================+=================================================================================+ -| :raw-latex:`\multicolumn{5}{c}{\textbf{Linux}}` -.. index:: - triple: General; Platform; Linux | | | | | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| Arch Linux -.. index:: - triple: General; Platform; Arch Linux}` |   | https://aur.archlinux.org/pkgbase/bareos/ | :raw-latex:`\elink{X}{https://aur.archlinux.org/pkgbase/bareos/ | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| CentOS | current | v12.4 | v12.4 | v12.4 | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| Debian | current | v12.4 | v12.4 | v12.4 | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| Fedora | current | v12.4 | v12.4 | v12.4 | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| Gentoo -.. index:: - triple: General; Platform; Gentoo}` |   | https://packages.gentoo.org/package/app-backup/bareos | :raw-latex:`\elink{X}{https://packages.gentoo.org/package/app-backup/bareos | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| openSUSE | current | v12.4 | v12.4 | v12.4 | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| RHEL | current | v12.4 | v12.4 | v12.4 | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| SLES | current | v12.4 | v12.4 | v12.4 | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| Ubuntu | current | v12.4 | v12.4 | v12.4 | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| :ref:`Univention Corporate Linux sec:UniventionCorporateServer` | App Center | v12.4 | v12.4 | v12.4 | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| :raw-latex:`\multicolumn{5}{c}{\textbf{MS Windows}}` | | | | | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| :ref:`MS Windows sec:windows` 32bit | 10/8/7 | v12.4 | v15.2 | v15.2 | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -|   | 2008/Vista | | | | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -|   | 2003/XP | v12.4–v14.2 | | | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| :ref:`MS Windows sec:windows` 64bit | 10/8/2012/7 | v12.4 | v15.2 | v15.2 | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -|   | 2008/Vista | | | | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| :raw-latex:`\multicolumn{5}{c}{\textbf{Mac OS}}` | | | | | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| :ref:`Mac OS X/Darwin sec:macosx` |   | v14.2 | | | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| :raw-latex:`\multicolumn{5}{c}{\textbf{BSD}}` | | | | | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| FreeBSD -.. index:: - triple: General; Platform; FreeBSD}` | :math:`\geq` 5.0 | http://www.freshports.org/sysutils/bareos-server/ | :raw-latex:`\elink{X}{http://www.freshports.org/sysutils/bareos-server/ | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| OpenBSD |   | X | |   | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| NetBSD |   | X | |   | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| :raw-latex:`\multicolumn{5}{c}{\textbf{Unix}}` | | | | | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| AIX -.. index:: - triple: General; Platform; AIX | :math:`\geq` 4.3 | com-13.2 | :math:`\star` | :math:`\star` | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| HP-UX -.. index:: - triple: General; Platform; HP-UX |   | com-13.2 |   |   | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| Irix |   | :math:`\star` |   |   | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| Solaris -.. index:: - triple: General; Platform; Solaris | :math:`\geq` 8 | com-12.4 | com-12.4 | com-12.4 | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ -| True64 |   | :math:`\star` |   |   | -+------------------------------------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ - -+---------------------+---------------------------------------------------------------------------------------------------------------------------------+ -| **vVV.V** | starting with Bareos version VV.V, this platform is official supported by the Bareos.org project | -+---------------------+---------------------------------------------------------------------------------------------------------------------------------+ -| **com-VV.V** | starting with Bareos version VV.V, this platform is supported. However, pre-build packages are only available from Bareos.com | -+---------------------+---------------------------------------------------------------------------------------------------------------------------------+ -| **nightly** | provided by Bareos nightly build. Bug reports are welcome, however it is not official supported | -+---------------------+---------------------------------------------------------------------------------------------------------------------------------+ -| **X** | known to work | -+---------------------+---------------------------------------------------------------------------------------------------------------------------------+ -| **:math:`\star`** | has been reported to work by the community | -+---------------------+---------------------------------------------------------------------------------------------------------------------------------+ - -Packages for the different Linux platforms ------------------------------------------- - -The following tables summarize what packages are available for the -different Linux platforms. - -This information is generated based on -http://download.bareos.com/bareos/release/. In most cases this is -identical to the packages provided by -http://download.bareos.org/bareos/release/. Only if a package have been -added later in a maintenance release, these information may differ. - -Distributions that are no longer relevant are left out. However, you -might still find the packages on our download servers. - -Bareos tries to provide all packages for all current platforms. For -extra packages, it depends if the distribution contains the required -dependencies. - -For general information about the packages, see -:ref:`sec:BareosPackages`. - -Packages names not containing the word **bareos** are -required packages where we decided to include them ourselves. - -:raw-latex:`\small` - -Univention Corporate Server ---------------------------- - - -.. index:: - triple: General; Platform; Univention Corporate Server The -Bareos version for the Univention App Center integraties into the -Univention Enterprise Linux environment, making it easy to backup all -the systems managed by the central Univention Corporate Server. - -Preamble -~~~~~~~~ - -The -http://www.univention.de/ -is an enterprise Linux distribution based on Debian. It consists of an -integrated management system for the centralised administration of -servers, computer workplaces, users and their rights as well as a wide -range of server applications. It also includes an Unvention App Center -for the easy installation and management of extensions and appliances. - -Bareos is part of the -https://www.univention.de/produkte/univention-app-center/app-katalog/bareos/ -and therefore an Univention environment can easily be extended to -provide backup functionality for the Univention servers as well as for -the connected client systems. Using the Univention Management Console -(UMC), you can also create backup jobs for client computers (Windows or -Linux systems), without the need of editing configuration files. - -The Bareos Univention App is shipped with a default configuration for -the director daemon and the storage daemon. - - -.. warning:: - You need to review some Univention configuration registry (UCR) variables. Most likely, you will want to set the location where the backups are stored. Otherwise, you may quickly run out of disk space on your backup server! - -You will find further information under -:ref:`sec:UniventionBackupStorage`. - -Quick Start -~~~~~~~~~~~ - -- Determine the space requirements and where to store your backup data - -- Set the **bareos/*** UCR variables according to - your needs, see :ref:`sec:UCR` - -- Restart :command:`bareos-dir`, - :command:`bareos-sd}` and :raw-latex:`\command{bareos-fd` - (or simply reboot the server) - -- Install the Bareos file daemon on clients and copy Director - configuration resource file from - - - */etc/bareos/bareos-dir-export/client/-fd/bareos-fd.d/director/*.conf* - - - (or - */etc/bareos/autogenerated/client-configs/.conf*, - if Bareos :math:`<` 16.2.0) - - For details, see :ref:`sec:UniventionAddClient`. - -- Enable backup jobs for clients in the Univention Management Console - -UCR variables -~~~~~~~~~~~~~ - -**bareos/filestorage** - : /var/lib/bareos/storage (default) - - - Location where to store the backup files. Make sure, it offers - enough disk space for a configured backup volumes. - -**bareos/max_full_volume_bytes** - : 20 (default) - - - Maximum size (in GB) of a volume for the **Full** - backup pool - -**bareos/max_full_volumes** - : 1 (default) - - - Maximum number of volumes for the **Full** backup - pool - -**bareos/max_diff_volume_bytes** - : 10 (default) - - - Maximum size (in GB) of a volume for the - **Differential** backup pool - -**bareos/max_diff_volumes** - : 1 (default) - - - Maximum number of volumes for the - **Differential** backup pool - -**bareos/max_incr_volume_bytes** - : 1 (default) - - - Maximum size (in GB) of a volume for the - **Incremental** backup pool - -**bareos/max_incr_volumes** - : 1 (default) - - - Maximum number of volumes for the **Incremental** - backup pool - -**bareos/backup_myself** - : no (default) - - no - don’t backup the server itself - - yes - backup the server itself - -**bareos/webui/console/user1/username** - : Administrator (default) - - - User name to login at the bareos-webui - -**bareos/webui/console/user1/password** - : (no default value) - - - Password to login at the bareos-webui - -UCR variables can be set via the Univention Configuration Registry Web -interface - -|image| - -or using the :command:`ucr` command line tool: - -.. raw:: latex - - \begin{commands}{Enable backup of the server itself} - root@ucs:~# ucr set bareos/backup_myself=yes - Setting bareos/backup_myself - File: /etc/bareos/bareos-dir.conf - [ ok ] Reloading Bareos Director: bareos-dir. - \end{commands} - - -.. warning:: - univention-bareos $<$ 15.2 did require a manual reload/restart of the bareos-dir service: - -.. raw:: latex - - \begin{commands}{let bareos-dir reload its configuration} - root@ucs:~# service bareos-dir reload - [ ok ] Reloading Bareos Director: bareos-dir. - \end{commands} - -Setup -~~~~~ - -After installation of the Bareos app, Bareos is ready for operation. A -default configuration is created automatically. - -Bareos consists of three daemons called :command:`director` -(or :command:`bareos-dir`), -:command:`storage-daemon` (or -:command:`bareos-sd}`) and :raw-latex:`\command{filedaemon` -(or :command:`bareos-fd`). All three daemons are started -right after the installation by the Univention App Center. - -If you want to enable automatic backups of the server, you need to set -the Univention configuration registry (UCR) variable -**bareos/backup_myself** to -**yes** and reload the director daemon. - -Administration -~~~~~~~~~~~~~~ - -For general tasks the :ref:`bareos-webui sec:webui` can -be used. Additional, there is the :command:`bconsole` -command line tool: - -.. raw:: latex - - \begin{commands}{Starting the bconsole} - root@ucs:~# bconsole - Connecting to Director ucs:9101 - 1000 OK: ucs-dir Version: 15.2.2 (15 November 2015) - Enter a period to cancel a command. - * - \end{commands} - -For general information, see the -:ref:`Bconsole Tuturial sec:TuturialBconsole`. - -Backup Schedule -~~~~~~~~~~~~~~~ - -As a result of the default configuration located at the -:command:`bareos-dir`, the backup schedule will look as -follows: - -Full Backups - - are written into the **Full** pool - - - on the first saturday at 21:00 o’clock - - - and kept for 365 days - -Differential Backups - - are written into the **Differential** pool - - - on every 2nd to 5th saturday at 21:00 o’clock - - - and kept for 90 days - -Incremental Backups - - are written into the **Incremental** pool - - - on every day from monday to friday at 21:00 o’clock - - - and kept for 30 days - -That means full backups will be written every first saturday at 21:00 -o’clock, differential backups every 2nd to 5th saturday at 21:00 o’clock -and incremental backups from monday to friday at 21:00 o’clock. So you -have got one full backup every month, four weekly differential and 20 -daily incremental backups per month. - -This schedule is active for the Univention server backup of itself and -all other clients, which are backed up through the -:command:`bareos-dir` on the Univention server. - -There is also a special backup task, which is the Bareos backups itself -for a possible disaster recovery. This backup has got its own backup -cycle which starts after the main backups. The backup consists of a -database backup for the metadata of the Bareos backup server and a -backup of the Bareos configuration files under -*/etc/bareos/*. - -Backup data management -~~~~~~~~~~~~~~~~~~~~~~ - -Data from the backup jobs is written to volumes, which are organized in -pools (see chapter :ref:`DirectorResourcePool`). - -The default configuration uses three different pools, called -**Full}`, :raw-latex:`\pool{Differential** and -**Incremental**, which are used for full backups, -differential and incremental backups, respectively. - -If you change the UCR variables, the configuration files will be -rewritten automatically. After each change you will need to reload the -director daemon. - -.. raw:: latex - - \begin{commands}{Example for changing the Full pool size to $10 \ast 20$ GB} - root@ucs:~# ucr set bareos/max_full_volumes=10 - Setting bareos/max_full_volumes - File: /etc/bareos/bareos-dir.conf - [ ok ] Reloading Bareos Director: bareos-dir. - root@ucs:~# ucr set bareos/max_full_volume_bytes=20 - Setting bareos/max_full_volume_bytes - File: /etc/bareos/bareos-dir.conf - [ ok ] Reloading Bareos Director: bareos-dir. - \end{commands} - - -.. warning:: - This only affects new volumes. Existing volumes will not change there size. - -Backup Storage -~~~~~~~~~~~~~~ - - -.. warning:: - Using the default configuration, Bareos will store backups on your local disk. You may want to store the data to another location to avoid using up all of your disk space. - -The location for backups is -*/var/lib/bareos/storage* -configuration. - -For example, to use a NAS device for storing backups, you can mount your -NAS volume via NFS on */var/lib/bareos/storage* -Alternatively, you can mount the NAS volume to another directory of your -own choice, and change the UCR variable -**bareos/filestorage** to the corresponding path. -The directory needs to be writable by user **bareos**. - -.. raw:: latex - - \begin{commands}{Example for changing the storage path} - root@ucs:/etc/bareos# ucr set bareos/filestorage=/path/to/your/storage - Setting bareos/filestorage - File: /etc/bareos/bareos-sd.conf - \end{commands} - - -.. warning:: - You need to restart the Bareos storage daemon after having changed the storage path: - -.. raw:: latex - - \begin{commands}{} - root@ucs:/# service bareos-sd restart - \end{commands} - -Bareos Webui Configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -After installation you just need to setup your login credentials via UCR -variables. Therefore, set the Univention configuration registry (UCR) -variable **bareos/webui/console/user1/username** -and **bareos/webui/consoles/user1/password** -according to your needs. The director configuration is automatically -reloaded if one of those two variables changes. - -Alternatively you can also set those UCR variables via commandline. - -.. raw:: latex - - \begin{commands}{Example for changing webui login credentials} - root@ucs:~# ucr set bareos/webui/console/user1/username="bareos" - Setting bareos/webui/console/user1/username - File: /etc/bareos/bareos-dir.conf - [ ok ] Reloading Bareos Director: bareos-dir. - root@ucs:~# ucr set bareos/webui/console/user1/password="secret" - Setting bareos/webui/console/user1/password - File: /etc/bareos/bareos-dir.conf - [ ok ] Reloading Bareos Director: bareos-dir. - \end{commands} - -When your login credentials are set, you can login into Bareos Webui by -following the entry in your Administration UCS Overview or directly via -`https:///bareos-webui/ /bareos-webui/>`__. - -|image| - -Add a client to the backup -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Overview -^^^^^^^^ - -- Install the Bareos client software on the target system, see - :ref:`Adding a Bareos Client SecondClient` - -- Use the Univention Management Console to add the client to the - backup, see the screenshot below - -- Copy the filedaemon resource configuration file from the Univention - server to the target system - -Bareos :math:`>=` 16.2.4 -^^^^^^^^^^^^^^^^^^^^^^^^ - -Server-side -''''''''''' - -The Univention Bareos application comes with an automatism for the -client and job configuration. If you want to add a client to the Bareos -director configuration, you need use the Univention Management Console, -select the client you want to backup and set the -**enable backup job** checkbox to true, as shown in -the screenshot below. - -|image| - -If the name of the client is **testw1.example.com**, -corresponding configuration files will be generated: - -- */etc/bareos/autogenerated/clients/testw1.example.com.include* - -- */etc/bareos/bareos-dir-export/client/testw1.example.com-fd/bareos-fd.d/director/bareos-dir.conf* - -Generated configuration files under -*/etc/bareos/bareos-dir-export/client/* are -intended for the target systems. After you have -:ref:`installed the Bareos client on the target system SecondClient`, -copy the generated client configuration over to the client and save it -to following directories: - -- on Linux: */etc/bareos/bareos-fd.d/director/* - -- on Windows: - *C::raw-latex:`\Program`Files:raw-latex:`\Bareos`:raw-latex:`\bareos`-fd.d/director/* - -.. raw:: latex - - \begin{commands}{copy client configuration from the server to the testw1.example.com client (Linux)} - root@ucs:~# CLIENTNAME=testw1.example.com - root@ucs:~# scp /etc/bareos/bareos-dir-export/client/${CLIENTNAME}-fd/bareos-fd.d/director/*.conf root@${CLIENTNAME}:/etc/bareos/bareos-fd.d/director/ - \end{commands} - -Background -^^^^^^^^^^ - -The settings for each job resource are defined by the template files you -see below: - -The files - -- */etc/bareos/autogenerated/clients/generic.template* - -- */etc/bareos/autogenerated/clients/windows.template* - -are used as templates for new clients. For Windows clients the file -*windows.template* is used, the -*generic.template* is used for all other client types. - -If you disable the Bareos backup for a client, the client will not be -removed from the configuration files. Only the backup job will be set -inactive. - -If you add three client, your client directory will look similar to -this: - -.. raw:: latex - - \begin{commands}{} - root@ucs:/etc/bareos/autogenerated/clients# ls -l - -rw-r--r-- 1 root root 430 16. Mai 15:15 generic.template - -rw-r----- 1 root bareos 513 21. Mai 14:46 testw1.example.com.include - -rw-r----- 1 root bareos 518 21. Mai 14:49 testw2.example.com.include - -rw-r----- 1 root bareos 518 16. Mai 18:17 testw3.example.com.include - -rw-r--r-- 1 root root 439 16. Mai 15:15 windows.template - \end{commands} - -The client configuration file contains, as you can see below, the client -connection and the job information: - -.. raw:: latex - - \begin{commands}{} - root@ucs:/etc/bareos/autogenerated/clients# cat testw2.example.com.include - Client { - Name = "testw2.example.com-fd" - Address = "testw2.example.com" - Password = "DBLtVnRKq5nRUOrnB3i3qAE38SiDtV8tyhzXIxqR" - } - - Job { - Name = "Backup-testw2.example.com" # job name - Client = "testw2.example.com-fd" # client name - JobDefs = "DefaultJob" # job definition for the job - FileSet = "Windows All Drives" # FileSet (data which is backed up) - Schedule = "WeeklyCycle" # schedule for the backup tasks - Enabled = "Yes" #this is the ressource which is toggled on/off by enabling or disabling a backup from the univention gui - } - \end{commands} - -Bareos :math:`<` 16.2.0 -^^^^^^^^^^^^^^^^^^^^^^^ - -Older versions of Bareos handle generating the client configuration -similar, but not identical: - -If the name of the client is **testw1.example.com**, -corresponding configuration files will be generated/adapted: - -- creates - */etc/bareos/autogenerated/fd-configs/testw1.example.com.conf* - -- creates - */etc/bareos/autogenerated/clients/testw1.example.com.include* - -- extends */etc/bareos/autogenerated/clients.include* - -Here the files intended for the target systems are generated under -*/etc/bareos/autogenerated/fd-configs/* and they -do not only definr a director resource, but are full configuration files -for the client. After you have -:ref:`installed the Bareos client on the target system SecondClient`, -copy the generated client configuration over to the client and save it -to - -- on Linux: */etc/bareos/bareos-fd.conf* - -- on Windows: - *C::raw-latex:`\Program`Files:raw-latex:`\Bareos`:raw-latex:`\bareos`-fd.conf* - -.. raw:: latex - - \begin{commands}{copy client configuration from the server to the testw1.example.com client (Linux)} - root@ucs:~# CLIENTNAME=testw1.example.com - root@ucs:~# scp /etc/bareos/autogenerated/fd-configs/${CLIENTNAME}.conf root@${CLIENTNAME}:/etc/bareos/bareos-fd.conf - \end{commands} - -Debian.org / Ubuntu Universe ----------------------------- - - -.. index:: - triple: General; Platform!Debian; Debian.org - -.. index:: - triple: General; Platform!Debian; 8 - -.. index:: - triple: General; Platform!Ubuntu; Universe - -.. index:: - triple: General; Platform!Ubuntu!Universe; 15.04 -.. _sec:DebianOrg: - -The distributions of Debian :math:`>=` 8 include a version of Bareos. -Ubuntu Universe :math:`>=` 15.04 does also include these packages. - -In the further text, these version will be named -**Bareos (Debian.org)** (also for the Ubuntu Universe -version, as this is based on the Debian version). - -Limitations of the Debian.org/Ubuntu Universe version of Bareos -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- Debian.org does not include the libfastlz compression library and - therefore the Bareos (Debian.org) packages do not offer the fileset - options **compression=LZFAST**, - **compression=LZ4** and - **compression=LZ4HC**. - -- Debian.org prefers that Bareos (Debian.org) is linked against GnuTLS - instead of OpenSSL. Therefore, the Bareos (Debian.org) package only - support :ref:`sec:TransportEncryption` but no - :ref:`DataEncryption`. - -- Debian.org does not include the **bareos-webui** - package. - -Mac OS X --------- - - -.. index:: - triple: General; Platform!Mac; OS X -.. _sec:macosx: - -Bareos for MacOS X is available either - -- via the https://brew.sh/ - (http://formulae.brew.sh/formula/bareos-client) or - -- as pkg file from - http://download.bareos.org/bareos/release/latest/MacOS/. - -However, you have to choose upfront, which client you want to use. -Otherwise conflicts do occur. - -Both packages contain the |bareosFd| and -:command:`bconsole`. - -Installing the Bareos Client as PKG -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -.. index:: - triple: General; Installation; MacOS - -The Bareos installer package for Mac OS X contains the - |bareosFd| for Mac OS X 10.5 or later. - -On your local Mac, you must be an admin user. The main user is an admin -user. - -Download the *bareos-client*.pkg* installer package -from http://download.bareos.org/bareos/release/latest/MacOS/. - -Find the .pkg you just downloaded. Install the .pkg by holding the CTRL -key, left-clicking the installer and choosing -:raw-latex:`\bquote{open}`. - -Follow the directions given to you and finish the installation. - -Configuration -~~~~~~~~~~~~~ - -To make use of your |bareosFd| on your system, it is required -to configure the |bareosDir| and the local - |bareosFd| . - -Configure the server-side by follow the instructions at -:ref:`sec:AddAClient`. - -After configuring the server-side you can either transfer the necessary -configuration file using following command or configure the client -locally. - -:raw-latex:`\subsubsubsection{Option 1: Copy the director resource from the Bareos Director to the Client}` - -Assuming your client has the DNS entry -**client2.example.com** and has been added to - |bareosDir| as -:raw-latex:`\resourcename{bareos-dir}{client}{client2-fd}`: - -.. raw:: latex - - \begin{commands}{} - scp /etc/bareos/bareos-dir-export/client/client2-fd/bareos-fd.d/director/bareos-dir.conf root@client2.example.com:/usr/local/etc/bareos/bareos-fd.d/director/ - \end{commands} - -This differs in so far, as on Linux the configuration files are located -under */etc/bareos/* -located at */usr/local/etc/bareos/* - -:raw-latex:`\subsubsubsection{Option 2: Edit the director resource on the Client}` - -Alternatively, you can edit the file -*/usr/local/etc/bareos/bareos-fd.d/director/bareos-dir.conf* - -This can be done by right-clicking the finder icon in your task bar, -select :raw-latex:`\bquote{Go to folder ...}` and paste -*/usr/local/etc/bareos/bareos-fd.d/director/* - -Select the *bareos-dir.conf* - -Alternatively you can also call following command on the command -console: - -.. raw:: latex - - \begin{commands}{} - open -t /usr/local/etc/bareos/bareos-fd.d/director/bareos-dir.conf - \end{commands} - -The file should look similar to this: - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-fd}{director}{bareos-dir} - Director { - Name = bareos-dir - Password = "SOME_RANDOM_PASSWORD" - Description = "Allow the configured Director to access this file daemon." - } - \end{bareosConfigResource} - -Set this client-side password to the same value as given on the -server-side. - - -.. warning:: - The configuration file contains passwords and therefore must not be accessible for any users except admin users. - -Restart bareos-fd after changing the configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The bareos-fd must be restarted to reread its configuration: - -.. raw:: latex - - \begin{commands}{Restart the \bareosFd} - sudo launchctl stop org.bareos.bareos-fd - sudo launchctl start org.bareos.bareos-fd - \end{commands} - -Verify that the Bareos File Daemon is working -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Open the :command:`bconsole` on your - |bareosDir| and check the status of the client with - -.. raw:: latex - - \begin{bconfig}{} - *status client=client2-fd - \end{bconfig} - -In case, the client does not react, following command are useful the -check the status: - -.. raw:: latex - - \begin{commands}{Verify the status of \bareosFd} - # check if bareos-fd is started by system: - sudo launchctl list org.bareos.bareos-fd - - # get process id (PID) of bareos-fd - pgrep bareos-fd - - # show files opened by bareos-fd - sudo lsof -p `pgrep bareos-fd` - - # check what process is listening on the \bareosFd port - sudo lsof -n -iTCP:9102 | grep LISTEN - \end{commands} - -You can also manually start bareos-fd in debug mode by: - -.. raw:: latex - - \begin{commands}{Start \bareosFd in debug mode} - sudo /usr/local/sbin/bareos-fd -f -d 100 - \end{commands} - -.. |image| image:: \idir univention-configuration-registry-settings - :width: 100.0% -.. |image| image:: \idir univention-ucs-overview-administration - :width: 80.0% -.. |image| image:: \idir univention-client-job-activation - :width: 80.0% diff --git a/docs/manuals/en/new_main_reference/source/tables.rst b/docs/manuals/en/new_main_reference/source/tables.rst index efaaba8eb1e..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/tables.rst +++ b/docs/manuals/en/new_main_reference/source/tables.rst @@ -1,115 +1 @@ -Catalog Tables -============== -.. index:: General; Catalog -.. _`Catalog`: - - -Bareos stores its information in a database, named Catalog. It is -configured by :ref:`DirectorResourceCatalog`. - -Job ---- - -.. index:: - triple: General; Catalog; Job -.. _`Catalog`: - -.. index:: - triple: General; Job; Catalog -.. _`Job`: - - -JobStatus -~~~~~~~~~ - -.. index:: - triple: General; Job; JobStatus -.. _`Job`: - -.. index:: - triple: General; Catalog!Job; JobStatus -.. _`Catalog!Job`: - - -The status of a Bareos job is stored as abbreviation in the Catalog -database table Job. It is also displayed by some bconsole commands, eg. -:command:`list jobs`. - -This table lists the abbreviations together with its description and -weight. The weight is used, when multiple states are applicable for a -job. In this case, only the status with the highest weight/priority is -applied. - -+-----------------------+-----------------------+-----------------------+ -| **Abbr.** | :raw-latex:`\multicol | **Weight** | -| | umn{1}{c|}{\textbf{De | | -| | scription}}` | | -+=======================+=======================+=======================+ -| C | Created, not yet | 15 | -| | running | | -+-----------------------+-----------------------+-----------------------+ -| R | Running | 15 | -+-----------------------+-----------------------+-----------------------+ -| B | Blocked | 15 | -+-----------------------+-----------------------+-----------------------+ -| T | Completed | 10 | -| | successfully | | -+-----------------------+-----------------------+-----------------------+ -| E | Terminated with | 25 | -| | errors | | -+-----------------------+-----------------------+-----------------------+ -| e | Non-fatal error | 20 | -+-----------------------+-----------------------+-----------------------+ -| f | Fatal error | 100 | -+-----------------------+-----------------------+-----------------------+ -| D | Verify found | 15 | -| | differences | | -+-----------------------+-----------------------+-----------------------+ -| A | Canceled by user | 90 | -+-----------------------+-----------------------+-----------------------+ -| I | Incomplete job | 15 | -+-----------------------+-----------------------+-----------------------+ -| L | Committing data | 15 | -+-----------------------+-----------------------+-----------------------+ -| W | Terminated with | 20 | -| | warnings | | -+-----------------------+-----------------------+-----------------------+ -| l | Doing data despooling | 15 | -+-----------------------+-----------------------+-----------------------+ -| q | Queued waiting for | 15 | -| | device | | -+-----------------------+-----------------------+-----------------------+ -| F | Waiting for Client | 15 | -+-----------------------+-----------------------+-----------------------+ -| S | Waiting for Storage | 15 | -| | daemon | | -+-----------------------+-----------------------+-----------------------+ -| m | Waiting for new media | 15 | -+-----------------------+-----------------------+-----------------------+ -| M | Waiting for media | 15 | -| | mount | | -+-----------------------+-----------------------+-----------------------+ -| s | Waiting for storage | 15 | -| | resource | | -+-----------------------+-----------------------+-----------------------+ -| j | Waiting for job | 15 | -| | resource | | -+-----------------------+-----------------------+-----------------------+ -| c | Waiting for client | 15 | -| | resource | | -+-----------------------+-----------------------+-----------------------+ -| d | Waiting on maximum | 15 | -| | jobs | | -+-----------------------+-----------------------+-----------------------+ -| t | Waiting on start time | 15 | -+-----------------------+-----------------------+-----------------------+ -| p | Waiting on higher | 15 | -| | priority jobs | | -+-----------------------+-----------------------+-----------------------+ -| i | Doing batch insert | 15 | -| | file records | | -+-----------------------+-----------------------+-----------------------+ -| a | SD despooling | 15 | -| | attributes | | -+-----------------------+-----------------------+-----------------------+ diff --git a/docs/manuals/en/new_main_reference/source/tape-without-autochanger.rst b/docs/manuals/en/new_main_reference/source/tape-without-autochanger.rst index 19a20f063ca..4998c2f1d1c 100644 --- a/docs/manuals/en/new_main_reference/source/tape-without-autochanger.rst +++ b/docs/manuals/en/new_main_reference/source/tape-without-autochanger.rst @@ -3,31 +3,19 @@ Using Tape Drives without Autochanger ===================================== -.. index:: - triple: General; Strategy; Backup -.. _`Strategy`: - -.. index:: General; Backup Strategies -.. _`Backup Strategies`: - +:raw-latex:`\index[general]{Strategy!Backup}` +:raw-latex:`\index[general]{Backup Strategies}` Although Recycling and Backing Up to Disk Volume have been discussed in previous chapters, this chapter is meant to give you an overall view of possible backup strategies and to explain their advantages and -disadvantages. - -.. _`Simple`: Simple +disadvantages. :raw-latex:`\label{Simple}` Simple One Tape Backup ---------------------- -.. index:: - triple: General; Backup; One Tape -.. _`Backup`: - -.. index:: General; One Tape Backup -.. _`One Tape Backup`: - +:raw-latex:`\index[general]{Backup!One Tape}` +:raw-latex:`\index[general]{One Tape Backup}` Probably the simplest strategy is to back everything up to a single tape and insert a new (or recycled) tape when it fills and Bareos requests a @@ -71,17 +59,12 @@ followed by daily Incremental backups. To minimize the amount of data written to the tape, one can do a Full backup once a month on the first Sunday of the month, a Differential backup on the 2nd-5th Sunday of the month, and incremental backups the rest of the week. - - -.. _`Manual`: Manual +:raw-latex:`\label{Manual}` Manually Changing Tapes ----------------------- -.. index:: - triple: General; Tape; Manually Changing -.. _`Tape`: - +:raw-latex:`\index[general]{Tape!Manually Changing}` If you use the strategy presented above, Bareos will ask you to change the tape, and you will **unmount** it and then remount it when you have @@ -148,20 +131,13 @@ are several ways to get Bareos to release the tape: \normalsize - - -.. _`Daily`: Daily +:raw-latex:`\label{Daily}` Daily Tape Rotation ------------------- -.. index:: - triple: General; Rotation; Daily Tape -.. _`Rotation`: - -.. index:: General; Daily Tape Rotation -.. _`Daily Tape Rotation`: - +:raw-latex:`\index[general]{Rotation!Daily Tape}` +:raw-latex:`\index[general]{Daily Tape Rotation}` This scheme is quite different from the one mentioned above in that a Full backup is done to a different tape every day of the week. diff --git a/docs/manuals/en/new_main_reference/source/tls.rst b/docs/manuals/en/new_main_reference/source/tls.rst index 346bb02ec6e..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/tls.rst +++ b/docs/manuals/en/new_main_reference/source/tls.rst @@ -1,324 +1 @@ -.. _CommEncryption: -Transport Encryption -==================== - - - -.. _`sec:TransportEncryption`: sec:TransportEncryption -.. index:: General; Communications Encryption -.. _`Communications Encryption`: - -.. index:: - triple: General; Encryption; Communication -.. _`Encryption`: - -.. index:: - triple: General; Encryption; Transport -.. _`Encryption`: - -.. index:: General; Transport Encryption -.. _`Transport Encryption`: - -:raw-latex:`\index[general]{TLS}` .. index:: General; SSL -:raw-latex:`\index[general]{TLS}` .. _`SSL`: -:raw-latex:`\index[general]{TLS}` - -Bareos TLS (Transport Layer Security) is built-in network encryption -code to provide secure network transport similar to that offered by -:command:`stunnel` or :command:`ssh`. The data -written to Volumes by the Storage daemon is not encrypted by this code. -For data encryption, please see the -:ref:`DataEncryption` chapter. - -The initial Bacula encryption implementation has been written by Landon -Fuller. - -Supported features of this code include: - -- Client/Server TLS Requirement Negotiation - -- TLSv1 Connections with Server and Client Certificate Validation - -- Forward Secrecy Support via Diffie-Hellman Ephemeral Keying - -This document will refer to both :raw-latex:`\bquote{server}` and -:raw-latex:`\bquote{client}` contexts. These terms refer to the -accepting and initiating peer, respectively. - -Diffie-Hellman anonymous ciphers are not supported by this code. The use -of DH anonymous ciphers increases the code complexity and places -explicit trust upon the two-way CRAM-MD5 implementation. CRAM-MD5 is -subject to known plaintext attacks, and it should be considered -considerably less secure than PKI certificate-based authentication. - -.. _TlsDirectives: - -TLS Configuration Directives ----------------------------- - -Additional configuration directives have been added to all the daemons -(Director, File daemon, and Storage daemon) as well as the various -different Console programs. These directives are defined as follows: - -.. raw:: latex - - \begin{description} - \directive{dir}{TLS Enable}{yes{\textbar}no}{}{no}{}% - Enable TLS support. Without setting \configdirective{TLS Require}=yes, - the connection can fall back to unencrypted connection, - if the other side does not support TLS. - - \directive{dir}{TLS Require}{yes{\textbar}no}{}{no}{}% - Require TLS connections. - If TLS is not required, - then Bareos will connect with other daemons either with or without TLS depending - on what the other daemon requests. - If TLS is required, - then Bareos will refuse any connection that does not use TLS. - \configdirective{TLS Require}=yes implicitly sets \configdirective{TLS Enable}=yes. - - \directive{dir}{TLS Certificate}{filename}{}{}{}% - The full path and filename of a PEM encoded TLS certificate. It can be - used as either a client or server certificate. - It is used because PEM files are base64 encoded and hence ASCII - text based rather than binary. - They may also contain encrypted information. - - \directive{dir}{TLS Key}{filename}{}{}{}% - The full path and filename of a PEM encoded TLS private key. It must - correspond to the certificate specified in the \configdirective{TLS Certificate} configuration directive. - - \directive{dir}{TLS Verify Peer}{yes{\textbar}no}{}{}{}% - Request and verify the peers certificate. - - In server context, unless the \configdirective{TLS Allowed CN} configuration directive is specified, - any client certificate signed by a known-CA will be accepted. - - In client context, the server certificate CommonName attribute is checked against - the \configdirective{Address} and \configdirective{TLS Allowed CN} configuration directives. - - - \directive{dir}{TLS Allowed CN}{stringlist}{}{}{}% - Common name attribute of allowed peer certificates. - If \configdirective{TLS Verify Peer}=yes, all connection request certificates - will be checked against this list. - - This directive may be specified more than once. - - - \directive{dir}{TLS CA Certificate File}{filename}{}{}{}% - The full path and filename specifying a - PEM encoded TLS CA certificate(s). Multiple certificates are - permitted in the file. - - In a client context, one of - \configdirective{TLS CA Certificate File} or \configdirective{TLS CA Certificate Dir} - is required. - - In a server context, it is only required if \configdirective{TLS Verify Peer} is used. - - \directive{dir}{TLS CA Certificate Dir}{directory}{}{}{}% - Full path to TLS CA certificate directory. In the current implementation, - certificates must be stored PEM encoded with OpenSSL-compatible hashes, - which is the subject name's hash and an extension of {\bf .0}. - - In a client context, one of - \configdirective{TLS CA Certificate File} or \configdirective{TLS CA Certificate Dir} - is required. - - In a server context, it is only required if \configdirective{TLS Verify Peer} is used. - - - \directive{dir}{TLS DH File}{filename}{}{}{}% - Path to PEM encoded Diffie-Hellman parameter file. If this directive is - specified, DH key exchange will be used for the ephemeral keying, allowing - for forward secrecy of communications. DH key exchange adds an additional - level of security because the key used for encryption/decryption by the - server and the client is computed on each end and thus is never passed over - the network if Diffie-Hellman key exchange is used. Even if DH key - exchange is not used, the encryption/decryption key is always passed - encrypted. This directive is only valid within a server context. - - To generate the parameter file, you - may use openssl: - - \begin{commands}{create DH key} - openssl dhparam -out dh1024.pem -5 1024 - \end{commands} - - \end{description} - -Getting TLS Certificates ------------------------- - -To get a trusted certificate (CA or Certificate Authority signed -certificate), you will either need to purchase certificates signed by a -commercial CA or become a CA yourself, and thus you can sign all your -own certificates. - -Bareos is known to work well with RSA certificates. - -You can use programs like -`xca `_ or TinyCA to -easily manage your own CA with a Graphical User Interface. - -Example TLS Configuration Files -------------------------------- - -.. index:: - triple: General; Example; TLS Configuration Files -.. _`Example`: - -.. index:: General; TLS Configuration Files -.. _`TLS Configuration Files`: - - -An example of the TLS portions of the configuration files are listed -below. - -Another example can be found at -:raw-latex:`\bareosTlsConfigurationExample`. - -Bareos Director -~~~~~~~~~~~~~~~ - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-dir}{director}{bareos-dir} - Director { # define myself - Name = bareos-dir - ... - TLS Enable = yes - TLS Require = yes - TLS CA Certificate File = /etc/bareos/tls/ca.pem - # This is a server certificate, used for incoming - # (console) connections. - TLS Certificate = /etc/bareos/tls/bareos-dir.example.com-cert.pem - TLS Key = /etc/bareos/tls/bareos-dir.example.com-key.pem - TLS Verify Peer = yes - TLS Allowed CN = "bareos@backup1.example.com" - TLS Allowed CN = "administrator@example.com" - } - \end{bareosConfigResource} - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-dir}{storage}{File} - Storage { - Name = File - Address = bareos-sd1.example.com - ... - TLS Require = yes - TLS CA Certificate File = /etc/bareos/tls/ca.pem - # This is a client certificate, used by the director to - # connect to the storage daemon - TLS Certificate = /etc/bareos/tls/bareos-dir.example.com-cert.pem - TLS Key = /etc/bareos/tls/bareos-dir.example.com-key.pem - TLS Allowed CN = bareos-sd1.example.com - } - \end{bareosConfigResource} - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-dir}{client}{client1-fd} - Client { - Name = client1-fd - Address = client1.example.com - ... - TLS Enable = yes - TLS Require = yes - TLS CA Certificate File = /etc/bareos/tls/ca.pem - TLS Certificate = "/etc/bareos/tls/bareos-dir.example.com-cert.pem" - TLS Key = "/etc/bareos/tls/bareos-dir.example.com-key.pem" - TLS Allowed CN = client1.example.com - } - \end{bareosConfigResource} - -Bareos Storage Daemon -~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-sd}{storage}{bareos-sd1} - Storage { - Name = bareos-sd1 - ... - # These TLS configuration options are used for incoming - # file daemon connections. Director TLS settings are handled - # in Director resources. - TLS Enable = yes - TLS Require = yes - TLS CA Certificate File = /etc/bareos/tls/ca.pem - # This is a server certificate. It is used by connecting - # file daemons to verify the authenticity of this storage daemon - TLS Certificate = /etc/bareos/tls/bareos-sd1.example.com-cert.pem - TLS Key = /etc/bareos/tls/bareos-sd1.example.com-key.pem - # Peer verification must be disabled, - # or all file daemon CNs must be listed in "TLS Allowed CN". - # Peer validity is verified by the storage connection cookie - # provided to the File Daemon by the Director. - TLS Verify Peer = no - } - \end{bareosConfigResource} - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-sd}{director}{bareos-dir} - Director { - Name = bareos-dir - ... - TLS Enable = yes - TLS Require = yes - TLS CA Certificate File = /etc/bareos/tls/ca.pem - # This is a server certificate. It is used by the connecting - # director to verify the authenticity of this storage daemon - TLS Certificate = /etc/bareos/tls/bareos-sd1.example.com-cert.pem - TLS Key = /etc/bareos/tls/bareos-sd1.example.com-key.pem - # Require the connecting director to provide a certificate - # with the matching CN. - TLS Verify Peer = yes - TLS Allowed CN = "bareos-dir.example.com" - } - \end{bareosConfigResource} - -Bareos File Daemon -~~~~~~~~~~~~~~~~~~ - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-fd}{client}{myself} - Client { - Name = client1-fd - ... - # you need these TLS entries so the SD and FD can - # communicate - TLS Enable = yes - TLS Require = yes - - TLS CA Certificate File = /etc/bareos/tls/ca.pem - TLS Certificate = /etc/bareos/tls/client1.example.com-cert.pem - TLS Key = /etc/bareos/tls/client1.example.com-key.pem - - TLS Allowed CN = bareos-sd1.example.com - } - \end{bareosConfigResource} - -.. raw:: latex - - \begin{bareosConfigResource}{bareos-fd}{director}{bareos-dir} - Director { - Name = bareos-dir - ... - TLS Enable = yes - TLS Require = yes - TLS CA Certificate File = /etc/bareos/tls/ca.pem - # This is a server certificate. It is used by connecting - # directors to verify the authenticity of this file daemon - TLS Certificate = /etc/bareos/tls/client11.example.com-cert.pem - TLS Key = /etc/bareos/tls/client1.example.com-key.pem - TLS Verify Peer = yes - # Allow only the Director to connect - TLS Allowed CN = "bareos-dir.example.com" - } - \end{bareosConfigResource} diff --git a/docs/manuals/en/new_main_reference/source/troubleshooting.rst b/docs/manuals/en/new_main_reference/source/troubleshooting.rst index 8fb9ee53b7d..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/troubleshooting.rst +++ b/docs/manuals/en/new_main_reference/source/troubleshooting.rst @@ -1,1810 +1 @@ -Debug Messages -============== -The Bareos programs contain a lot of debug messages. Normally, these are -not printed. See the :ref:`setdebug bcommandSetdebug` -chapter about how to enable them. - -Client Access Problems -====================== - - -.. index:: - triple: General; Problem; Cannot Access a Client There are -several reasons why a |bareosDir| could not contact a client -on a different machine. They are: - -- Check if the client file daemon is really running. - -- The Client address or port is incorrect or not resolved by DNS. See - if you can ping the client machine using the same address as in the - Client record. - -- You have a firewall, and it is blocking traffic on port 9102 between - the Director’s machine and the Client’s machine (or on port 9103 - between the Client and the Storage daemon machines). - -- If your system is using Tcpwrapper (*hosts.allow* - or *hosts.deny* file), verify that is permitting - access. - -- Your password or names are not correct in both the Director and the - Client machine. Try configuring everything identical to how you run - the client on the same machine as the Director, but just change the - address. If that works, make the other changes one step at a time - until it works. - -Some of the DNS and Firewall problems can be circumvented by configuring -clients using :ref:`sec:ClientInitiatedConnection` or as -:ref:`PassiveClient`. - -Difficulties Connecting from the FD to the SD ---------------------------------------------- - - -.. index:: - triple: General; Problem; Connecting from the FD to the SD - -If you are having difficulties getting one or more of your File daemons -to connect to the Storage daemon, it is most likely because you have not -used a fully qualified domain name on the -Address directive. -That is the resolver on the File daemon’s machine (not on the -Director’s) must be able to resolve the name you supply into an IP -address. An example of an address that is guaranteed not to work: -**localhost**. An example that may work: -**bareos-sd1**. An example that is more likely to work: -**bareos-sd1.example.com**. - -You can verify how a |bareosFd| resolves a DNS name by the -following command: - -.. raw:: latex - - \begin{bconsole}{Test DNS resolution of the \bareosFd \name{bareos-fd}} - *resolve client=bareos-fd NONEXISTINGHOSTNAME - Connecting to Client bareos-fd at bareos:9102 - bareos-fd: Failed to resolve NONEXISTINGHOSTNAME - *resolve client=bareos-fd bareos-sd1.example.com - Connecting to Client bareos-fd at bareos:9102 - bareos-fd resolves bareos-sd1.example.com to host[ipv4;192.168.0.1] - \end{bconsole} - -If your address is correct, then make sure that no other program is -using the port 9103 on the Storage daemon’s machine. The Bacula project -has reserved these port numbers by IANA, therefore they should only be -used by Bacula and its replacements like Bareos. However, apparently -some HP printers do use these port numbers. A -:command:`netstat -lntp` on the |bareosSd| ’s -machine can determine who is listening on the 9103 port (used for FD to -SD communications in Bareos). - -Authorization Errors --------------------- - - -.. index:: - triple: General; Problem; Authorization Errors -.. index:: General; Concurrent Jobs -.. _AuthorizationErrors: - -For security reasons, Bareos requires that both the File daemon and the -Storage daemon know the name of the Director as well as its password. As -a consequence, if you change the Director’s name or password, you must -make the corresponding change in the Storage daemon’s and in the File -daemon’s configuration files. - -During the authorization process, the Storage daemon and File daemon -also require that the Director authenticates itself, so both ends -require the other to have the correct name and password. - -If you have edited the configuration files and modified any name or any -password, and you are getting authentication errors, then your best bet -is to go back to the original configuration files generated by the -Bareos installation process. Make only the absolutely necessary -modifications to these files – e.g. add the correct email address. Then -follow the instructions in the -:ref:`Running Bareos TutorialChapter` chapter of this -manual. You will run a backup to disk and a restore. Only when that -works, should you begin customization of the configuration files. - -Some users report that authentication fails if there is not a proper -reverse DNS lookup entry for the machine. This seems to be a requirement -of gethostbyname(), which is what Bareos uses to translate names into IP -addresses. If you cannot add a reverse DNS entry, or you don’t know how -to do so, you can avoid the problem by specifying an IP address rather -than a machine name in the appropriate Bareos configuration file. - -Here is a picture that indicates what names/passwords in which -files/Resources must match up: - -|image| - -In the left column, you will find the Director, Storage, and Client -resources, with their names and passwords – these are all in the - |bareosDir| configuration. The right column is where the -corresponding values should be found in the Console, Storage daemon -(SD), and File daemon (FD) configuration files. - -Another thing to check is to ensure that the Bareos component you are -trying to access has -:raw-latex:`\configdirective{Maximum Concurrent Jobs}` set large enough -to handle each of the Jobs and the Console that want to connect -simultaneously. Once the maximum connections has been reached, each -Bareos component will reject all new connections. - -Concurrent Jobs -=============== - - -.. index:: - triple: General; Job; Concurrent Jobs -.. index:: General; Running Concurrent Jobs -.. index:: General; Concurrent Jobs - -Bareos can run multiple concurrent jobs. Using the -:raw-latex:`\configdirective{Maximum Concurrent Jobs}` directives, you -can configure how many and which jobs can be run simultaneously: - - |bareosDir| - | - - - Maximum Concurrent Jobs - - - Maximum Concurrent Jobs - - - Maximum Concurrent Jobs - - - Maximum Concurrent Jobs - - |bareosSd| - | - - - Maximum Concurrent Jobs - - - Maximum Concurrent Jobs - - |bareosFd| - | - - - Maximum Concurrent Jobs - -For example, if you want two different jobs to run simultaneously -backing up the same Client to the same Storage device, they will run -concurrently only if you have set -:raw-latex:`\configdirective{Maximum Concurrent Jobs}` greater than one -in the :raw-latex:`\configresource{Director}` resource, the -:raw-latex:`\configresource{Client}` resource, and the -:raw-latex:`\configresource{Storage}` resource in - |bareosDir| configuration. - -.. _sec:Interleaving: When running concurrent jobs -without :ref:`sec:DataSpooling`, the volume format -becomes more complicated, consequently, restores may take longer if -Bareos must sort through interleaved volume blocks from multiple -simultaneous jobs. This can be avoided by having each simultaneous job -write to a different volume or by using data spooling We recommend that -you read the :ref:`sec:DataSpooling` of this manual -first, then test your multiple concurrent backup including restore -testing before you put it into production. - -When using random access media as backup space (e.g. disk), you should -also read the chapter about :ref:`ConcurrentDiskJobs`. - -Below is a super stripped down *bareos-dir.conf* file -showing you the four places where the the file must be modified to allow -the same job :raw-latex:`\resourcename{Dir}{Job}{NightlySave}` to run up -to four times concurrently. The change to the Job resource is not -necessary if you want different Jobs to run at the same time, which is -the normal case. - -.. raw:: latex - - \begin{bconfig}{Concurrent Jobs Example} - # - # Bareos Director Configuration file -- bareos-dir.conf - # - Director { - Name = rufus-dir - Maximum Concurrent Jobs = 4 - ... - } - Job { - Name = "NightlySave" - Maximum Concurrent Jobs = 4 - Client = rufus-fd - Storage = File - ... - } - Client { - Name = rufus-fd - Maximum Concurrent Jobs = 4 - ... - } - Storage { - Name = File - Maximum Concurrent Jobs = 4 - ... - } - \end{bconfig} - -Tape Labels: ANSI or IBM -======================== - - -.. index:: - triple: General; Label; Tape Labels - -.. index:: - triple: General; Tape!Label; ANSI - -.. index:: - triple: General; Tape!Label; IBM - -By default, Bareos uses its own tape label (see -:ref:`backward-compability-tape-format` and -Label Type). However, -Bareos also supports reading and write ANSI and IBM tape labels. - -Reading -------- - -Reading ANSI/IBM labels is important, if some of your tapes are used by -other programs that also support ANSI/IBM labels. For example, LTFS -tapes -.. index:: - triple: General; Tape; LTFS are indicated by an ANSI -label. - -If your are running Bareos in such an environment, you must set -Check Labels to yes, -otherwise Bareos will not recognize that these tapes are already in use. - -Writing -------- - -To configure Bareos to also write ANSI/IBM tape labels, use -Label Type or -Label Type. With the -proper configuration, you can force Bareos to require ANSI or IBM -labels. - -Even though Bareos will recognize and write ANSI and IBM labels, it -always writes its own tape labels as well. - -If you have labeled your volumes outside of Bareos, then the ANSI/IBM -label will be recognized by Bareos only if you have created the HDR1 -label with **BAREOS.DATA** in the filename field (starting with -character 5). If Bareos writes the labels, it will use this information -to recognize the tape as a Bareos tape. This allows ANSI/IBM labeled -tapes to be used at sites with multiple machines and multiple backup -programs. - -Tape Drive -========== - - -.. index:: - triple: General; Problem; Tape - -This chapter is concerned with testing and configuring your tape drive -to make sure that it will work properly with Bareos using the **btape** -program. - -Get Your Tape Drive Working ---------------------------- - -In general, you should follow the following steps to get your tape drive -to work with Bareos. Start with a tape mounted in your drive. If you -have an autochanger, load a tape into the drive. We use **/dev/nst0** as -the tape drive name, you will need to adapt it according to your system. - -Do not proceed to the next item until you have succeeded with the -previous one. - -#. Make sure that Bareos (the Storage daemon) is not running or that you - have **unmount**\ ed the drive you will use for testing. - -#. Use tar to write to, then read from your drive: - - - - :: - - mt -f /dev/nst0 rewind - tar cvf /dev/nst0 . - mt -f /dev/nst0 rewind - tar tvf /dev/nst0 - - - -#. Make sure you have a valid and correct Device resource corresponding - to your drive. For Linux users, generally, the default one works. For - FreeBSD users, there are two possible Device configurations (see - below). For other drives and/or OSes, you will need to first ensure - that your system tape modes are properly setup (see below), then - possibly modify you Device resource depending on the output from the - btape program (next item). When doing this, you should consult the - :raw-latex:`\ilink{Storage Daemon - Configuration}{StoredConfChapter}` of this manual. - -#. If you are using a Fibre Channel to connect your tape drive to - Bareos, please be sure to disable any caching in the NSR (network - storage router, which is a Fibre Channel to SCSI converter). - -#. Run the btape **test** command: - - - - :: - - btape /dev/nst0 - test - - - - It isn’t necessary to run the autochanger part of the test at this - time, but do not go past this point until the basic test succeeds. If - you do have an autochanger, please be sure to read the - :raw-latex:`\ilink{Autochanger - chapter}{AutochangersChapter}` of this manual. - -#. Run the btape **fill** command, preferably with two volumes. This can - take a long time. If you have an autochanger and it is configured, - Bareos will automatically use it. If you do not have it configured, - you can manually issue the appropriate **mtx** command, or press the - autochanger buttons to change the tape when requested to do so. - -#. Run Bareos, and backup a reasonably small directory, say 60 - Megabytes. Do three successive backups of this directory. - -#. Stop Bareos, then restart it. Do another full backup of the same - directory. Then stop and restart Bareos. - -#. Do a restore of the directory backed up, by entering the following - restore command, being careful to restore it to an alternate - location: - - - - :: - - restore select all done - yes - - - - Do a **diff** on the restored directory to ensure it is identical to - the original directory. If you are going to backup multiple different - systems (Linux, Windows, Mac, Solaris, FreeBSD, ...), be sure you - test the restore on each system type. - -#. If you have an autochanger, you should now go back to the btape - program and run the autochanger test: - - - - :: - - btape /dev/nst0 - auto - - - - Adjust your autochanger as necessary to ensure that it works - correctly. See the - :ref:`Autochanger chapter AutochangerTesting` of this - manual for a complete discussion of testing your autochanger. - -:raw-latex:`\hide{ -If you have reached this point, you stand a good chance of having everything -work. If you get into trouble at any point, {\bf carefully} read the -documentation given below. - -\subsection{btape} -\label{btape1} -\index[general]{btape} - -This program permits a number of elementary tape operations via a tty command -interface. The {\bf test} command, described below, can be very useful for -testing tape drive compatibility problems. Aside from initial testing of tape -drive compatibility with {\bf Bareos}, {\bf btape} will be mostly used by -developers writing new tape drivers. - -{\bf btape} can be dangerous to use with existing {\bf Bareos} tapes because -it will relabel a tape or write on the tape if so requested regardless of -whether or not the tape contains valuable data, so please be careful and use -it only on blank tapes. - -To work properly, \command{btape} needs to read the Storage daemon's configuration. - -The physical device name or the Device resource name must be specified on the -command line, and this same device name must be present in the Storage -daemon's configuration file read by \command{btape} - -\footnotesize -\begin{verbatim} -Usage: btape [options] device_name - -b specify bootstrap file - -c set configuration file to file - -d set debug level to nn - -p proceed inspite of I/O errors - -s turn off signals - -v be verbose - -? print this message. -\end{verbatim} -\normalsize - - - - -\label{problems1} -\subsection{Tips for Resolving Problems} -\index[general]{Problems!Tips for Resolving} -\index[general]{Tips for Resolving Problems} - -\label{CannotRestore} -\subsubsection{Bareos Saves But Cannot Restore Files} -\index[general]{Files!Bareos Saves But Cannot Restore} -\index[general]{Bareos Saves But Cannot Restore Files} - -If you are getting error messages such as: - -\footnotesize -\begin{verbatim} -Volume data error at 0:1! Wanted block-id: "BB02", got "". Buffer discarded -\end{verbatim} -\normalsize - -It is very likely that Bareos has tried to do block positioning and ended up -at an invalid block. This can happen if your tape drive is in fixed block mode -while Bareos's default is variable blocks. Note that in such cases, Bareos is -perfectly able to write to your Volumes (tapes), but cannot position to read -them. - -There are two possible solutions. - -\begin{enumerate} -\item The first and best is to always ensure that your drive is in variable - block mode. Note, it can switch back to fixed block mode on a reboot or if - another program uses the drive. So on such systems you need to modify the - Bareos startup files to explicitly set: - -\footnotesize -\begin{verbatim} -mt -f /dev/nst0 defblksize 0 -\end{verbatim} -\normalsize - -or whatever is appropriate on your system. Note, if you are running a Linux -system, and the above command does not work, it is most likely because you -have not loaded the appropriate {\bf mt} package, which is often called -{\bf mt\_st}, but may differ according to your distribution. - -\item The second possibility, especially, if Bareos wrote while the drive was - in fixed block mode, is to turn off block positioning in Bareos. This is done - by adding: - -\footnotesize -\begin{verbatim} -Block Positioning = no -\end{verbatim} -\normalsize - -to the Device resource. This is not the recommended procedure because it can -enormously slow down recovery of files, but it may help where all else -fails. This directive is available in version 1.35.5 or later (and not yet -tested). -\end{enumerate} - -If you are getting error messages such as: -\footnotesize -\begin{verbatim} -Volume data error at 0:0! -Block checksum mismatch in block=0 len=32625 calc=345678 blk=123456 -\end{verbatim} -\normalsize - -You are getting tape read errors, and this is most likely due to -one of the following things: -\begin{enumerate} -\item An old or bad tape. -\item A dirty drive that needs cleaning (particularly for DDS drives). -\item A loose SCSI cable. -\item Old firmware in your drive. Make sure you have the latest firmware - loaded. -\item Computer memory errors. -\item Over-clocking your CPU. -\item A bad SCSI card. -\end{enumerate} - - -\label{opendevice} -\subsubsection{Bareos Cannot Open the Device} -\index[general]{Device!Bareos Cannot Open the} -\index[general]{Bareos Cannot Open the Device} - -If you get an error message such as: - -\footnotesize -\begin{verbatim} -dev open failed: dev.c:265 stored: unable to open -device /dev/nst0:> ERR=No such device or address -\end{verbatim} -\normalsize - -the first time you run a job, it is most likely due to the fact that you -specified the incorrect device name on your {\bf Archive Device}. - -If Bareos works fine with your drive, then all off a sudden you get error -messages similar to the one shown above, it is quite possible that your driver -module is being removed because the kernel deems it idle. This is done via -{\bf crontab} with the use of {\bf rmmod -a}. To fix the problem, you can -remove this entry from {\bf crontab}, or you can manually {\bf modprob} your -driver module (or add it to the local startup script). Thanks to Alan Brown -for this tip. -\label{IncorrectFiles} - -\subsubsection{Incorrect File Number} -\index[general]{Number!Incorrect File} -\index[general]{Incorrect File Number} - -When Bareos moves to the end of the medium, it normally uses the {\bf -ioctl(MTEOM)} function. Then Bareos uses the {\bf ioctl(MTIOCGET)} function to -retrieve the current file position from the {\bf mt\_fileno} field. Some SCSI -tape drivers will use a fast means of seeking to the end of the medium and in -doing so, they will not know the current file position and hence return a {\bf --1}. As a consequence, if you get {\bf "This is NOT correct!"} in the -positioning tests, this may be the cause. You must correct this condition in -order for Bareos to work. - -There are two possible solutions to the above problem of incorrect file -number: - -\begin{itemize} -\item Figure out how to configure your SCSI driver to keep track of the file - position during the MTEOM request. This is the preferred solution. -\item Modify the {\bf Device} resource of your {\bf bareos-sd.conf} file to - include: - -\footnotesize -\begin{verbatim} -Hardware End of File = no -\end{verbatim} -\normalsize - -This will cause Bareos to use the MTFSF request to seek to the end of the -medium, and Bareos will keep track of the file number itself. -\end{itemize} - -\label{IncorrectBlocks} -\subsubsection{Incorrect Number of Blocks or Positioning Errors} -\index[general]{Testing!Incorrect Number of Blocks or Positioning Errors} -\index[general]{Incorrect Number of Blocks or Positioning Errors} - -{\bf Bareos's} preferred method of working with tape drives (sequential -devices) is to run in variable block mode, and this is what is set by default. -You should first ensure that your tape drive is set for variable block mode -(see below). - -If your tape drive is in fixed block mode and you have told Bareos to use -different fixed block sizes or variable block sizes (default), you will get -errors when Bareos attempts to forward space to the correct block (the kernel -driver's idea of tape blocks will not correspond to Bareos's). - -All modern tape drives support variable tape blocks, but some older drives (in -particular the QIC drives) as well as the ATAPI ide-scsi driver run only in -fixed block mode. The Travan tape drives also apparently must run in fixed -block mode (to be confirmed). - -Even in variable block mode, with the exception of the first record on the -second or subsequent volume of a multi-volume backup, Bareos will write blocks -of a fixed size. However, in reading a tape, Bareos will assume that for each -read request, exactly one block from the tape will be transferred. This the -most common way that tape drives work and is well supported by {\bf Bareos}. - -Drives that run in fixed block mode can cause serious problems for Bareos if -the drive's block size does not correspond exactly to {\bf Bareos's} block -size. In fixed block size mode, drivers may transmit a partial block or -multiple blocks for a single read request. From {\bf Bareos's} point of view, -this destroys the concept of tape blocks. It is much better to run in variable -block mode, and almost all modern drives run in -variable block mode. In order for Bareos to run in fixed block mode, you must -include the following records in the Storage daemon's Device resource -definition: - -\footnotesize -\begin{verbatim} -Minimum Block Size = nnn -Maximum Block Size = nnn -\end{verbatim} -\normalsize - -where {\bf nnn} must be the same for both records and must be identical to the -driver's fixed block size. - -We recommend that you avoid this configuration if at all possible by using -variable block sizes. - -If you must run with fixed size blocks, make sure they are not 512 bytes. This -is too small and the overhead that Bareos has with each record will become -excessive. If at all possible set any fixed block size to something like -64,512 bytes or possibly 32,768 if 64,512 is too large for your drive. See -below for the details on checking and setting the default drive block size. - -To recover files from tapes written in fixed block mode, see below. - -\label{TapeModes} -\subsubsection{Ensuring that the Tape Modes Are Properly Set -- {\bf Linux -Only}} -\index[general]{Ensuring that the Tape Modes Are Properly Set -- Linux Only} - -If you have a modern SCSI tape drive and you are having problems with the {\bf -test} command as noted above, it may be that some program has set one or more -of your SCSI driver's options to non-default values. For example, if your -driver is set to work in SysV manner, Bareos will not work correctly because -it expects BSD behavior. To reset your tape drive to the default values, you -can try the following, but {\bf ONLY} if you have a SCSI tape drive on a {\bf -Linux} system: - -\footnotesize -\begin{verbatim} -become super user -mt -f /dev/nst0 rewind -mt -f /dev/nst0 stoptions buffer-writes async-writes read-ahead -\end{verbatim} -\normalsize - -The above commands will clear all options and then set those specified. None -of the specified options are required by Bareos, but a number of other options -such as SysV behavior must not be set. Bareos does not support SysV tape -behavior. On systems other than Linux, you will need to consult your {\bf mt} -man pages or documentation to figure out how to do the same thing. This should -not really be necessary though -- for example, on both Linux and Solaris -systems, the default tape driver options are compatible with Bareos. -On Solaris systems, you must take care to specify the correct device -name on the {\bf Archive device} directive. See above for more details. - -You may also want to ensure that no prior program has set the default block -size, as happened to one user, by explicitly turning it off with: - -\footnotesize -\begin{verbatim} -mt -f /dev/nst0 defblksize 0 -\end{verbatim} -\normalsize - -If you are running a Linux -system, and the above command does not work, it is most likely because you -have not loaded the appropriate {\bf mt} package, which is often called -{\bf mt\_st}, but may differ according to your distribution. - -If you would like to know what options you have set before making any of the -changes noted above, you can now view them on Linux systems, thanks to a tip -provided by Willem Riede. Do the following: - -\footnotesize -\begin{verbatim} -become super user -mt -f /dev/nst0 stsetoptions 0 -grep st0 /var/log/messages -\end{verbatim} -\normalsize - -and you will get output that looks something like the following: - -\footnotesize -\begin{verbatim} -kernel: st0: Mode 0 options: buffer writes: 1, async writes: 1, read ahead: 1 -kernel: st0: can bsr: 0, two FMs: 0, fast mteom: 0, auto lock: 0, -kernel: st0: defs for wr: 0, no block limits: 0, partitions: 0, s2 log: 0 -kernel: st0: sysv: 0 nowait: 0 -\end{verbatim} -\normalsize - -Note, I have chopped off the beginning of the line with the date and machine -name for presentation purposes. - -Some people find that the above settings only last until the next reboot, so -please check this otherwise you may have unexpected problems. - -Beginning with Bareos version 1.35.8, if Bareos detects that you are running -in variable block mode, it will attempt to set your drive appropriately. All -OSes permit setting variable block mode, but some OSes do not permit setting -the other modes that Bareos needs to function properly. - - -\subsubsection{Tape Modes on FreeBSD} -\label{FreeBSDTapes} -\index[general]{FreeBSD!Tape Modes on} -\index[general]{Tape Modes on FreeBSD} - -On most FreeBSD systems such as 4.9 and most tape drives, Bareos should run -with: - -\footnotesize -\begin{verbatim} -mt -f /dev/nsa0 seteotmodel 2 -mt -f /dev/nsa0 blocksize 0 -mt -f /dev/nsa0 comp enable -\end{verbatim} -\normalsize - -You might want to put those commands in a startup script to make sure your -tape driver is properly initialized before running Bareos, because -depending on your system configuration, these modes may be reset if a -program other than Bareos uses the drive or when your system is rebooted. - -Then according to what the {\bf btape test} command returns, you will probably -need to set the following (see below for an alternative): - -\footnotesize -\begin{verbatim} - Hardware End of Medium = no - BSF at EOM = yes - Backward Space Record = no - Backward Space File = no - Fast Forward Space File = no - TWO EOF = yes -\end{verbatim} -\normalsize - -Then be sure to run some append tests with Bareos where you start and stop -Bareos between appending to the tape, or use {\bf btape} version 1.35.1 or -greater, which includes simulation of stopping/restarting Bareos. - -Please see the file {\bf platforms/freebsd/pthreads-fix.txt} in the main -Bareos directory concerning {\bf important} information concerning -compatibility of Bareos and your system. A much more optimal Device -configuration is shown below, but does not work with all tape drives. Please -test carefully before putting either into production. - -Note, for FreeBSD 4.10-RELEASE, using a Sony TSL11000 L100 DDS4 with an -autochanger set to variable block size and DCLZ compression, Brian McDonald -reports that to get Bareos to append correctly between Bareos executions, -the correct values to use are: - -\footnotesize -\begin{verbatim} -mt -f /dev/nsa0 seteotmodel 1 -mt -f /dev/nsa0 blocksize 0 -mt -f /dev/nsa0 comp enable -\end{verbatim} -\normalsize - -and - -\footnotesize -\begin{verbatim} - Hardware End of Medium = no - BSF at EOM = no - Backward Space Record = no - Backward Space File = no - Fast Forward Space File = yes - TWO EOF = no -\end{verbatim} -\normalsize - -This has been confirmed by several other people using different hardware. This -configuration is the preferred one because it uses one EOF and no backspacing -at the end of the tape, which works much more efficiently and reliably with -modern tape drives. - -Finally, here is a Device configuration that Danny Butroyd reports to work -correctly with the Overland Powerloader tape library using LT0-2 and -FreeBSD 5.4-Stable: - -\footnotesize -\begin{verbatim} -# Overland Powerloader LT02 - 17 slots single drive -Device { - Name = Powerloader - Media Type = LT0-2 - Archive Device = /dev/nsa0 - AutomaticMount = yes; - AlwaysOpen = yes; - RemovableMedia = yes; - RandomAccess = no; - Changer Command = "/usr/local/sbin/mtx-changer %c %o %S %a %d" - Changer Device = /dev/pass2 - AutoChanger = yes - Alert Command = "sh -c 'tapeinfo -f %c |grep TapeAlert|cat'" - - # FreeBSD Specific Settings - Offline On Unmount = no - Hardware End of Medium = no - BSF at EOM = yes - Backward Space Record = no - Fast Forward Space File = no - TWO EOF = yes -} - -The following Device resource works fine with Dell PowerVault 110T and -120T devices on both FreeBSD 5.3 and on NetBSD 3.0. It also works -with Sony AIT-2 drives on FreeBSD. -\footnotesize -\begin{verbatim} -Device { - ... - # FreeBSD/NetBSD Specific Settings - Hardware End of Medium = no - BSF at EOM = yes - Backward Space Record = no - Fast Forward Space File = yes - TWO EOF = yes -} -\end{verbatim} -\normalsize - -On FreeBSD version 6.0, it is reported that you can even set -Backward Space Record = yes. - - - -\subsubsection{Finding your Tape Drives and Autochangers on FreeBSD} -\index[general]{FreeBSD!Finding Tape Drives and Autochangers} -\index[general]{Finding Tape Drives and Autochangers on FreeBSD} - -On FreeBSD, you can do a {\bf camcontrol devlist} as root to determine what -drives and autochangers you have. For example, - -\footnotesize -\begin{verbatim} -undef# camcontrol devlist - at scbus0 target 2 lun 0 (pass0,sa0) - at scbus0 target 4 lun 0 (pass1,sa1) - at scbus0 target 4 lun 1 (pass2) -\end{verbatim} -\normalsize - -from the above, you can determine that there is a tape drive on {\bf /dev/sa0} -and another on {\bf /dev/sa1} in addition since there is a second line for the -drive on {\bf /dev/sa1}, you know can assume that it is the control device for -the autochanger (i.e. {\bf /dev/pass2}). It is also the control device name to -use when invoking the tapeinfo program. E.g. - -\footnotesize -\begin{verbatim} -tapeinfo -f /dev/pass2 -\end{verbatim} -\normalsize - - -\label{fill} -\subsubsection{Using btape to Simulate Filling a Tape} -\index[general]{Using btape to Simulate Filling a Tape} -\index[general]{Tape!Using btape to Simulate Filling} - -Because there are often problems with certain tape drives or systems when end -of tape conditions occur, {\bf btape} has a special command {\bf fill} that -causes it to write random data to a tape until the tape fills. It then writes -at least one more Bareos block to a second tape. Finally, it reads back both -tapes to ensure that the data has been written in a way that Bareos can -recover it. Note, there is also a single tape option as noted below, which you -should use rather than the two tape test. See below for more details. - -This can be an extremely time consuming process (here it is about 6 hours) to -fill a full tape. Note, that btape writes random data to the tape when it is -filling it. This has two consequences: 1. it takes a bit longer to generate -the data, especially on slow CPUs. 2. the total amount of data is -approximately the real physical capacity of your tape, regardless of whether -or not the tape drive compression is on or off. This is because random data -does not compress very much. - -To begin this test, you enter the {\bf fill} command and follow the -instructions. There are two options: the simple single tape option and the -multiple tape option. Please use only the simple single tape option because -the multiple tape option still doesn't work totally correctly. If the single -tape option does not succeed, you should correct the problem before using -Bareos. -\label{RecoveringFiles} - -\subsection{Recovering Files Written With Fixed Block Sizes} -\index[general]{Recovering Files Written With Fixed Block Sizes} - -If you have been previously running your tape drive in fixed block mode -(default 512) and Bareos with variable blocks (default), then in version -1.32f-x and 1.34 and above, Bareos will fail to recover files because it does -block spacing, and because the block sizes don't agree between your tape drive -and Bareos it will not work. - -The long term solution is to run your drive in variable block mode as -described above. However, if you have written tapes using fixed block sizes, -this can be a bit of a pain. The solution to the problem is: while you are -doing a restore command using a tape written in fixed block size, ensure that -your drive is set to the fixed block size used while the tape was written. -Then when doing the {\bf restore} command in the Console program, do not -answer the prompt {\bf yes/mod/no}. Instead, edit the bootstrap file (the -location is listed in the prompt) using any ASCII editor. Remove all {\bf -VolBlock} lines in the file. When the file is re-written, answer the question, -and Bareos will run without using block positioning, and it should recover -your files. - -\label{BlockModes} -\subsection{Tape Blocking Modes} -\index[general]{Modes!Tape Blocking} -\index[general]{Tape Blocking Modes} - -SCSI tapes may either be written in {\bf variable} or {\bf fixed} block sizes. -Newer drives support both modes, but some drives such as the QIC devices -always use fixed block sizes. Bareos attempts to fill and write complete -blocks (default 65K), so that in normal mode (variable block size), Bareos -will always write blocks of the same size except the last block of a Job. If -Bareos is configured to write fixed block sizes, it will pad the last block of -the Job to the correct size. Bareos expects variable tape block size drives to -behave as follows: Each write to the drive results in a single record being -written to the tape. Each read returns a single record. If you request less -bytes than are in the record, only those number of bytes will be returned, but -the entire logical record will have been read (the next read will retrieve the -next record). Thus data from a single write is always returned in a single -read, and sequentially written records are returned by sequential reads. - -Bareos expects fixed block size tape drives to behave as follows: If a write -length is greater than the physical block size of the drive, the write will be -written as two blocks each of the fixed physical size. This single write may -become multiple physical records on the tape. (This is not a good situation). -According to the documentation, one may never write an amount of data that is -not the exact multiple of the blocksize (it is not specified if an error -occurs or if the the last record is padded). When reading, it is my -understanding that each read request reads one physical record from the tape. -Due to the complications of fixed block size tape drives, you should avoid -them if possible with Bareos, or you must be ABSOLUTELY certain that you use -fixed block sizes within Bareos that correspond to the physical block size of -the tape drive. This will ensure that Bareos has a one to one correspondence -between what it writes and the physical record on the tape. - -Please note that Bareos will not function correctly if it writes a block and -that block is split into two or more physical records on the tape. Bareos -assumes that each write causes a single record to be written, and that it can -sequentially recover each of the blocks it has written by using the same -number of sequential reads as it had written. - -\subsection{Details of Tape Modes} -\index[general]{Modes!Details} -\index[general]{Details of Tape Modes} -Rudolf Cejka has provided the following information concerning -certain tape modes and MTEOM. - -\begin{description} -\item[Tape level] - It is always possible to position filemarks or blocks, whereas - positioning to the end-of-data is only optional feature, however it is - implemented very often. SCSI specification also talks about optional - sequential filemarks, setmarks and sequential setmarks, but these are not - implemented so often. Modern tape drives keep track of file positions in - built-in chip (AIT, LTO) or at the beginning of the tape (SDLT), so there - is not any speed difference, if end-of-data or filemarks is used (I have - heard, that LTO-1 from all 3 manufacturers do not use its chip for file - locations, but a tape as in SDLT case, and I'm not sure about LTO-2 and - LTO-3 case). However there is a big difference, that end-of-data ignores - file position, whereas filemarks returns the real number of skipped - files, so OS can track current file number just in filemarks case. - -\item[OS level] - Solaris does use just SCSI SPACE Filemarks, it does not support SCSI - SPACE End-of-data. When MTEOM is called, Solaris does use SCSI SPACE - Filemarks with count = 1048576 for fast mode, and combination of SCSI - SPACE Filemarks with count = 1 with SCSI SPACE Blocks with count = 1 for - slow mode, so EOD mark on the tape on some older tape drives is not - skipped. File number is always tracked for MTEOM. - - Linux does support both SCSI SPACE Filemarks and End-of-data: When MTEOM - is called in MT\_ST\_FAST\_MTEOM mode, SCSI SPACE End-of-data is used. - In the other case, SCSI SPACE Filemarks with count = - 8388607 is used. - There is no real slow mode like in Solaris - I just expect, that for - older tape drives Filemarks may be slower than End-of-data, but not so - much as in Solaris slow mode. File number is tracked for MTEOM just - without MT\_ST\_FAST\_MTEOM - when MT\_ST\_FAST\_MTEOM is used, it is not. - - FreeBSD does support both SCSI SPACE Filemarks and End-of-data, but when - MTEOD (MTEOM) is called, SCSI SPACE End-of-data is always used. FreeBSD - never use SCSI SPACE Filemarks for MTEOD. File number is never tracked - for MTEOD. - -\item[Bareos level] - When {\bf Hardware End of Medium = Yes} is used, MTEOM is called, but it - does not mean, that hardware End-of-data must be used. When Hardware End - of Medium = No, if Fast Forward Space File = Yes, MTFSF with count = - 32767 is used, else Block Read with count = 1 with Forward Space File - with count = 1 is used, which is really very slow. - -\item [Hardware End of Medium = Yes|No] - The name of this option is misleading and is the source of confusion, - because it is not the hardware EOM, what is really switched here. - - If I use Yes, OS must not use SCSI SPACE End-of-data, because Bareos - expects, that there is tracked file number, which is not supported by - SCSI specification. Instead, the OS have to use SCSI SPACE Filemarks. - - If I use No, an action depends on Fast Forward Space File. - - When I set {\bf Hardware End of Medium = no} - and {\bf Fast Forward Space File = no} - file positioning was very slow - on my LTO-3 (about ten to 100 minutes), but - - with {\bf Hardware End of Medium = no} and -{\bf Fast Forward Space File = yes}, the time is ten to -100 times faster (about one to two minutes). - -\end{description} - -\subsection{Tape Performance Problems} -\index[general]{Tape Performance} -If you have LTO-3 or LTO-4 drives, you should be able to -fairly good transfer rates; from 60 to 150 MB/second, providing -you have fast disks; GigaBit Ethernet connections (probably 2); you are -running multiple simultaneous jobs; you have Bareos data spooling -enabled; your tape block size is set to 131072 or 262144; and -you have set {\bf Maximum File Size = 5G}. - -If you are not getting good performance, consider some of the following -suggestions from the Allen Balck on the Bareos Users email list: - -\begin{enumerate} -\item You are using an old HBA (i.e. SCSI-1, which only does 5 MB/s) - -\item There are other, slower, devices on the SCSI bus. The HBA will - negotiate the speed of every device down to the speed of the - slowest. - -\item There is a termination problem on the bus (either too much or - too little termination). The HBA will drop the bus speed in an - attempt to increase the reliability of the bus. - -\item Loose or damaged cabling - this will probably make the HBA "think" - you have a termination problem and it will react as in 3 above. -\end{enumerate} - -See if /var/adm/messages (or /var/log/messages) tells you what the sync -rate of the SCSI devices/bus are. Also, the next time you reboot, the -BIOS may be able to tell you what the rate of each device is. - - -\subsection{Autochanger Errors} -\index[general]{Errors!Autochanger} -\index[general]{Autochanger Errors} - -If you are getting errors such as: - -\footnotesize -\begin{verbatim} -3992 Bad autochanger "load slot 1, drive 1": ERR=Child exited with code 1. -\end{verbatim} -\normalsize - -and you are running your Storage daemon as non-root, then most likely -you are having permissions problems with the control channel. Running -as root, set permissions on /dev/sgX so that the userid and group of -your Storage daemon can access the device. You need to ensure that you -all access to the proper control device, and if you don't have any -SCSI disk drives (including SATA drives), you might want to change -the permissions on /dev/sg*. - -\subsection{Syslog Errors} -\index[general]{Errors!Syslog} -\index[general]{Syslog Errors} - -If you are getting errors such as: - -\footnotesize -\begin{verbatim} -: kernel: st0: MTSETDRVBUFFER only allowed for root -\end{verbatim} -\normalsize - -you are most likely running your Storage daemon as non-root, and -Bareos is attempting to set the correct OS buffering to correspond -to your Device resource. Most OSes allow only root to issue this -ioctl command. In general, the message can be ignored providing -you are sure that your OS parameters are properly configured as -described earlier in this manual. If you are running your Storage daemon -as root, you should not be getting these system log messages, and if -you are, something is probably wrong. -}` - -Autochanger -=========== - -Testing Autochanger and Adapting mtx-changer script ---------------------------------------------------- - -.. _sec:MtxChangerManualUsage: - -.. index:: - triple: General; Autochanger; Testing - -.. index:: - triple: General; Autochanger; mtx-changer - -.. index:: - triple: General; Command; mtx-changer - -.. index:: - triple: General; Problem; Autochanger - -.. index:: - triple: General; Problem; mtx-changer - -In case, Bareos does not work well with the Autochanger, it is -preferable to “hand-test” that the changer works. To do so, we suggest -you do the following commands: - -Make sure Bareos is not running. - -:command:`/usr/lib/bareos/scripts/mtx-changer /dev/sg0 list 0 /dev/nst0 0` -.. index:: SD; mtx-changer list - -This command should print: - - - -:: - - 1: - 2: - 3: - ... - - - -or one number per line for each slot that is occupied in your changer, -and the number should be terminated by a colon (**:**). If your changer -has barcodes, the barcode will follow the colon. If an error message is -printed, you must resolve the problem (e.g. try a different SCSI control -device name if **/dev/sg0** is incorrect). For example, on FreeBSD -systems, the autochanger SCSI control device is generally -**/dev/pass2**. - -:command:`/usr/lib/bareos/scripts/mtx-changer /dev/sg0 listall 0 /dev/nst0 0` -.. index:: SD; mtx-changer listall - -This command should print: - - - -:: - - Drive content: D:Drive num:F:Slot loaded:Volume Name - D:0:F:2:vol2 or D:Drive num:E - D:1:F:42:vol42 - D:3:E - - Slot content: - S:1:F:vol1 S:Slot num:F:Volume Name - S:2:E or S:Slot num:E - S:3:F:vol4 - - Import/Export tray slots: - I:10:F:vol10 I:Slot num:F:Volume Name - I:11:E or I:Slot num:E - I:12:F:vol40 - - - -:command:`/usr/lib/bareos/scripts/mtx-changer /dev/sg0 transfer 1 2` -.. index:: SD; mtx-changer listall - -This command should transfer a volume from source (1) to destination (2) - -:command:`/usr/lib/bareos/scripts/mtx-changer /dev/sg0 slots` -.. index:: SD; mtx-changer slots - -This command should return the number of slots in your autochanger. - -:command:`/usr/lib/bareos/scripts/mtx-changer /dev/sg0 unload 1 /dev/nst0 0` -.. index:: SD; mtx-changer unload - -If a tape is loaded from slot 1, this should cause it to be unloaded. - -:command:`/usr/lib/bareos/scripts/mtx-changer /dev/sg0 load 3 /dev/nst0 0` -.. index:: SD; mtx-changer load - -Assuming you have a tape in slot 3, it will be loaded into drive (0). - -:command:`/usr/lib/bareos/scripts/mtx-changer /dev/sg0 loaded 0 /dev/nst0 0` -.. index:: SD; mtx-changer loaded - -It should print “3” Note, we have used an “illegal” slot number 0. In -this case, it is simply ignored because the slot number is not used. -However, it must be specified because the drive parameter at the end of -the command is needed to select the correct drive. - -:command:`/usr/lib/bareos/scripts/mtx-changer /dev/sg0 unload 3 /dev/nst0 0` -.. index:: SD; mtx-changer unload - -will unload the tape into slot 3. - -Once all the above commands work correctly, assuming that you have the -right **Changer Command** in your configuration, Bareos should be able -to operate the changer. The only remaining area of problems will be if -your autoloader needs some time to get the tape loaded after issuing the -command. After the **mtx-changer** script returns, Bareos will -immediately rewind and read the tape. If Bareos gets rewind I/O errors -after a tape change, you will probably need to configure the -**load_sleep** paramenter in the config file -*/etc/bareos/mtx-changer.conf*. You can test whether -or not you need a **sleep** by putting the following commands into a -file and running it as a script: - - - -:: - - #!/bin/sh - /usr/lib/bareos/scripts/mtx-changer /dev/sg0 unload 1 /dev/nst0 0 - /usr/lib/bareos/scripts/mtx-changer /dev/sg0 load 3 /dev/nst0 0 - mt -f /dev/st0 rewind - mt -f /dev/st0 weof - - - -If the above script runs, you probably have no timing problems. If it -does not run, start by putting a **sleep 30** or possibly a **sleep 60** -in the script just after the mtx-changer load command. If that works, -then you should configure the **load_sleep** -paramenter in the config file -*/etc/bareos/mtx-changer.conf* to the specified value -so that it will be effective when Bareos runs. - -A second problem that comes up with a small number of autochangers is -that they need to have the cartridge ejected before it can be removed. -If this is the case, the **load 3** will never succeed regardless of how -long you wait. If this seems to be your problem, you can insert an eject -just after the unload so that the script looks like: - - - -:: - - #!/bin/sh - /usr/lib/bareos/scripts/mtx-changer /dev/sg0 unload 1 /dev/nst0 0 - mt -f /dev/st0 offline - /usr/lib/bareos/scripts/mtx-changer /dev/sg0 load 3 /dev/nst0 0 - mt -f /dev/st0 rewind - mt -f /dev/st0 weof - - - -If this solves your problems, set the parameter -**offline** in the config file -*/etc/bareos/mtx-changer.conf* to “1”. - -Restore -======= - -Restore a pruned job using a pattern ------------------------------------- - - -.. index:: - triple: General; Restore; pruned job - -.. index:: - triple: General; Problem!Restore; pruned job -.. index:: General; Regex - -It is possible to configure Bareos in a way, that job information are -still stored in the Bareos catalog, while the individual file -information are already pruned. - -If all File records are pruned from the catalog for a Job, normally -Bareos can restore only all files saved. That is there is no way using -the catalog to select individual files. With this new feature, Bareos -will ask if you want to specify a Regex expression for extracting only a -part of the full backup. - -:: - - Building directory tree for JobId(s) 1,3 ... - There were no files inserted into the tree, so file selection - is not possible.Most likely your retention policy pruned the files - - Do you want to restore all the files? (yes|no): no - - Regexp matching files to restore? (empty to abort): /etc/.* - Bootstrap records written to /tmp/regress/working/zog4-dir.restore.1.bsr - -See also :ref:`FileRegex bsr option FileRegex` for more -information. - -Problems Restoring Files ------------------------- - - -.. index:: - triple: General; Restore!Files; Problem - -.. index:: - triple: General; Problem; Restoring Files - -.. index:: - triple: General; Problem!Tape; fixed mode - -.. index:: - triple: General; Problem!Tape; variable mode - -The most frequent problems users have restoring files are error messages -such as: - - - -:: - - 04-Jan 00:33 z217-sd: RestoreFiles.2005-01-04_00.31.04 Error: - block.c:868 Volume data error at 20:0! Short block of 512 bytes on - device /dev/tape discarded. - - - -or - - - -:: - - 04-Jan 00:33 z217-sd: RestoreFiles.2005-01-04_00.31.04 Error: - block.c:264 Volume data error at 20:0! Wanted ID: "BB02", got ".". - Buffer discarded. - - - -Both these kinds of messages indicate that you were probably running -your tape drive in fixed block mode rather than variable block mode. -Fixed block mode will work with any program that reads tapes -sequentially such as tar, but Bareos repositions the tape on a block -basis when restoring files because this will speed up the restore by -orders of magnitude when only a few files are being restored. There are -several ways that you can attempt to recover from this unfortunate -situation. - -Try the following things, each separately, and reset your Device -resource to what it is now after each individual test: - -#. Set “Block Positioning = no” in your Device resource and try the - restore. This is a new directive and untested. - -#. Set “Minimum Block Size = 512” and “Maximum Block Size = 512” and try - the restore. If you are able to determine the block size your drive - was previously using, you should try that size if 512 does not work. - This is a really horrible solution, and it is not at all recommended - to continue backing up your data without correcting this condition. - Please see the :ref:`TapeTestingChapter` section for - more on this. - -#. Try editing the restore.bsr file at the Run xxx yes/mod/no prompt - before starting the restore job and remove all the VolBlock - statements. These are what causes Bareos to reposition the tape, and - where problems occur if you have a fixed block size set for your - drive. The VolFile commands also cause repositioning, but this will - work regardless of the block size. - -#. Use bextract to extract the files you want – it reads the Volume - sequentially if you use the include list feature, or if you use a - .bsr file, but remove all the VolBlock statements after the .bsr file - is created (at the Run yes/mod/no) prompt but before you start the - restore. - -Restoring Files Can Be Slow ---------------------------- - - -.. index:: - triple: General; Restore; slow - -.. index:: - triple: General; Problem!Restore; slow - -Restoring files is generally **much** slower than backing them up for -several reasons. The first is that during a backup the tape is normally -already positioned and Bareos only needs to write. On the other hand, -because restoring files is done so rarely, Bareos keeps only the start -file and block on the tape for the whole job rather than on a file by -file basis which would use quite a lot of space in the catalog. - -Bareos will forward space to the correct file mark on the tape for the -Job, then forward space to the correct block, and finally sequentially -read each record until it gets to the correct one(s) for the file or -files you want to restore. Once the desired files are restored, Bareos -will stop reading the tape. - -Finally, instead of just reading a file for backup, during the restore, -Bareos must create the file, and the operating system must allocate disk -space for the file as Bareos is restoring it. - -For all the above reasons the restore process is generally much slower -than backing up (sometimes it takes three times as long). - -Restoring When Things Go Wrong ------------------------------- - - -.. index:: - triple: General; Catalog; Restore - -.. index:: - triple: General; Restore; Catalog - -.. index:: - triple: General; Disaster!Recovery; Catalog - -.. index:: - triple: General; Problem; Repair Catalog - -This and the following sections will try to present a few of the kinds -of problems that can come up making restoring more difficult. We will -try to provide a few ideas how to get out of these problem situations. -In addition to what is presented here, there is more specific -information on restoring a -:ref:`Client sec:BareMetalRestoreClient` and your -:ref:`Server sec:RestoreServer` in the -:ref:`RescueChapter` chapter of this manual. - -Problem - My database is broken. - -Solution - For SQLite, use the vacuum command to try to fix the database. For - either MySQL or PostgreSQL, see the vendor’s documentation. They - have specific tools that check and repair databases, see the - :ref:`CatMaintenanceChapter` sections of this manual - for links to vendor information. - - Assuming the above does not resolve the problem, you will need to - restore or rebuild your catalog. Note, if it is a matter of some - inconsistencies in the Bareos tables rather than a broken database, - then running :ref:`bareos-dbcheck bareos-dbcheck` - might help, but you will need to ensure that your database indexes - are properly setup. - -Problem - How do I restore my catalog? - -Solution with a Catalog backup - If you have backed up your database nightly (as you should) and you - have made a bootstrap file, you can immediately load back your - database (or the ASCII SQL output). Make a copy of your current - database, then re-initialize it, by running the following scripts: - - :: - - ./drop_bareos_tables - ./make_bareos_tables - - After re-initializing the database, you should be able to run - Bareos. If you now try to use the restore command, it will not work - because the database will be empty. However, you can manually run a - restore job and specify your bootstrap file. You do so by entering - the **run** command in the console and selecting the restore job. If - you are using the default bareos-dir.conf, this Job will be named - **RestoreFiles**. Most likely it will prompt you with something such - as: - - - - :: - - Run Restore job - JobName: RestoreFiles - Bootstrap: /home/user/bareos/working/restore.bsr - Where: /tmp/bareos-restores - Replace: always - FileSet: Full Set - Client: rufus-fd - Storage: File - When: 2005-07-10 17:33:40 - Catalog: MyCatalog - Priority: 10 - OK to run? (yes/mod/no): - - - - A number of the items will be different in your case. What you want - to do is: to use the mod option to change the Bootstrap to point to - your saved bootstrap file; and to make sure all the other items such - as Client, Storage, Catalog, and Where are correct. The FileSet is - not used when you specify a bootstrap file. Once you have set all - the correct values, run the Job and it will restore the backup of - your database, which is most likely an ASCII dump. - - You will then need to follow the instructions for your database type - to recreate the database from the ASCII backup file. See the - :ref:`Catalog Maintenance CatMaintenanceChapter` - chapter of this manual for examples of the command needed to restore - a database from an ASCII dump (they are shown in the Compacting Your - XXX Database sections). - - Also, please note that after you restore your database from an ASCII - backup, you do NOT want to do a **make\_bareos\_tables** command, or - you will probably erase your newly restored database tables. - -Solution with a Job listing - If you did save your database but did not make a bootstrap file, - then recovering the database is more difficult. You will probably - need to use :command:`bextract` to extract the backup - copy. First you should locate the listing of the job report from the - last catalog backup. It has important information that will allow - you to quickly find your database file. For example, in the job - report for the CatalogBackup shown below, the critical items are the - Volume name(s), the Volume Session Id and the Volume Session Time. - If you know those, you can easily restore your Catalog. - - - - :: - - 22-Apr 10:22 HeadMan: Start Backup JobId 7510, - Job=CatalogBackup.2005-04-22_01.10.0 - 22-Apr 10:23 HeadMan: Bareos 1.37.14 (21Apr05): 22-Apr-2005 10:23:06 - JobId: 7510 - Job: CatalogBackup.2005-04-22_01.10.00 - Backup Level: Full - Client: Polymatou - FileSet: "CatalogFile" 2003-04-10 01:24:01 - Pool: "Default" - Storage: "DLTDrive" - Start time: 22-Apr-2005 10:21:00 - End time: 22-Apr-2005 10:23:06 - FD Files Written: 1 - SD Files Written: 1 - FD Bytes Written: 210,739,395 - SD Bytes Written: 210,739,521 - Rate: 1672.5 KB/s - Software Compression: None - Volume name(s): DLT-22Apr05 - Volume Session Id: 11 - Volume Session Time: 1114075126 - Last Volume Bytes: 1,428,240,465 - Non-fatal FD errors: 0 - SD Errors: 0 - FD termination status: OK - SD termination status: OK - Termination: Backup OK - - - - From the above information, you can manually create a bootstrap - file, and then follow the instructions given above for restoring - your database. A reconstructed bootstrap file for the above backup - Job would look like the following: - - - - :: - - Volume="DLT-22Apr05" - VolSessionId=11 - VolSessionTime=1114075126 - FileIndex=1-1 - - - - Where we have inserted the Volume name, Volume Session Id, and - Volume Session Time that correspond to the values in the job report. - We’ve also used a FileIndex of one, which will always be the case - providing that there was only one file backed up in the job. - - The disadvantage of this bootstrap file compared to what is created - when you ask for one to be written, is that there is no File and - Block specified, so the restore code must search all data in the - Volume to find the requested file. A fully specified bootstrap file - would have the File and Blocks specified as follows: - - - - :: - - Volume="DLT-22Apr05" - VolSessionId=11 - VolSessionTime=1114075126 - VolFile=118-118 - VolBlock=0-4053 - FileIndex=1-1 - - - - Once you have restored the ASCII dump of the database, you will then - to follow the instructions for your database type to recreate the - database from the ASCII backup file. See the - :ref:`Catalog Maintenance CatMaintenanceChapter` - chapter of this manual for examples of the command needed to restore - a database from an ASCII dump (they are shown in the Compacting Your - XXX Database sections). - - Also, please note that after you restore your database from an ASCII - backup, you do NOT want to do a **make\_bareos\_tables** command, or - you will probably erase your newly restored database tables. - -Solution without a Job Listing - If you do not have a job listing, then it is a bit more difficult. - Either you use the :ref:`bscan bscan` program to scan - the contents of your tape into a database, which can be very time - consuming depending on the size of the tape, or you can use the - :ref:`bls bls` program to list everything on the - tape, and reconstruct a bootstrap file from the bls listing for the - file or files you want following the instructions given above. - - There is a specific example of how to use **bls** below. - -Problem - Trying to restore the last known good full backup by specifying item - 3 on the restore menu then the JobId to restore, but Bareos then - reports: - - - - :: - - 1 Job 0 Files - - and restores nothing. - -Solution - Most likely the File records were pruned from the database either - due to the File Retention period expiring or by explicitly purging - the Job. By using the “llist jobid=nn” command, you can obtain all - the important information about the job: - - - - :: - - llist jobid=120 - JobId: 120 - Job: save.2005-12-05_18.27.33 - Job.Name: save - PurgedFiles: 0 - Type: B - Level: F - Job.ClientId: 1 - Client.Name: Rufus - JobStatus: T - SchedTime: 2005-12-05 18:27:32 - StartTime: 2005-12-05 18:27:35 - EndTime: 2005-12-05 18:27:37 - JobTDate: 1133803657 - VolSessionId: 1 - VolSessionTime: 1133803624 - JobFiles: 236 - JobErrors: 0 - JobMissingFiles: 0 - Job.PoolId: 4 - Pool.Name: Full - Job.FileSetId: 1 - FileSet.FileSet: BackupSet - - - - Then you can find the Volume(s) used by doing: - - - - :: - - sql - select VolumeName from JobMedia,Media where JobId=1 and JobMedia.MediaId=Media.MediaId; - - - - Finally, you can create a bootstrap file as described in the - previous problem above using this information. - - Bareos will ask you if you would like to restore all the files in - the job, and it will collect the above information and write the - bootstrap file for you. - -Problem - You don’t have a bootstrap file, and you don’t have the Job report - for the backup of your database, but you did backup the database, - and you know the Volume to which it was backed up. - -Solution - Either :command:`bscan` the tape (see below for - bscanning), or better use :command:`bls` to find where - it is on the tape, then use :command:`bextract` to - restore the database. For example, - - - - :: - - ./bls -j -V DLT-22Apr05 /dev/nst0 - - Might produce the following output: - - - :: - - bls: butil.c:258 Using device: "/dev/nst0" for reading. - 21-Jul 18:34 bls: Ready to read from volume "DLT-22Apr05" on device "DLTDrive" - (/dev/nst0). - Volume Record: File:blk=0:0 SessId=11 SessTime=1114075126 JobId=0 DataLen=164 - ... - Begin Job Session Record: File:blk=118:0 SessId=11 SessTime=1114075126 - JobId=7510 - Job=CatalogBackup.2005-04-22_01.10.0 Date=22-Apr-2005 10:21:00 Level=F Type=B - End Job Session Record: File:blk=118:4053 SessId=11 SessTime=1114075126 - JobId=7510 - Date=22-Apr-2005 10:23:06 Level=F Type=B Files=1 Bytes=210,739,395 Errors=0 - Status=T - ... - 21-Jul 18:34 bls: End of Volume at file 201 on device "DLTDrive" (/dev/nst0), - Volume "DLT-22Apr05" - 21-Jul 18:34 bls: End of all volumes. - - Of course, there will be many more records - printed, but we have indicated the essential lines of output. From - the information on the Begin Job and End Job Session Records, you - can reconstruct a bootstrap file such as the one shown above. - -Problem - How can I find where a file is stored? - -Solution - Normally, it is not necessary, you just use the **restore** command - to restore the most recently saved version (menu option 5), or a - version saved before a given date (menu option 8). If you know the - JobId of the job in which it was saved, you can use menu option 3 to - enter that JobId. - - If you would like to know the JobId where a file was saved, select - restore menu option 2. - - You can also use the **query** command to find information such as: - - - :: - - *query - Available queries: - 1: List up to 20 places where a File is saved regardless of the - directory - 2: List where the most recent copies of a file are saved - 3: List last 20 Full Backups for a Client - 4: List all backups for a Client after a specified time - 5: List all backups for a Client - 6: List Volume Attributes for a selected Volume - 7: List Volumes used by selected JobId - 8: List Volumes to Restore All Files - 9: List Pool Attributes for a selected Pool - 10: List total files/bytes by Job - 11: List total files/bytes by Volume - 12: List Files for a selected JobId - 13: List Jobs stored on a selected MediaId - 14: List Jobs stored for a given Volume name - 15: List Volumes Bareos thinks are in changer - 16: List Volumes likely to need replacement from age or errors - Choose a query (1-16): - - - -Problem - I didn’t backup my database. What do I do now? - -Solution - This is probably the worst of all cases, and you will probably have - to re-create your database from scratch and then bscan in all your - volumes, which is a very long, painful, and inexact process. - - There are basically three steps to take: - - #. Ensure that your SQL server is running (MySQL or PostgreSQL) and - that the Bareos database (normally bareos) exists. See the - :ref:`sec:CreateDatabase` chapter of the manual. - - #. Ensure that the Bareos databases are created. This is also - described at the above link. - - #. Start and stop the Bareos Director using the propriate - bareos-dir.conf file so that it can create the Client and Storage - records which are not stored on the Volumes. Without these - records, scanning is unable to connect the Job records to the - proper client. - - When the above is complete, you can begin bscanning your Volumes. - Please see the :ref:`bscan` chapter for more - details. - -.. |image| image:: \idir Conf-Diagram - :width: 80.0% diff --git a/docs/manuals/en/new_main_reference/source/tutorial.rst b/docs/manuals/en/new_main_reference/source/tutorial.rst index 383d80fd2c9..bc3dd5bf819 100644 --- a/docs/manuals/en/new_main_reference/source/tutorial.rst +++ b/docs/manuals/en/new_main_reference/source/tutorial.rst @@ -1,25 +1,31 @@ +.. _TutorialChapter: + Tutorial ======== -.. index:: General; Tutorial +:raw-latex:`\index[general]{Tutorial}` This chapter will guide you through running Bareos. To do so, we assume you have installed Bareos. However, we assume that you have not modified the configuration. The examples in this chapter use the default configuration files and will write the volumes to disk in your -*/var/lib/bareos/storage/* +:raw-latex:`\path`\|/var/lib/bareos/storage/\| directory. The general flow of running Bareos is: -#. Start the Database (if using |postgresql| or - |mysql| ) +#. Start the Database (if using :raw-latex:`\postgresql `or + |mysql|) + +#. + + .. raw:: latex -#. :ref:`InstallChapter` + \nameref{InstallChapter} #. Start the Bareos Daemons #. Start the Console program to interact with the - |bareosDir| + |bareosDir| #. Run a job @@ -34,25 +40,25 @@ Each of these steps is described in more detail below. Starting the Database --------------------- -If you are using |postgresql| or |mysql| as the +If you are using :raw-latex:`\postgresql `or :raw-latex:`\mysql `as the Bareos database, you should start it before you install Bareos. If you -are using |sqlite| you need do nothing. - |sqlite| is automatically started by the - |bareosDir| . +are using :raw-latex:`\sqlite `you need do nothing. +:raw-latex:`\sqlite `is automatically started by the +|bareosDir|. Installing Bareos ----------------- For installing Bareos, follow the instructions from the -:ref:`InstallChapter` chapter. +:raw-latex:`\nameref{InstallChapter}` chapter. + +.. _StartDaemon: Starting the Daemons -------------------- -.. index:: General; Starting the Daemons - -.. index:: - triple: General; Daemon; Start +:raw-latex:`\index[general]{Starting the Daemons}` +:raw-latex:`\index[general]{Daemon!Start}` Assuming you have installed the packages, to start the three daemons, from your installation directory, simply enter: @@ -63,100 +69,100 @@ from your installation directory, simply enter: service bareos-sd start service bareos-fd start +.. _sec-TuturialBconsole: + Using the Director to Query and Start Jobs ------------------------------------------ -To communicate with the |bareosDir| and to query the state of -Bareos or run jobs, the :command:`bconsole` program can be -used as a textual interface. Alternatively, for most purposes, also the -:ref:`\bareosWebui sec:webui` can be used, but for +To communicate with the |bareosDir| and to query the state +of Bareos or run jobs, the :raw-latex:`\command{verbatim}` program can +be used as a textual interface. Alternatively, for most purposes, also +the :raw-latex:`\ilink{\bareosWebui}{sec-webui}` can be used, but for simplicity, here we will describe only the -:command:`bconsole` program. +:raw-latex:`\command{verbatim}` program. -The :command:`bconsole` runs the Bareos Console program, -which connects to the |bareosDir| . Since Bareos is a network +The :raw-latex:`\command{verbatim}` runs the Bareos Console program, +which connects to the |bareosDir|. Since Bareos is a network program, you can run the Console program anywhere on your network. Most frequently, however, one runs it on the same machine as the - |bareosDir| . Normally, the Console program will print +|bareosDir|. Normally, the Console program will print something similar to the following: -.. raw:: latex +:: - \begin{commands}{bconsole} - bconsole - Connecting to Director bareos:9101 - Enter a period to cancel a command. - * - \end{commands} + {verbatim} + bconsole + Connecting to Director bareos:9101 + Enter a period to cancel a command. + * The asterisk is the console command prompt. -Type :command:`help ` to see a list of available commands: +Type :raw-latex:`\bcommand{help}{}` to see a list of available commands: -.. raw:: latex +:: - \begin{bconsole}{help} - *help - Command Description - ======= =========== - add Add media to a pool - autodisplay Autodisplay console messages - automount Automount after label - cancel Cancel a job - create Create DB Pool from resource - delete Delete volume, pool or job - disable Disable a job - enable Enable a job - estimate Performs FileSet estimate, listing gives full listing - exit Terminate Bconsole session - export Export volumes from normal slots to import/export slots - gui Non-interactive gui mode - help Print help on specific command - import Import volumes from import/export slots to normal slots - label Label a tape - list List objects from catalog - llist Full or long list like list command - messages Display pending messages - memory Print current memory usage - mount Mount storage - move Move slots in an autochanger - prune Prune expired records from catalog - purge Purge records from catalog - quit Terminate Bconsole session - query Query catalog - restore Restore files - relabel Relabel a tape - release Release storage - reload Reload conf file - rerun Rerun a job - run Run a job - status Report status - setbandwidth Sets bandwidth - setdebug Sets debug level - setip Sets new client address -- if authorized - show Show resource records - sqlquery Use SQL to query catalog - time Print current time - trace Turn on/off trace to file - unmount Unmount storage - umount Umount - for old-time Unix guys, see unmount - update Update volume, pool or stats - use Use specific catalog - var Does variable expansion - version Print Director version - wait Wait until no jobs are running - \end{bconsole} + {help} + *help + Command Description + ======= =========== + add Add media to a pool + autodisplay Autodisplay console messages + automount Automount after label + cancel Cancel a job + create Create DB Pool from resource + delete Delete volume, pool or job + disable Disable a job + enable Enable a job + estimate Performs FileSet estimate, listing gives full listing + exit Terminate Bconsole session + export Export volumes from normal slots to import/export slots + gui Non-interactive gui mode + help Print help on specific command + import Import volumes from import/export slots to normal slots + label Label a tape + list List objects from catalog + llist Full or long list like list command + messages Display pending messages + memory Print current memory usage + mount Mount storage + move Move slots in an autochanger + prune Prune expired records from catalog + purge Purge records from catalog + quit Terminate Bconsole session + query Query catalog + restore Restore files + relabel Relabel a tape + release Release storage + reload Reload conf file + rerun Rerun a job + run Run a job + status Report status + setbandwidth Sets bandwidth + setdebug Sets debug level + setip Sets new client address -- if authorized + show Show resource records + sqlquery Use SQL to query catalog + time Print current time + trace Turn on/off trace to file + unmount Unmount storage + umount Umount - for old-time Unix guys, see unmount + update Update volume, pool or stats + use Use specific catalog + var Does variable expansion + version Print Director version + wait Wait until no jobs are running Details of the console program’s commands are explained in the -:ref:`sec:bconsole` chapter. +:raw-latex:`\nameref{sec-bconsole}` chapter. + +.. _Running: Running a Job ------------- - -.. index:: - triple: General; Job; Running a -.. index:: General; Running a Job +:raw-latex:`\index[general]{Job!Running a}` +:raw-latex:`\index[general]{Running a Job}` At this point, we assume you have done the following: @@ -168,156 +174,160 @@ At this point, we assume you have done the following: - Started Bareos Director, Storage Daemon and File Daemon -- Invoked the Console program with :command:`bconsole` +- Invoked the Console program with :raw-latex:`\command{verbatim}` Furthermore, we assume for the moment you are using the default configuration files. -At this point, enter the :command:`show filesets` and you +At this point, enter the :raw-latex:`\bcommand{show}{filesets}` and you should get something similar this: -.. raw:: latex +:: - \begin{bconsole}{show filesets} - *show filesets - ... - FileSet { - Name = "SelfTest" - Include { - Options { - Signature = MD5 - } - File = "/usr/sbin" - } - } - - FileSet { - Name = "Catalog" - Include { - Options { - Signature = MD5 - } - File = "/var/lib/bareos/bareos.sql" - File = "/etc/bareos" - } - } - ... - \end{bconsole} - -One of the FileSets is the pre-defined **SelfTest** -FileSet that will backup the */usr/sbin* + {show filesets} + *show filesets + ... + FileSet { + Name = "SelfTest" + Include { + Options { + Signature = MD5 + } + File = "/usr/sbin" + } + } + + FileSet { + Name = "Catalog" + Include { + Options { + Signature = MD5 + } + File = "/var/lib/bareos/bareos.sql" + File = "/etc/bareos" + } + } + ... + +One of the FileSets is the pre-defined :raw-latex:`\fileset{SelfTest}` +FileSet that will backup the :raw-latex:`\path`\|/usr/sbin\| directory. For testing purposes, we have chosen a directory of moderate size (about 30 Megabytes) and complexity without being too big. The FileSet -**Catalog** is used for backing up Bareos’s catalog +:raw-latex:`\fileset{Catalog}` is used for backing up Bareos’s catalog and is not of interest to us for the moment. You can change what is backed up by editing the configuration and changing the -*File =* +:raw-latex:`\path`\|File =\| line in the :raw-latex:`\resourcetype{Dir}{FileSet}` resource. Now is the time to run your first backup job. We are going to backup your Bareos source directory to a File Volume in your -*/var/lib/bareos/storage/* +:raw-latex:`\path`\|/var/lib/bareos/storage/\| directory just to show you how easy it is. Now enter: -.. raw:: latex +:: + + {status dir} + *status dir + bareos-dir Version: 13.2.0 (09 April 2013) x86_64-pc-linux-gnu debian Debian GNU/Linux 6.0 (squeeze) + Daemon started 23-May-13 13:17. Jobs: run=0, running=0 mode=0 + Heap: heap=270,336 smbytes=59,285 max_bytes=59,285 bufs=239 max_bufs=239 + + Scheduled Jobs: + Level Type Pri Scheduled Name Volume + =================================================================================== + Incremental Backup 10 23-May-13 23:05 BackupClient1 testvol + Full Backup 11 23-May-13 23:10 BackupCatalog testvol + ==== - \begin{bconsole}{status dir} - *status dir - bareos-dir Version: 13.2.0 (09 April 2013) x86_64-pc-linux-gnu debian Debian GNU/Linux 6.0 (squeeze) - Daemon started 23-May-13 13:17. Jobs: run=0, running=0 mode=0 - Heap: heap=270,336 smbytes=59,285 max_bytes=59,285 bufs=239 max_bufs=239 - - Scheduled Jobs: - Level Type Pri Scheduled Name Volume - =================================================================================== - Incremental Backup 10 23-May-13 23:05 BackupClient1 testvol - Full Backup 11 23-May-13 23:10 BackupCatalog testvol - ==== - - Running Jobs: - Console connected at 23-May-13 13:34 - No Jobs running. - ==== - \end{bconsole} + Running Jobs: + Console connected at 23-May-13 13:34 + No Jobs running. + ==== where the times and the Director’s name will be different according to your setup. This shows that an Incremental job is scheduled to run for the Job :raw-latex:`\resourcename{Dir}{Job}{BackupClient1}` at 1:05am and that at 1:10, a :raw-latex:`\resourcename{Dir}{Job}{BackupCatalog}` -is scheduled to run. Now enter: +is scheduled to run. -.. raw:: latex +Now enter: - \begin{bconsole}{status client} - *status client - Automatically selected Client: bareos-fd - Connecting to Client bareos-fd at bareos:9102 +:: - bareos-fd Version: 13.2.0 (09 April 2013) x86_64-pc-linux-gnu debian Debian GNU/Linux 6.0 (squeeze) - Daemon started 23-May-13 13:17. Jobs: run=0 running=0. - Heap: heap=135,168 smbytes=26,000 max_bytes=26,147 bufs=65 max_bufs=66 - Sizeof: boffset_t=8 size_t=8 debug=0 trace=0 bwlimit=0kB/s + {status client} + *status client + Automatically selected Client: bareos-fd + Connecting to Client bareos-fd at bareos:9102 - Running Jobs: - Director connected at: 23-May-13 13:58 - No Jobs running. - ==== - \end{bconsole} + bareos-fd Version: 13.2.0 (09 April 2013) x86_64-pc-linux-gnu debian Debian GNU/Linux 6.0 (squeeze) + Daemon started 23-May-13 13:17. Jobs: run=0 running=0. + Heap: heap=135,168 smbytes=26,000 max_bytes=26,147 bufs=65 max_bufs=66 + Sizeof: boffset_t=8 size_t=8 debug=0 trace=0 bwlimit=0kB/s + + Running Jobs: + Director connected at: 23-May-13 13:58 + No Jobs running. + ==== In this case, the client is named :raw-latex:`\resourcename{Dir}{Client}{bareos-fd}` your name might be different, but the line beginning with :raw-latex:`\path`\|bareos-fd -Version\| is printed by your |bareosFd| , so we are now sure +Version\| is printed by your |bareosFd|, so we are now sure it is up and running. -Finally do the same for your |bareosSd| with: +Finally do the same for your |bareosSd| with: -.. raw:: latex +:: - \begin{bconsole}{status storage} - *status storage - Automatically selected Storage: File - Connecting to Storage daemon File at bareos:9103 + {status storage} + *status storage + Automatically selected Storage: File + Connecting to Storage daemon File at bareos:9103 - bareos-sd Version: 13.2.0 (09 April 2013) x86_64-pc-linux-gnu debian Debian GNU/Linux 6.0 (squeeze) - Daemon started 23-May-13 13:17. Jobs: run=0, running=0. - Heap: heap=241,664 smbytes=28,574 max_bytes=88,969 bufs=73 max_bufs=74 - Sizes: boffset_t=8 size_t=8 int32_t=4 int64_t=8 mode=0 bwlimit=0kB/s + bareos-sd Version: 13.2.0 (09 April 2013) x86_64-pc-linux-gnu debian Debian GNU/Linux 6.0 (squeeze) + Daemon started 23-May-13 13:17. Jobs: run=0, running=0. + Heap: heap=241,664 smbytes=28,574 max_bytes=88,969 bufs=73 max_bufs=74 + Sizes: boffset_t=8 size_t=8 int32_t=4 int64_t=8 mode=0 bwlimit=0kB/s - Running Jobs: - No Jobs running. - ==== + Running Jobs: + No Jobs running. + ==== - Device status: + Device status: - Device "FileStorage" (/var/lib/bareos/storage) is not open. - == - ==== + Device "FileStorage" (/var/lib/bareos/storage) is not open. + == + ==== - Used Volume status: - ==== + Used Volume status: + ==== - ==== - \end{bconsole} + ==== -You will notice that the default |bareosSd| device is named +You will notice that the default |bareosSd| device is named :raw-latex:`\resourcename{Dir}{Storage}{File}` and that it will use -device */var/lib/bareos/storage*, which is not +device :raw-latex:`\directory{/var/lib/bareos/storage}`, which is not currently open. Now, let’s actually run a job with: +.. raw:: latex + \footnotesize :: run +.. raw:: latex + \normalsize you should get the following output: +.. raw:: latex + \footnotesize :: @@ -330,13 +340,17 @@ you should get the following output: 3: RestoreFiles Select Job resource (1-3): +.. raw:: latex + \normalsize Here, Bareos has listed the three different Jobs that you can run, and you should choose number **1** and type enter, at which point you will get: +.. raw:: latex + \footnotesize :: @@ -353,14 +367,16 @@ get: Priority: 10 OK to run? (yes/mod/no): +.. raw:: latex + \normalsize At this point, take some time to look carefully at what is printed and understand it. It is asking you if it is OK to run a job named -**BackupClient1** with FileSet -**SelfTest** as an Incremental job on your Client, +:raw-latex:`\job{BackupClient1}` with FileSet +:raw-latex:`\fileset{SelfTest}` as an Incremental job on your Client, and to use Storage :raw-latex:`\resourcename{Dir}{Storage}{File}` and -Pool **Full**, and finally, it wants to run it now (the +Pool :raw-latex:`\pool{Full}`, and finally, it wants to run it now (the current time should be displayed by your console). Here we have the choice to run (**yes**), to modify one or more of the @@ -369,126 +385,129 @@ above parameters (**mod**), or to not run the job (**no**). Please enter (an asterisk). If you wait a few seconds, then enter the command -:command:`messages ` you will get back something like: - -:raw-latex:`\TODO{Replace bconsole output by current version of Bareos.}` +:raw-latex:`\bcommand{messages}{}` you will get back something like: .. raw:: latex - \begin{bconsole}{run} - *messages - 28-Apr-2003 14:30 bareos-sd: Wrote label to prelabeled Volume - "TestVolume001" on device /var/lib/bareos/storage - 28-Apr-2003 14:30 rufus-dir: Bareos 1.30 (28Apr03): 28-Apr-2003 14:30 - JobId: 1 - Job: BackupClient1.2003-04-28_14.22.33 - FileSet: Full Set - Backup Level: Full - Client: bareos-fd - Start time: 28-Apr-2003 14:22 - End time: 28-Apr-2003 14:30 - Files Written: 1,444 - Bytes Written: 38,988,877 - Rate: 81.2 KB/s - Software Compression: None - Volume names(s): TestVolume001 - Volume Session Id: 1 - Volume Session Time: 1051531381 - Last Volume Bytes: 39,072,359 - FD termination status: OK - SD termination status: OK - Termination: Backup OK - 28-Apr-2003 14:30 rufus-dir: Begin pruning Jobs. - 28-Apr-2003 14:30 rufus-dir: No Jobs found to prune. - 28-Apr-2003 14:30 rufus-dir: Begin pruning Files. - 28-Apr-2003 14:30 rufus-dir: No Files found to prune. - 28-Apr-2003 14:30 rufus-dir: End auto prune. - \end{bconsole} + \TODO{Replace bconsole output by current version of Bareos.} + +:: + + {run} + *messages + 28-Apr-2003 14:30 bareos-sd: Wrote label to prelabeled Volume + "TestVolume001" on device /var/lib/bareos/storage + 28-Apr-2003 14:30 rufus-dir: Bareos 1.30 (28Apr03): 28-Apr-2003 14:30 + JobId: 1 + Job: BackupClient1.2003-04-28_14.22.33 + FileSet: Full Set + Backup Level: Full + Client: bareos-fd + Start time: 28-Apr-2003 14:22 + End time: 28-Apr-2003 14:30 + Files Written: 1,444 + Bytes Written: 38,988,877 + Rate: 81.2 KB/s + Software Compression: None + Volume names(s): TestVolume001 + Volume Session Id: 1 + Volume Session Time: 1051531381 + Last Volume Bytes: 39,072,359 + FD termination status: OK + SD termination status: OK + Termination: Backup OK + 28-Apr-2003 14:30 rufus-dir: Begin pruning Jobs. + 28-Apr-2003 14:30 rufus-dir: No Jobs found to prune. + 28-Apr-2003 14:30 rufus-dir: Begin pruning Files. + 28-Apr-2003 14:30 rufus-dir: No Files found to prune. + 28-Apr-2003 14:30 rufus-dir: End auto prune. If you don’t see the output immediately, you can keep entering -:command:`messages ` until the job terminates. +:raw-latex:`\bcommand{messages}{}` until the job terminates. -Instead of typing :command:`messages ` multiple times, you +Instead of typing :raw-latex:`\bcommand{messages}{}` multiple times, you can also ask bconsole to wait, until a specific job is finished: -.. raw:: latex +:: - \begin{bconsole}{wait} - *wait jobid=1 - \end{bconsole} + {wait} + *wait jobid=1 -or just :command:`wait `, which waits for all running jobs +or just :raw-latex:`\bcommand{wait}{}`, which waits for all running jobs to finish. -Another useful command is :command:`autodisplay on`. With +Another useful command is :raw-latex:`\bcommand{autodisplay}{on}`. With autodisplay activated, messages will automatically be displayed as soon as they are ready. -If you do an :command:`ls -l` of your -*/var/lib/bareos/storage* directory, you will see +If you do an :raw-latex:`\command{ls -l}` of your +:raw-latex:`\directory{/var/lib/bareos/storage}` directory, you will see that you have the following item: +.. raw:: latex + \footnotesize :: -rw-r----- 1 bareos bareos 39072153 Apr 28 14:30 Full-001 +.. raw:: latex + \normalsize This is the file Volume that you just wrote and it contains all the data of the job just run. If you run additional jobs, they will be appended to this Volume unless you specify otherwise. If you would like to stop here, you can simply enter -:command:`quit ` in the Console program. +:raw-latex:`\bcommand{quit}{}` in the Console program. If you would like to try restoring the files that you just backed up, -read the following section. .. _restoring: +read the following section. :raw-latex:`\label{restoring}` Restoring Your Files -------------------- - -.. index:: - triple: General; Files; Restoring Your -.. index:: General; Restoring Your Files +:raw-latex:`\index[general]{Files!Restoring Your}` +:raw-latex:`\index[general]{Restoring Your Files}` If you have run the default configuration and run the job as demonstrated above, you can restore the backed up files in the Console program by entering: -.. raw:: latex +:: - \begin{bconsole}{restore} - *restore all - First you select one or more JobIds that contain files - to be restored. You will be presented several methods - of specifying the JobIds. Then you will be allowed to - select which files from those JobIds are to be restored. - - To select the JobIds, you have the following choices: - 1: List last 20 Jobs run - 2: List Jobs where a given File is saved - 3: Enter list of comma separated JobIds to select - 4: Enter SQL list command - 5: Select the most recent backup for a client - 6: Select backup for a client before a specified time - 7: Enter a list of files to restore - 8: Enter a list of files to restore before a specified time - 9: Find the JobIds of the most recent backup for a client - 10: Find the JobIds for a backup for a client before a specified time - 11: Enter a list of directories to restore for found JobIds - 12: Select full restore to a specified Job date - 13: Cancel - Select item: (1-13): - \end{bconsole} + {restore} + *restore all + First you select one or more JobIds that contain files + to be restored. You will be presented several methods + of specifying the JobIds. Then you will be allowed to + select which files from those JobIds are to be restored. + + To select the JobIds, you have the following choices: + 1: List last 20 Jobs run + 2: List Jobs where a given File is saved + 3: Enter list of comma separated JobIds to select + 4: Enter SQL list command + 5: Select the most recent backup for a client + 6: Select backup for a client before a specified time + 7: Enter a list of files to restore + 8: Enter a list of files to restore before a specified time + 9: Find the JobIds of the most recent backup for a client + 10: Find the JobIds for a backup for a client before a specified time + 11: Enter a list of directories to restore for found JobIds + 12: Select full restore to a specified Job date + 13: Cancel + Select item: (1-13): As you can see, there are a number of options, but for the current demonstration, please enter **5** to do a restore of the last backup you did, and you will get the following output: +.. raw:: latex + \footnotesize :: @@ -498,13 +517,17 @@ did, and you will get the following output: 2: Full Set Select FileSet resource (1-2): +.. raw:: latex + \normalsize As you can see, Bareos knows what client you have, and since there was only one, it selected it automatically. Select **2**, because you want to restore files from the file set. +.. raw:: latex + \footnotesize :: @@ -526,7 +549,9 @@ to restore files from the file set. cwd is: / $ +.. raw:: latex + \normalsize where I have truncated the listing on the right side to make it more readable. @@ -536,30 +561,36 @@ current backup, in this case, there is only one, and the Storage daemon was also automatically chosen. Bareos then took all the files that were in Job number 1 and entered them into a **directory tree** (a sort of in memory representation of your filesystem). At this point, you can use -the :command:`cd}{}` and :raw-latex:`\bcommand{ls ` or -:command:`dir ` commands to walk up and down the directory +the :raw-latex:`\bcommand{cd}{}` and :raw-latex:`\bcommand{ls}{}` or +:raw-latex:`\bcommand{dir}{}` commands to walk up and down the directory tree and view what files will be restored. For example, if you enter -:command:`cd /usr/sbin` and then enter -:command:`dir ` you will get a listing of all the files in -the */usr/sbin/* directory. On your system, the +:raw-latex:`\bcommand{cd}{/usr/sbin}` and then enter +:raw-latex:`\bcommand{dir}{}` you will get a listing of all the files in +the :raw-latex:`\directory{/usr/sbin/}` directory. On your system, the path might be somewhat different. For more information on this, please refer to the -:ref:`Restore Command Chapter RestoreChapter` of this +:raw-latex:`\ilink{Restore Command Chapter}{RestoreChapter}` of this manual for more details. To exit this mode, simply enter: +.. raw:: latex + \footnotesize :: done +.. raw:: latex + \normalsize and you will get the following output: +.. raw:: latex + \footnotesize :: @@ -610,18 +641,22 @@ and you will get the following output: Plugin Options: *None* OK to run? (yes/mod/no): +.. raw:: latex + \normalsize If you answer **yes** your files will be restored to -*/tmp/bareos-restores*. If you want to restore +:raw-latex:`\directory{/tmp/bareos-restores}`. If you want to restore the files to their original locations, you must use the **mod** option and explicitly set **Where:** to nothing (or to /). We recommend you go ahead and answer **yes** and after a brief moment, enter -:command:`messages `, at which point you should get a +:raw-latex:`\bcommand{messages}{}`, at which point you should get a listing of all the files that were restored as well as a summary of the job that looks similar to this: +.. raw:: latex + \footnotesize :: @@ -645,46 +680,47 @@ job that looks similar to this: SD termination status: OK Termination: Restore OK +.. raw:: latex + \normalsize After exiting the Console program, you can examine the files in -*/tmp/bareos-restores*, which will contain a +:raw-latex:`\directory{/tmp/bareos-restores}`, which will contain a small directory tree with all the files. Be sure to clean up at the end with: -.. raw:: latex +:: - \begin{commands}{remove restore directory} - rm -rf /tmp/bareos-restore - \end{commands} + {remove restore directory} + rm -rf /tmp/bareos-restore Quitting the Console Program ---------------------------- +:raw-latex:`\index[general]{Program!Quitting the Console}` +:raw-latex:`\index[general]{Quitting the Console Program}` -.. index:: - triple: General; Program; Quitting the Console -.. index:: General; Quitting the Console Program +Simply enter the command :raw-latex:`\bcommand{quit}{}`. -Simply enter the command :command:`quit `. +.. _SecondClient: Adding a Client --------------- -.. _sec:AddAClient: - -.. index:: - triple: General; Client; Adding a Second -.. index:: General; Adding a Client +:raw-latex:`\label{sec-AddAClient}` +:raw-latex:`\index[general]{Client!Adding a Second}` +:raw-latex:`\index[general]{Adding a Client}` If you have gotten the example shown above to work on your system, you -may be ready to add a second Client ( |bareosFd| ). That is +may be ready to add a second Client (|bareosFd|). That is you have a second machine that you would like backed up. Lets assume, following settings about the machine you want to add to your backup environment: Hostname (FQDN) - **client2.example.com** + .. raw:: latex + + \host{client2.example.com} IP Address 192.168.0.2 @@ -693,218 +729,231 @@ OS Linux (otherwise the paths may differ) For this you have to make changes on the server side -( |bareosDir| ) and the client side. +(|bareosDir|) and the client side. Client: install package ~~~~~~~~~~~~~~~~~~~~~~~ -See :ref:`InstallChapter` about how to add the Bareos +See :raw-latex:`\nameref{InstallChapter}` about how to add the Bareos repository. The only part you need installed on the other machine is the -**bareos-filedaemon**. +:raw-latex:`\package{bareos-filedaemon}`. Director: configure client ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Bareos 16.2.4 offers the -:ref:`configure add command sec:bcommandConfigure` to add -resources to the |bareosDir| . +Bareos :raw-latex:`\sinceVersion{Dir}{configure add}{16.2.4}` offers the +:raw-latex:`\ilink{configure add command}{sec-bcommandConfigure}` to add +resources to the |bareosDir|. -Start the :command:`bconsole` and use the -:command:`configure add client` command. Address must be a +Start the :raw-latex:`\command{verbatim}` and use the +:raw-latex:`\bcommand{configure}{add client}` command. Address must be a DNS resolvable name or an IP address. -.. raw:: latex +:: - \begin{bconsole}{add a client} - *configure add client name=client2-fd address=192.168.0.2 password=secret - Created resource config file "/etc/bareos/bareos-dir.d/client/client2-fd.conf": - Client { - Name = client2-fd - Address = 192.168.0.2 - Password = secret - } - \end{bconsole} + {add a client} + *configure add client name=client2-fd address=192.168.0.2 password=secret + Created resource config file "/etc/bareos/bareos-dir.d/client/client2-fd.conf": + Client { + Name = client2-fd + Address = 192.168.0.2 + Password = secret + } This creates two resource configuration files: -- */etc/bareos/bareos-dir.d/client/client2-fd.conf* +- + + .. raw:: latex -- */etc/bareos/bareos-dir-export/client/client2-fd/bareos-fd.d/director/bareos-dir.conf* + \file{/etc/bareos/bareos-dir.d/client/client2-fd.conf} + +- :raw-latex:`\file{/etc/bareos/bareos-dir-export/client/client2-fd/bareos-fd.d/director/bareos-dir.conf}` (assuming your director resource is named - **bareos-dir**) + :raw-latex:`\name{bareos-dir}`) The -*/etc/bareos/bareos-dir-export/client/client2-fd/bareos-fd.d/director/bareos-dir.conf* -is the required resource needed on the |bareosFd| . You can +:raw-latex:`\file{/etc/bareos/bareos-dir-export/client/client2-fd/bareos-fd.d/director/bareos-dir.conf}` +is the required resource needed on the |bareosFd|. You can copy it to the destination: -.. raw:: latex +:: - \begin{commands}{Copy the bareos-fd director resource to the new client} - scp /etc/bareos/bareos-dir-export/client/client2-fd/bareos-fd.d/director/bareos-dir.conf root@client2.example.com:/etc/bareos/bareos-fd.d/director/ - \end{commands} + {Copy the bareos-fd director resource to the new client} + scp /etc/bareos/bareos-dir-export/client/client2-fd/bareos-fd.d/director/bareos-dir.conf root@client2.example.com:/etc/bareos/bareos-fd.d/director/ Manual configuration ^^^^^^^^^^^^^^^^^^^^ Alternatively you can configure your resources manually. On the - |bareosDir| create the file +|bareosDir| create the file -.. raw:: latex +:: - \begin{bareosConfigResource}{bareos-dir}{client}{client2-fd} - Client { - Name = client2-fd - Address = 192.168.0.2 - Password = secret - } - \end{bareosConfigResource} + {bareos-dir}{client}{client2-fd} + Client { + Name = client2-fd + Address = 192.168.0.2 + Password = secret + } -Reload or restart your |bareosDir| : +Reload or restart your |bareosDir|: -.. raw:: latex +:: - \begin{bconsole}{reload the Director configuration} - *reload - reloaded - \end{bconsole} + {reload the Director configuration} + *reload + reloaded -The corresponding |bareosFd| director resource can be created -directly on the client, see below. +The corresponding |bareosFd| director resource can be +created directly on the client, see below. Client: configure ~~~~~~~~~~~~~~~~~ -The package **bareos-filedaemon** -16.2.4 brings +The package :raw-latex:`\package{bareos-filedaemon}` +:raw-latex:`\sinceVersion{Fd}{Client resource files}{16.2.4}` brings several configuration files: -- */etc/bareos/bareos-fd.d/client/myself.conf* +- + + .. raw:: latex + + \file{/etc/bareos/bareos-fd.d/client/myself.conf} + +- + + .. raw:: latex -- */etc/bareos/bareos-fd.d/director/bareos-dir.conf* + \file{/etc/bareos/bareos-fd.d/director/bareos-dir.conf} -- */etc/bareos/bareos-fd.d/director/bareos-mon.conf* +- -- */etc/bareos/bareos-fd.d/messages/Standard.conf* + .. raw:: latex + + \file{/etc/bareos/bareos-fd.d/director/bareos-mon.conf} + +- + + .. raw:: latex + + \file{/etc/bareos/bareos-fd.d/messages/Standard.conf} In detail: -*client/myself.conf* +:raw-latex:`\file{client/myself.conf}` defines the name of the client. The default is - *-fd* + :raw-latex:`\path`\|-fd|. Changes are only required, if you want to use another name or en- or disable special - |bareosFd| features. See - :ref:`ClientResourceClient`. + |bareosFd| features. See + :raw-latex:`\nameref{ClientResourceClient}`. -*director/bareos-dir.conf* - gives the |bareosDir| **bareos-dir** full - access to this |bareosFd| . During installation, the - Password is set +:raw-latex:`\file{director/bareos-dir.conf}` + gives the |bareosDir| :raw-latex:`\name{bareos-dir}` + full access to this |bareosFd|. During installation, the + :raw-latex:`\linkResourceDirective{Fd}{Director}{Password}` is set to a random default. Adapt the name and/or the password to your - |bareosDir| . (The name **bareos-dir** is - the default |bareosDir| name since Bareos - 16.2.4.) + |bareosDir|. (The name :raw-latex:`\name{bareos-dir}` is + the default |bareosDir| name since Bareos + :raw-latex:`\sinceVersion{Dir}{bareos-dir is the default \bareosDir name}{16.2.4}`.) -*director/bareos-mon.conf* - gives the |bareosDir| **bareos-mon** - restricted access to this |bareosFd| . During +:raw-latex:`\file{director/bareos-mon.conf}` + gives the |bareosDir| :raw-latex:`\name{bareos-mon}` + restricted access to this |bareosFd|. During installation, the - Password is set + :raw-latex:`\linkResourceDirective{Fd}{Director}{Password}` is set to a random value. This resource is intended to be used by the local - **bareos-tray-monitor**. + :raw-latex:`\package{bareos-tray-monitor}`. -*messages/Standard.conf* +:raw-latex:`\file{messages/Standard.conf}` defines, how messages should be handled. The default sends all - relevant messages to the |bareosDir| . + relevant messages to the |bareosDir|. -If your |bareosDir| is named **bareos-dir**, -the */etc/bareos/bareos-fd.d/director/bareos-dir.conf* +If your |bareosDir| is named :raw-latex:`\name{bareos-dir}`, +the :raw-latex:`\file{/etc/bareos/bareos-fd.d/director/bareos-dir.conf}` may already be overwritten by the file you copied from the - |bareosDir| . If your Director has another name, an addition +|bareosDir|. If your Director has another name, an addition resource file will exists. You can define an arbitrary number of - |bareosDir| ’s in your |bareosFd| configuration. +|bareosDir|’s in your |bareosFd| configuration. However, normally you will only have one :raw-latex:`\resourcetype{Fd}{Director}` with full control of your - |bareosFd| and optional one +|bareosFd| and optional one :raw-latex:`\resourcetype{Fd}{Director}` for monitoring (used by the :raw-latex:`\bareosTrayMonitor`). Anyhow, the resource will look similar to this: -.. raw:: latex +:: - \begin{bareosConfigResource}{bareos-fd}{director}{bareos-dir} - Director { - Name = bareos-dir - Password = "[md5]5ebe2294ecd0e0f08eab7690d2a6ee69" - } - \end{bareosConfigResource} + {bareos-fd}{director}{bareos-dir} + Director { + Name = bareos-dir + Password = "[md5]5ebe2294ecd0e0f08eab7690d2a6ee69" + } -After a restart of the |bareosFd| to reload the configuration -this resource allows the access for a |bareosDir| with name -**bareos-dir}` and password :raw-latex:`\name{secret** -(stored in MD5 format). +After a restart of the |bareosFd| to reload the +configuration this resource allows the access for a +|bareosDir| with name :raw-latex:`\name{bareos-dir}` and +password :raw-latex:`\name{secret}` (stored in MD5 format). -.. raw:: latex +:: + + {restart bareos-fd} + service bareos-fd restart - \begin{commands}{restart bareos-fd} - service bareos-fd restart - \end{commands} +.. _manual-configuration-1: Manual configuration ^^^^^^^^^^^^^^^^^^^^ If you have not created the :raw-latex:`\resourcetype{Fd}{Director}` by -:command:`configure `, you can create it also manually. If -your |bareosDir| is also named -**bareos-dir**, modify or create the file -*/etc/bareos/bareos-fd.d/director/bareos-dir.conf*: +:raw-latex:`\bcommand{configure}{}`, you can create it also manually. If +your |bareosDir| is also named +:raw-latex:`\name{bareos-dir}`, modify or create the file +:raw-latex:`\file{/etc/bareos/bareos-fd.d/director/bareos-dir.conf}`: -.. raw:: latex +:: - \begin{bareosConfigResource}{bareos-fd}{director}{bareos-dir} - Director { - Name = "bareos-dir" # Name of your Bareos Director - Password = "secret" # Password (cleartext or MD5) must be identical - # to the password of your client reosurce in the Direcotr - # (bareos-dir.d/client/client2-fd.conf) - } - \end{bareosConfigResource} + {bareos-fd}{director}{bareos-dir} + Director { + Name = "bareos-dir" # Name of your Bareos Director + Password = "secret" # Password (cleartext or MD5) must be identical + # to the password of your client reosurce in the Direcotr + # (bareos-dir.d/client/client2-fd.conf) + } See the relation between resource names and password of the different -Bareos components in :ref:`sec:resource-relation`. +Bareos components in :raw-latex:`\nameref{sec-resource-relation}`. If your are not using the -:ref:`sec:SubdirectoryConfigurationScheme`, make sure +:raw-latex:`\nameref{sec-SubdirectoryConfigurationScheme}`, make sure that this resource file gets included in your - |bareosFd| configuration. You can verify this by +|bareosFd| configuration. You can verify this by -.. raw:: latex +:: - \begin{commands}{show how bareos-fd would read the current configuration files} - bareos-fd -xc - \end{commands} + {show how bareos-fd would read the current configuration files} + bareos-fd -xc After modifying the file, you have to restart the - |bareosFd| : +|bareosFd|: -.. raw:: latex +:: - \begin{commands}{restart bareos-fd} - service bareos-fd restart - \end{commands} + {restart bareos-fd} + service bareos-fd restart Director: test client, add a job ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following example show how to -- Verify the network connection from |bareosDir| to the - |bareosFd| . +- Verify the network connection from |bareosDir| to the + |bareosFd|. - Add a job resource. -- Dry-run the job (:command:`estimate listing`). +- Dry-run the job (:raw-latex:`\bcommand{estimate}{listing}`). - Run the job. @@ -912,31 +961,30 @@ The following example show how to - Verify the job. -.. raw:: latex +:: - \begin{bconsole}{test the client and add a job resource} - *status client=client2-fd - ... - *configure add job name=client2-job client=client2-fd jobdefs=DefaultJob - Created resource config file "/etc/bareos/bareos-dir.d/job/client2-job.conf": - Job { - Name = client2-job - Client = client2-fd - JobDefs = DefaultJob - } - *estimate listing job=client2-job - ... - *run job=client2-job - ... - *wait jobid=... - ... - *list joblog jobid=... - ... - *list files jobid=... - ... - *list volumes - ... - \end{bconsole} + {test the client and add a job resource} + *status client=client2-fd + ... + *configure add job name=client2-job client=client2-fd jobdefs=DefaultJob + Created resource config file "/etc/bareos/bareos-dir.d/job/client2-job.conf": + Job { + Name = client2-job + Client = client2-fd + JobDefs = DefaultJob + } + *estimate listing job=client2-job + ... + *run job=client2-job + ... + *wait jobid=... + ... + *list joblog jobid=... + ... + *list files jobid=... + ... + *list volumes + ... Patience When Starting Daemons or Mounting Blank Tapes ------------------------------------------------------ @@ -954,21 +1002,21 @@ the drive will be ready to be used. The same considerations apply if you have just mounted a blank tape in a drive. It can take a minute or two before the drive properly recognizes that the tape is blank. If you attempt to -:command:`mount ` the tape with the Console program during +:raw-latex:`\bcommand{mount}{}` the tape with the Console program during this recognition period, it is quite possible that you will hang your SCSI driver. As a consequence, you are again urged to have patience when inserting blank tapes. Let the device settle down before attempting to access it. +.. _Pool: + Pools ----- - -.. index:: - triple: General; Pool; Overview +:raw-latex:`\index[general]{Pool!Overview}` Creating the Pool is automatically done when the - |bareosDir| starts, so if you understand Pools, you can skip +|bareosDir| starts, so if you understand Pools, you can skip to the next section. When you run a backup job, one of the things that Bareos must know is @@ -976,13 +1024,13 @@ what Volumes to use. Instead of specifying a Volume (tape) directly, you specify which Pool of Volumes you want Bareos to consult when it wants a Volume for writing backups. Bareos will select the first available Volume from the Pool that is appropriate for the -Storage you have +:raw-latex:`\linkResourceDirective{Dir}{Job}{Storage}` you have specified for the Job being run. When a volume has filled up with data, -Bareos will change its **VolStatus** from -**Append}` to :raw-latex:`\name{Full**, and then Bareos +Bareos will change its :raw-latex:`\name{VolStatus}` from +:raw-latex:`\name{Append}` to :raw-latex:`\name{Full}`, and then Bareos will use the next volume and so on. If no appendable Volume exists in the Pool, the Director will attempt to recycle an old Volume. For -details, please read the :ref:`RecyclingChapter` +details, please read the :raw-latex:`\nameref{RecyclingChapter}` chapter. If there are still no appendable Volumes available, Bareos will send a @@ -994,106 +1042,79 @@ and a number of attributes of each of those Volumes. When Bareos starts, it ensures that all Pool resource definitions have been recorded in the catalog. You can verify this by entering: -.. raw:: latex +:: - \begin{bconsole}{list pools} - *list pools - +--------+--------------+---------+---------+----------+---------------+ - | PoolId | Name | NumVols | MaxVols | PoolType | LabelFormat | - +--------+--------------+---------+---------+----------+---------------+ - | 1 | Full | 1 | 100 | Backup | Full- | - | 2 | Differential | 0 | 100 | Backup | Differential- | - | 3 | Incremental | 1 | 100 | Backup | Incremental- | - | 4 | Scratch | 0 | 0 | Backup | * | - +--------+--------------+---------+---------+----------+---------------+ - \end{bconsole} + {list pools} + *list pools + +--------+--------------+---------+---------+----------+---------------+ + | PoolId | Name | NumVols | MaxVols | PoolType | LabelFormat | + +--------+--------------+---------+---------+----------+---------------+ + | 1 | Full | 1 | 100 | Backup | Full- | + | 2 | Differential | 0 | 100 | Backup | Differential- | + | 3 | Incremental | 1 | 100 | Backup | Incremental- | + | 4 | Scratch | 0 | 0 | Backup | * | + +--------+--------------+---------+---------+----------+---------------+ Other Useful Console Commands ----------------------------- - -.. index:: - triple: General; Console!Commands; Useful +:raw-latex:`\index[general]{Console!Commands!Useful}` help Show the list all all available commands. help list Show detail information about a specific command, in this case the - command :command:`list `. + command :raw-latex:`\bcommand{list}{}`. status dir - -.. index:: - triple: General; Console!Command; status dir Print a + :raw-latex:`\index[general]{Console!Command!status dir}` Print a status of all running jobs and jobs scheduled in the next 24 hours. status - -.. index:: - triple: General; Console!Command; status The console + :raw-latex:`\index[general]{Console!Command!status}` The console program will prompt you to select a daemon type, then will request the daemon’s status. status jobid=nn - -.. index:: - triple: General; Console!Command; status jobid Print a + :raw-latex:`\index[general]{Console!Command!status jobid}` Print a status of JobId nn if it is running. The Storage daemon is contacted and requested to print a current status of the job as well. list pools - -.. index:: - triple: General; Console!Command; list pools List the + :raw-latex:`\index[general]{Console!Command!list pools}` List the pools defined in the Catalog (normally only Default is used). list volumes - -.. index:: - triple: General; Console!Command; list volumes Lists all + :raw-latex:`\index[general]{Console!Command!list volumes}` Lists all the media defined in the Catalog. list jobs - -.. index:: - triple: General; Console!Command; list jobs Lists all + :raw-latex:`\index[general]{Console!Command!list jobs}` Lists all jobs in the Catalog that have run. list jobid=nn - -.. index:: - triple: General; Console!Command; list jobid Lists JobId + :raw-latex:`\index[general]{Console!Command!list jobid}` Lists JobId nn from the Catalog. list jobtotals - -.. index:: - triple: General; Console!Command; list jobtotals Lists + :raw-latex:`\index[general]{Console!Command!list jobtotals}` Lists totals for all jobs in the Catalog. list files jobid=nn - -.. index:: - triple: General; Console!Command; list files jobid List + :raw-latex:`\index[general]{Console!Command!list files jobid}` List the files that were saved for JobId nn. list jobmedia - -.. index:: - triple: General; Console!Command; list jobmedia List the + :raw-latex:`\index[general]{Console!Command!list jobmedia}` List the media information for each Job run. messages - -.. index:: - triple: General; Console!Command; messages Prints any + :raw-latex:`\index[general]{Console!Command!messages}` Prints any messages that have been directed to the console. quit - -.. index:: - triple: General; Console!Command; quit Exit or quit the + :raw-latex:`\index[general]{Console!Command!quit}` Exit or quit the console program. Most of the commands given above, with the exception of **list**, will @@ -1101,4 +1122,4 @@ prompt you for the necessary arguments if you simply enter the command name. The full list of commands is shown in the chapter -:ref:`sec:ConsoleCommands`. +:raw-latex:`\nameref{sec-ConsoleCommands}`. diff --git a/docs/manuals/en/new_main_reference/source/update.rst b/docs/manuals/en/new_main_reference/source/update.rst index e4f4f456ff0..dff7146f463 100644 --- a/docs/manuals/en/new_main_reference/source/update.rst +++ b/docs/manuals/en/new_main_reference/source/update.rst @@ -2,7 +2,7 @@ In most cases, a Bareos update is simply done by a package update of the distribution. Please remind, that Bareos Director and Bareos Storage Daemon must always have the same version. The version of the File Daemon may differ, see chapter about -:ref:`backward compatibility backward-compability`. +:raw-latex:`\ilink{backward compatibility}{backward-compability}`. Updating the configuration files ================================ @@ -15,22 +15,22 @@ modify the configuration. However, in some rare cases, configuration changes are required. These cases are described in the -:ref:`Release Notes releasenotes`. +:raw-latex:`\ilink{Release Notes}{releasenotes}`. With Bareos version 16.2.4 the default configuration uses the -:ref:`sec:SubdirectoryConfigurationScheme`. This scheme +:raw-latex:`\nameref{sec-SubdirectoryConfigurationScheme}`. This scheme offers various improvements. However, if your are updating from earlier versions, your existing single configuration files -(*/etc/bareos/bareos-*.conf*) stay in place and are +(:raw-latex:`\file{/etc/bareos/bareos-*.conf}`) stay in place and are contentiously used by Bareos. The new default configuration resource files will also be installed -(*/etc/bareos/bareos-*.d/*/*.conf*). However, +(:raw-latex:`\directory{/etc/bareos/bareos-*.d/*/*.conf}`). However, they will only be used, when the legacy configuration file does not exist. -See :ref:`sec:UpdateToConfigurationSubdirectories` for +See :raw-latex:`\nameref{sec-UpdateToConfigurationSubdirectories}` for details and how to migrate to -:ref:`sec:SubdirectoryConfigurationScheme`. +:raw-latex:`\nameref{sec-SubdirectoryConfigurationScheme}`. Updating the database scheme ============================ @@ -38,45 +38,46 @@ Updating the database scheme Sometimes improvements in Bareos make it necessary to update the database scheme. +.. raw:: latex -.. warning:: - If the Bareos catalog database does not have the current schema, the Bareos Director refuses to start. + \warning{If the Bareos catalog database does not have the current schema, the Bareos Director refuses to start.} Detailed information can then be found in the log file -*/var/log/bareos/bareos.log*. +:raw-latex:`\logfileUnix`. -Take a look into the :ref:`Release Notes releasenotes` to +Take a look into the :raw-latex:`\ilink{Release Notes}{releasenotes}` to see which Bareos updates do require a database scheme update. +.. raw:: latex -.. warning:: - Especially the upgrade to Bareos $\geq$ 17.2.0 restructures the \dbtable{File} database table. In larger installations this is very time consuming and temporarily doubles the amount of required database disk space. + \warning{Especially the upgrade to Bareos $\geq$ 17.2.0 restructures the \dbtable{File} database table. In larger installations this is very time consuming and temporarily doubles the amount of required database disk space.} Debian based Linux Distributions -------------------------------- Since Bareos -14.2.0 the +:raw-latex:`\sinceVersion{dir}{dbconfig-common (Debian)}{14.2.0}` the Debian (and Ubuntu) based packages support the -**dbconfig-common** mechanism to create and update +:raw-latex:`\package{dbconfig-common}` mechanism to create and update the Bareos database. If this is properly configured, the database schema will be automatically adapted by the Bareos packages. +.. raw:: latex -.. warning:: - When using the PostgreSQL backend and updating to Bareos $<$ 14.2.3, it is necessary to manually grant database permissions, normally by using + \warning{When using the PostgreSQL backend and updating to Bareos $<$ 14.2.3, it is necessary to manually grant database permissions, normally by using} -.. raw:: latex +:: - \begin{commands}{} - su - postgres -c /usr/lib/bareos/scripts/grant_bareos_privileges - \end{commands} + {} + su - postgres -c /usr/lib/bareos/scripts/grant_bareos_privileges -For details see :ref:`sec:dbconfig`. +For details see :raw-latex:`\nameref{sec-dbconfig}`. -If you disabled the usage of **dbconfig-common**, +If you disabled the usage of :raw-latex:`\package{dbconfig-common}`, follow the instructions for -:ref:`sec:UpdateDatabaseOtherDistributions`. +:raw-latex:`\nameref{sec-UpdateDatabaseOtherDistributions}`. + +.. _sec-UpdateDatabaseOtherDistributions: Other Platforms --------------- @@ -86,31 +87,30 @@ knows only about the credentials to access the Bareos database, but not about the database administrator to modify the database schema. The task of updating the database schema is done by the script -:command:`/usr/lib/bareos/scripts/update_bareos_tables`. +:raw-latex:`\command{/usr/lib/bareos/scripts/update_bareos_tables}`. However, this script requires administration access to the database. Depending on your distribution and your database, this requires different preparations. More details can be found in chapter -:ref:`Catalog Maintenance CatMaintenanceChapter`. +:raw-latex:`\ilink{Catalog Maintenance}{CatMaintenanceChapter}`. +.. raw:: latex -.. warning:: - If you're updating to Bareos $<=$ 13.2.3 and have configured the Bareos database during install using Bareos environment variables (\variable{db_name}, \variable{db_user} or \variable{db_password}, see \nameref{CatMaintenanceChapter}), make sure to have these variables defined in the same way when calling the update and grant scripts. Newer versions of Bareos read these variables from the Director configuration file \configFileDirUnix. However, make sure that the user running the database scripts has read access to this file (or set the environment variables). The \user{postgres} user normally does not have the required permissions. + \warning{If you're updating to Bareos $<=$ 13.2.3 and have configured the Bareos database during install using Bareos environment variables (\variable{db_name}, \variable{db_user} or \variable{db_password}, see \nameref{CatMaintenanceChapter}), make sure to have these variables defined in the same way when calling the update and grant scripts. Newer versions of Bareos read these variables from the Director configuration file \configFileDirUnix. However, make sure that the user running the database scripts has read access to this file (or set the environment variables). The \user{postgres} user normally does not have the required permissions.} PostgreSQL ~~~~~~~~~~ If your are using PostgreSQL and your PostgreSQL administrator is -**postgres** (default), use following commands: +:raw-latex:`\user{postgres}` (default), use following commands: -.. raw:: latex +:: - \begin{commands}{Update PostgreSQL database schema} - su postgres -c /usr/lib/bareos/scripts/update_bareos_tables - su postgres -c /usr/lib/bareos/scripts/grant_bareos_privileges - \end{commands} + {Update PostgreSQL database schema} + su postgres -c /usr/lib/bareos/scripts/update_bareos_tables + su postgres -c /usr/lib/bareos/scripts/grant_bareos_privileges -The :command:`grant_bareos_privileges` command is required, +The :raw-latex:`\command{grant_bareos_privileges}` command is required, if new databases tables are introduced. It does not hurt to run it multiple times. @@ -120,10 +120,10 @@ problems. MySQL/MariaDB ~~~~~~~~~~~~~ -Make sure, that **root** has direct access to the local -MySQL server. Check if the command :command:`mysql` without +Make sure, that :raw-latex:`\user{root}` has direct access to the local +MySQL server. Check if the command :raw-latex:`\command{mysql}` without parameter connects to the database. If not, you may be required to adapt -your local MySQL configuration file *~/.my.cnf*. It +your local MySQL configuration file :raw-latex:`\file{~/.my.cnf}`. It should look similar to this: .. raw:: latex @@ -135,17 +135,16 @@ should look similar to this: password=YourPasswordForAccessingMysqlAsRoot \end{config} -If you are able to connect via the :command:`mysql` to the +If you are able to connect via the :raw-latex:`\command{mysql}` to the database, run the following script from the Unix prompt: -.. raw:: latex +:: - \begin{commands}{Update MySQL database schema} - /usr/lib/bareos/scripts/update_bareos_tables - \end{commands} + {Update MySQL database schema} + /usr/lib/bareos/scripts/update_bareos_tables Currently on MySQL is it not necessary to run -:command:`grant_bareos_privileges`, because access to the +:raw-latex:`\command{grant_bareos_privileges}`, because access to the database is already given using wildcards. After this, restart the Bareos Director and verify it starts without diff --git a/docs/manuals/en/new_main_reference/source/verify.rst b/docs/manuals/en/new_main_reference/source/verify.rst index b892f8d1fd1..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/verify.rst +++ b/docs/manuals/en/new_main_reference/source/verify.rst @@ -1,479 +1 @@ -.. _VerifyChapter: -Verify File Integrity with Bareos -================================= - -.. index:: - triple: General; Security; Using Bareos to Improve Computer -.. _`Security`: - -.. index:: - triple: General; Verify; File Integrity -.. _`Verify`: - - -Since Bareos maintains a catalog of files, their attributes, and either -SHA1 or MD5 signatures, it can be an ideal tool for improving computer -security. This is done by making a snapshot of your system files with a -**Verify** Job and then checking the current state of your system -against the snapshot, on a regular basis (e.g. nightly). - -The first step is to set up a **Verify** Job and to run it with: - -.. raw:: latex - - \footnotesize - -:: - - Level = InitCatalog - -.. raw:: latex - - \normalsize - -The **InitCatalog** level tells **Bareos** simply to get the information -on the specified files and to put it into the catalog. That is your -database is initialized and no comparison is done. The **InitCatalog** -is normally run one time manually. - -Thereafter, you will run a Verify Job on a daily (or whatever) basis -with: - -.. raw:: latex - - \footnotesize - -:: - - Level = Catalog - -.. raw:: latex - - \normalsize - -The **Level = Catalog** level tells Bareos to compare the current state -of the files on the Client to the last **InitCatalog** that is stored in -the catalog and to report any differences. See the example below for the -format of the output. - -You decide what files you want to form your "snapshot" by specifying -them in a **FileSet** resource, and normally, they will be system files -that do not change, or that only certain features change. - -Then you decide what attributes of each file you want compared by -specifying comparison options on the **Include** statements that you use -in the **FileSet** resource of your **Catalog** Jobs. - -The Details ------------ - -.. index:: - triple: General; Verify; Details -.. _`Verify`: - - -In the discussion that follows, we will make reference to the Verify -Configuration Example that is included below in the **A Verify -Configuration Example** section. You might want to look it over now to -get an idea of what it does. - -The main elements consist of adding a schedule, which will normally be -run daily, or perhaps more often. This is provided by the -**VerifyCycle** Schedule, which runs at 5:05 in the morning every day. - -Then you must define a Job, much as is done below. We recommend that the -Job name contain the name of your machine as well as the word **Verify** -or **Check**. In our example, we named it **MatouVerify**. This will -permit you to easily identify your job when running it from the Console. - -You will notice that most records of the Job are quite standard, but -that the **FileSet** resource contains **verify=pins1** option in -addition to the standard **signature=SHA1** option. If you don’t want -SHA1 signature comparison, and we cannot imagine why not, you can drop -the **signature=SHA1** and none will be computed nor stored in the -catalog. Or alternatively, you can use **verify=pins5** and -**signature=MD5**, which will use the MD5 hash algorithm. The MD5 hash -computes faster than SHA1, but is cryptographically less secure. - -The **verify=pins1** is ignored during the **InitCatalog** Job, but is -used during the subsequent **Catalog** Jobs to specify what attributes -of the files should be compared to those found in the catalog. **pins1** -is a reasonable set to begin with, but you may want to look at the -details of these and other options. They can be found in the -:ref:`FileSetResource FileSet Resource` section of this -manual. Briefly, however, the **p** of the **pins1** tells Verify to -compare the permissions bits, the **i** is to compare inodes, the **n** -causes comparison of the number of links, the **s** compares the file -size, and the **1** compares the SHA1 checksums (this requires the -**signature=SHA1** option to have been set also). - -You must also specify the **Client** and the **Catalog** resources for -your Verify job, but you probably already have them created for your -client and do not need to recreate them, they are included in the -example below for completeness. - -As mentioned above, you will need to have a **FileSet** resource for the -Verify job, which will have the additional **verify=pins1** option. You -will want to take some care in defining the list of files to be included -in your **FileSet**. Basically, you will want to include all system (or -other) files that should not change on your system. If you select files, -such as log files or mail files, which are constantly changing, your -automatic Verify job will be constantly finding differences. The -objective in forming the FileSet is to choose all unchanging important -system files. Then if any of those files has changed, you will be -notified, and you can determine if it changed because you loaded a new -package, or because someone has broken into your computer and modified -your files. The example below shows a list of files that I use on my Red -Hat 7.3 system. Since I didn’t spend a lot of time working on it, it -probably is missing a few important files (if you find one, please send -it to me). On the other hand, as long as I don’t load any new packages, -none of these files change during normal operation of the system. - -Running the Verify ------------------- - -.. index:: - triple: General; Verify; Running -.. _`Verify`: - - -The first thing you will want to do is to run an **InitCatalog** level -Verify Job. This will initialize the catalog to contain the file -information that will later be used as a basis for comparisons with the -actual file system, thus allowing you to detect any changes (and -possible intrusions into your system). - -The easiest way to run the **InitCatalog** is manually with the console -program by simply entering **run**. You will be presented with a list of -Jobs that can be run, and you will choose the one that corresponds to -your Verify Job, **MatouVerify** in this example. - -.. raw:: latex - - \footnotesize - -:: - - The defined Job resources are: - 1: MatouVerify - 2: usersrestore - 3: Filetest - 4: usersave - Select Job resource (1-4): 1 - -.. raw:: latex - - \normalsize - -Next, the console program will show you the basic parameters of the Job -and ask you: - -.. raw:: latex - - \footnotesize - -:: - - Run Verify job - JobName: MatouVerify - FileSet: Verify Set - Level: Catalog - Client: MatouVerify - Storage: DLTDrive - Verify Job: - Verify List: /tmp/regress/working/MatouVerify.bsr - OK to run? (yes/mod/no): mod - -.. raw:: latex - - \normalsize - -Here, you want to respond **mod** to modify the parameters because the -Level is by default set to **Catalog** and we want to run an -**InitCatalog** Job. After responding **mod**, the console will ask: - -.. raw:: latex - - \footnotesize - -:: - - Parameters to modify: - 1: Level - 2: Storage - 3: Job - 4: FileSet - 5: Client - 6: When - 7: Priority - 8: Pool - 9: Verify Job - Select parameter to modify (1-5): 1 - -.. raw:: latex - - \normalsize - -you should select number 2 to modify the **Level**, and it will display: - -.. raw:: latex - - \footnotesize - -:: - - Levels: - 1: Initialize Catalog - 2: Verify Catalog - 3: Verify Volume to Catalog - 4: Verify Disk to Catalog - 5: Verify Volume Data (not yet implemented) - Select level (1-4): 1 - -.. raw:: latex - - \normalsize - -Choose item 1, and you will see the final display: - -.. raw:: latex - - \footnotesize - -:: - - Run Verify job - JobName: MatouVerify - FileSet: Verify Set - Level: Initcatalog - Client: MatouVerify - Storage: DLTDrive - Verify Job: - Verify List: /tmp/regress/working/MatouVerify.bsr - OK to run? (yes/mod/no): yes - -.. raw:: latex - - \normalsize - -at which point you respond **yes**, and the Job will begin. - -Thereafter the Job will automatically start according to the schedule -you have defined. If you wish to immediately verify it, you can simply -run a Verify **Catalog** which will be the default. No differences -should be found. - -To use a previous job, you can add ``jobid=xxx`` option in run command -line. It will run the Verify job against the specified job. - -:: - - *run jobid=1 job=MatouVerify - Run Verify job - JobName: MatouVerify - Level: Catalog - Client: 127.0.0.1-fd - FileSet: Full Set - Pool: Default (From Job resource) - Storage: File (From Job resource) - Verify Job: MatouVerify.2010-09-08_15.33.33_03 - Verify List: /tmp/regress/working/MatouVerify.bsr - When: 2010-09-08 15:35:32 - Priority: 10 - OK to run? (yes/mod/no): - -What To Do When Differences Are Found -------------------------------------- - -.. index:: - triple: General; Verify; Differences -.. _`Verify`: - - -If you have setup your messages correctly, you should be notified if -there are any differences and exactly what they are. For example, below -is the email received after doing an update of OpenSSH: - -.. raw:: latex - - \footnotesize - -:: - - HeadMan: Start Verify JobId 83 Job=RufusVerify.2002-06-25.21:41:05 - HeadMan: Verifying against Init JobId 70 run 2002-06-21 18:58:51 - HeadMan: File: /etc/pam.d/sshd - HeadMan: st_ino differ. Cat: 4674b File: 46765 - HeadMan: File: /etc/rc.d/init.d/sshd - HeadMan: st_ino differ. Cat: 56230 File: 56231 - HeadMan: File: /etc/ssh/ssh_config - HeadMan: st_ino differ. Cat: 81317 File: 8131b - HeadMan: st_size differ. Cat: 1202 File: 1297 - HeadMan: SHA1 differs. - HeadMan: File: /etc/ssh/sshd_config - HeadMan: st_ino differ. Cat: 81398 File: 81325 - HeadMan: st_size differ. Cat: 1182 File: 1579 - HeadMan: SHA1 differs. - HeadMan: File: /etc/ssh/ssh_config.rpmnew - HeadMan: st_ino differ. Cat: 812dd File: 812b3 - HeadMan: st_size differ. Cat: 1167 File: 1114 - HeadMan: SHA1 differs. - HeadMan: File: /etc/ssh/sshd_config.rpmnew - HeadMan: st_ino differ. Cat: 81397 File: 812dd - HeadMan: st_size differ. Cat: 2528 File: 2407 - HeadMan: SHA1 differs. - HeadMan: File: /etc/ssh/moduli - HeadMan: st_ino differ. Cat: 812b3 File: 812ab - HeadMan: File: /usr/bin/scp - HeadMan: st_ino differ. Cat: 5e07e File: 5e343 - HeadMan: st_size differ. Cat: 26728 File: 26952 - HeadMan: SHA1 differs. - HeadMan: File: /usr/bin/ssh-keygen - HeadMan: st_ino differ. Cat: 5df1d File: 5e07e - HeadMan: st_size differ. Cat: 80488 File: 84648 - HeadMan: SHA1 differs. - HeadMan: File: /usr/bin/sftp - HeadMan: st_ino differ. Cat: 5e2e8 File: 5df1d - HeadMan: st_size differ. Cat: 46952 File: 46984 - HeadMan: SHA1 differs. - HeadMan: File: /usr/bin/slogin - HeadMan: st_ino differ. Cat: 5e359 File: 5e2e8 - HeadMan: File: /usr/bin/ssh - HeadMan: st_mode differ. Cat: 89ed File: 81ed - HeadMan: st_ino differ. Cat: 5e35a File: 5e359 - HeadMan: st_size differ. Cat: 219932 File: 234440 - HeadMan: SHA1 differs. - HeadMan: File: /usr/bin/ssh-add - HeadMan: st_ino differ. Cat: 5e35b File: 5e35a - HeadMan: st_size differ. Cat: 76328 File: 81448 - HeadMan: SHA1 differs. - HeadMan: File: /usr/bin/ssh-agent - HeadMan: st_ino differ. Cat: 5e35c File: 5e35b - HeadMan: st_size differ. Cat: 43208 File: 47368 - HeadMan: SHA1 differs. - HeadMan: File: /usr/bin/ssh-keyscan - HeadMan: st_ino differ. Cat: 5e35d File: 5e96a - HeadMan: st_size differ. Cat: 139272 File: 151560 - HeadMan: SHA1 differs. - HeadMan: 25-Jun-2002 21:41 - JobId: 83 - Job: RufusVerify.2002-06-25.21:41:05 - FileSet: Verify Set - Verify Level: Catalog - Client: RufusVerify - Start time: 25-Jun-2002 21:41 - End time: 25-Jun-2002 21:41 - Files Examined: 4,258 - Termination: Verify Differences - -.. raw:: latex - - \normalsize - -At this point, it was obvious that these files were modified during -installation of the RPMs. If you want to be super safe, you should run a -**Verify Level=Catalog** immediately before installing new software to -verify that there are no differences, then run a **Verify -Level=InitCatalog** immediately after the installation. - -To keep the above email from being sent every night when the Verify Job -runs, we simply re-run the Verify Job setting the level to -**InitCatalog** (as we did above in the very beginning). This will -re-establish the current state of the system as your new basis for -future comparisons. Take care that you don’t do an **InitCatalog** after -someone has placed a Trojan horse on your system! - -If you have included in your **FileSet** a file that is changed by the -normal operation of your system, you will get false matches, and you -will need to modify the **FileSet** to exclude that file (or not to -Include it), and then re-run the **InitCatalog**. - -The FileSet that is shown below is what I use on my Red Hat 7.3 system. -With a bit more thought, you can probably add quite a number of -additional files that should be monitored. - -A Verify Configuration Example ------------------------------- - -.. index:: - triple: General; Verify; Example -.. _`Verify`: - - -.. raw:: latex - - \footnotesize - -:: - - Schedule { - Name = "VerifyCycle" - Run = Level=Catalog sun-sat at 5:05 - } - Job { - Name = "MatouVerify" - Type = Verify - Level = Catalog # default level - Client = MatouVerify - FileSet = "Verify Set" - Messages = Standard - Storage = DLTDrive - Pool = Default - Schedule = "VerifyCycle" - } - # - # The list of files in this FileSet should be carefully - # chosen. This is a good starting point. - # - FileSet { - Name = "Verify Set" - Include { - Options { - verify=pins1 - signature=SHA1 - } - File = /boot - File = /bin - File = /sbin - File = /usr/bin - File = /lib - File = /root/.ssh - File = /home/user/.ssh - File = /var/named - File = /etc/sysconfig - File = /etc/ssh - File = /etc/security - File = /etc/exports - File = /etc/rc.d/init.d - File = /etc/sendmail.cf - File = /etc/sysctl.conf - File = /etc/services - File = /etc/xinetd.d - File = /etc/hosts.allow - File = /etc/hosts.deny - File = /etc/hosts - File = /etc/modules.conf - File = /etc/named.conf - File = /etc/pam.d - File = /etc/resolv.conf - } - Exclude = { } - } - Client { - Name = MatouVerify - Address = lmatou - Catalog = Bareos - Password = "" - File Retention = 80d # 80 days - Job Retention = 1y # one year - AutoPrune = yes # Prune expired Jobs/Files - } - Catalog { - Name = Bareos - dbname = verify; user = bareos; password = "" - } - -.. raw:: latex - - \normalsize diff --git a/docs/manuals/en/new_main_reference/source/webui.rst b/docs/manuals/en/new_main_reference/source/webui.rst index 065a4f0ca4b..31a115dfd02 100644 --- a/docs/manuals/en/new_main_reference/source/webui.rst +++ b/docs/manuals/en/new_main_reference/source/webui.rst @@ -1,9 +1,9 @@ This chapter addresses the installation process of the -|bareosWebui| . +|bareosWebui|. -Since 15.2.0 -|bareosWebui| is part of the Bareos project and available for -a number of platforms. +Since :raw-latex:`\sinceVersion{dir}{bareos-webui}{15.2.0}` +:raw-latex:`\bareosWebui `is part of the Bareos project and available +for a number of platforms. |image| @@ -52,32 +52,32 @@ Features System Requirements =================== -- A platform, for which the **bareos-webui** package - is available, see :ref:**sec:BareosPackages**. +- A platform, for which the :raw-latex:`\package{bareos-webui}` package + is available, see :raw-latex:`\nameref{sec-BareosPackages}`. - A working Bareos environment. -- |bareosDir| version :math:**>=** - |bareosWebui| version. +- |bareosDir| version :math:`>=` + :raw-latex:`\bareosWebui `version. -- The |bareosWebui| can be installed on any host. It does - not have to be installed on the same as the |bareosDir| . +- The :raw-latex:`\bareosWebui `can be installed on any host. It does + not have to be installed on the same as the |bareosDir|. - The default installation uses an Apache webserver with mod-rewrite, mod-php and mod-setenv. -*- PHP :math:`>`* = 5.3.23 +- PHP :math:`>`\ = 5.3.23 - On SUSE Linux Enterprise 12 you need the additional SUSE Linux Enterprise Module for Web Scripting 12. -Version :math:**<** 16.2 +Version :math:`<` 16.2 ---------------------- -|bareosWebui| 16.2.4 +:raw-latex:`\bareosWebui `:raw-latex:`\sinceVersion{}{bareos-webui incorporates Zend Framework 2}{16.2.4}` incorporates the required Zend Framework 2 components, no extra Zend Framework installation is required. For older versions of -**bareos-webui**, you must install Zend Framework +:raw-latex:`\package{bareos-webui}`, you must install Zend Framework separately. Unfortunately, not all distributions offer Zend Framework 2 packages. The following list shows where to get the Zend Framework 2 package: @@ -97,7 +97,7 @@ package: - http://download.bareos.org/bareos Also be aware, that older versions of |bareosDir| do not -support the :ref:**sec:SubdirectoryConfigurationScheme** +support the :raw-latex:`\nameref{sec-SubdirectoryConfigurationScheme}` and therefore Bareos configuration resource files must be included manually. @@ -109,7 +109,7 @@ Adding the Bareos Repository If not already done, add the Bareos repository that is matching your Linux distribution. Please have a look at the chapter -:ref:**sec:InstallBareosPackages** for more information on +:raw-latex:`\nameref{sec-InstallBareosPackages}` for more information on how to achieve this. Install the bareos-webui package @@ -120,293 +120,281 @@ your package manager. - RHEL, CentOS and Fedora - .. raw:: latex + :: -* *begin{commands}{} - yum install bareos-webui -* *end{commands} + {} + yum install bareos-webui or - .. raw:: latex + :: -* *begin{commands}{} - dnf install bareos-webui -* *end{commands} + {} + dnf install bareos-webui - SUSE Linux Enterprise Server (SLES), openSUSE - .. raw:: latex + :: -* *begin{commands}{} - zypper install bareos-webui -* *end{commands} + {} + zypper install bareos-webui - Debian, Ubuntu - .. raw:: latex + :: -* *begin{commands}{} - apt-get install bareos-webui -* *end{commands} + {} + apt-get install bareos-webui Minimal Configuration --------------------- -This assumes, |bareosDir| and |bareosWebui| are +This assumes, |bareosDir| and :raw-latex:`\bareosWebui `are installed on the same host. #. If you are using SELinux, allow HTTPD scripts and modules make network connections: - .. raw:: latex + :: -* *begin{commands}{} - setsebool -P httpd_can_network_connect on -* *end{commands} + {} + setsebool -P httpd_can_network_connect on - For details, see :ref:**sec:webui-selinux**. + For details, see :raw-latex:`\nameref{sec-webui-selinux}`. #. Restart Apache (to load configuration provided by bareos-webui, see - :ref:**sec:webui-apache**) + :raw-latex:`\nameref{sec-webui-apache}`) -#. .. _item:webui-create-user: Use - :kbd:**bconsole** to create a user with name -* **admin}` and password :raw-latex:`*name{secret** and +#. :raw-latex:`\label{item:webui-create-user}` Use + :raw-latex:`\command{verbatim}` to create a user with name + :raw-latex:`\name{admin}` and password :raw-latex:`\name{secret}` and permissions defined in -* :raw-latex:`*resourcename{Dir}{Profile}{webui-admin}**: + :raw-latex:`\resourcename{Dir}{Profile}{webui-admin}`: - .. raw:: latex + :: -* *begin{bconsole}{add a named console} - *configure add console name=admin password=secret profile=webui-admin -* *end{bconsole} + {add a named console} + *configure add console name=admin password=secret profile=webui-admin Of course, you can choose other names and passwords. For details, see - :ref:**sec:webui-console**. + :raw-latex:`\nameref{sec-webui-console}`. #. Login to http://HOSTNAME/bareos-webui with username and password as -* created in :raw-latex:`*ref{item:webui-create-user}**. + created in :raw-latex:`\ref{item:webui-create-user}`. Configuration Details --------------------- +.. _sec-webui-console: + Create a restricted consoles ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There is not need, that |bareosWebui| itself provide a user +There is not need, that :raw-latex:`\bareosWebui `itself provide a user management. Instead it uses so named -*:raw-latex:`*resourcetype{Dir}{Console}** defined in the -|bareosDir| . You can have multiple consoles with different +:raw-latex:`\resourcetype{Dir}{Console}` defined in the +|bareosDir|. You can have multiple consoles with different names and passwords, sort of like multiple users, each with different privileges. -*At least one :raw-latex:`*resourcetype{Dir}{Console}** is required to use -the |bareosWebui| . +At least one :raw-latex:`\resourcetype{Dir}{Console}` is required to use +the |bareosWebui|. -To allow a user with name **admin** and password -**secret** to access the |bareosDir| with +To allow a user with name :raw-latex:`\name{admin}` and password +:raw-latex:`\name{secret}` to access the |bareosDir| with permissions defined in the -*:raw-latex:`*resourcename{Dir}{Profile}{webui-admin}** (see -:ref:**sec:webui-profile**), either +:raw-latex:`\resourcename{Dir}{Profile}{webui-admin}` (see +:raw-latex:`\nameref{sec-webui-profile}`), either - create a file - */etc/bareos/bareos-dir.d/console/admin.conf* with + :raw-latex:`\file{/etc/bareos/bareos-dir.d/console/admin.conf}` with following content: - .. raw:: latex + :: + + {bareos-dir}{console}{admin} + Console { + Name = "admin" + Password = "secret" + Profile = "webui-admin" + } -* *begin{bareosConfigResource}{bareos-dir}{console}{admin} - Console { - Name = "admin" - Password = "secret" - Profile = "webui-admin" - } -* *end{bareosConfigResource} + To enable this, reload or restart your |bareosDir|. - To enable this, reload or restart your |bareosDir| . +- or use the :raw-latex:`\command{verbatim}`: -- or use the :kbd:**bconsole**: + :: - .. raw:: latex + {add console} + *configure add console name=admin password=secret profile=webui-admin -* *begin{bconsole}{add console} - *configure add console name=admin password=secret profile=webui-admin -* *end{bconsole} +For details, please read :raw-latex:`\nameref{DirectorResourceConsole}`. -For details, please read :ref:**DirectorResourceConsole**. +.. _sec-webui-profile: Configuration of profile resources ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The package **bareos-webui** comes with a predefined -profile for |bareosWebui| : -*:raw-latex:`*resourcename{Dir}{Profile}{webui-admin}**. +The package :raw-latex:`\package{bareos-webui}` comes with a predefined +profile for |bareosWebui|: +:raw-latex:`\resourcename{Dir}{Profile}{webui-admin}`. -If your |bareosWebui| is installed on another system then the -|bareosDir| , you have to copy the profile to the -|bareosDir| . +If your :raw-latex:`\bareosWebui `is installed on another system then +the |bareosDir|, you have to copy the profile to the +|bareosDir|. This is the default profile, giving access to all Bareos resources and -allowing all commands used by the |bareosWebui| : - -.. raw:: latex - -* *begin{bareosConfigResource}{bareos-dir}{profile}{webui-admin} - Profile { - Name = webui-admin - CommandACL = !.bvfs_clear_cache, !.exit, !.sql, !configure, !create, !delete, !purge, !sqlquery, !umount, !unmount, *all* - Job ACL = *all* - Schedule ACL = *all* - Catalog ACL = *all* - Pool ACL = *all* - Storage ACL = *all* - Client ACL = *all* - FileSet ACL = *all* - Where ACL = *all* - Plugin Options ACL = *all* - } -* *end{bareosConfigResource} - -*The :raw-latex:`*resourcetype{Dir}{Profile}** itself does not give any -access to the |bareosDir| , but can be used by -*:raw-latex:`*resourcetype{Dir}{Console}**, which do give access to the -|bareosDir| , see :ref:**sec:webui-console**. - -For details, please read :ref:**DirectorResourceProfile**. +allowing all commands used by the |bareosWebui|: + +:: + + {bareos-dir}{profile}{webui-admin} + Profile { + Name = webui-admin + CommandACL = !.bvfs_clear_cache, !.exit, !.sql, !configure, !create, !delete, !purge, !sqlquery, !umount, !unmount, *all* + Job ACL = *all* + Schedule ACL = *all* + Catalog ACL = *all* + Pool ACL = *all* + Storage ACL = *all* + Client ACL = *all* + FileSet ACL = *all* + Where ACL = *all* + Plugin Options ACL = *all* + } + +The :raw-latex:`\resourcetype{Dir}{Profile}` itself does not give any +access to the |bareosDir|, but can be used by +:raw-latex:`\resourcetype{Dir}{Console}`, which do give access to the +|bareosDir|, see :raw-latex:`\nameref{sec-webui-console}`. + +For details, please read :raw-latex:`\nameref{DirectorResourceProfile}`. + +.. _sec-webui-selinux: SELinux ~~~~~~~ - -.. index:: - triple: General; SELinux; bareos-webui +:raw-latex:`\index[general]{SELinux!bareos-webui}` To use |bareosDir| on a system with SELinux enabled, permission must be given to HTTPD to make network connections: -.. raw:: latex +:: -* *begin{commands}{} - setsebool -P httpd_can_network_connect on -* *end{commands} + {} + setsebool -P httpd_can_network_connect on Configure your Apache Webserver ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:raw-latex:`\index[general]{Apache!bareos-webui}` +:raw-latex:`\label{sec-webui-apache}` -.. index:: - triple: General; Apache; bareos-webui -.. _sec:webui-apache: - -The package **bareos-webui** provides a default +The package :raw-latex:`\package{bareos-webui}` provides a default configuration for Apache. Depending on your distribution, it is -installed at */etc/apache2/conf.d/bareos-webui.conf*, -*/etc/httpd/conf.d/bareos-webui.conf* or -*/etc/apache2/available-conf/bareos-webui.conf*. +installed at :raw-latex:`\file{/etc/apache2/conf.d/bareos-webui.conf}`, +:raw-latex:`\file{/etc/httpd/conf.d/bareos-webui.conf}` or +:raw-latex:`\file{/etc/apache2/available-conf/bareos-webui.conf}`. -The required Apache modules, **setenv**, -***rewrite}` and :raw-latex:`*argument{php** are +The required Apache modules, :raw-latex:`\argument{setenv}`, +:raw-latex:`\argument{rewrite}` and :raw-latex:`\argument{php}` are enabled via package postinstall script. However, after installing the -**bareos-webui** package, you need to restart your +:raw-latex:`\package{bareos-webui}` package, you need to restart your Apache webserver manually. Configure your /etc/bareos-webui/directors.ini ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. index:: - triple: General; Configuration; WebUI -.. _sec:webui-configuration-files: +:raw-latex:`\index[general]{Configuration!WebUI}` +:raw-latex:`\label{sec-webui-configuration-files}` Configure your directors in -*/etc/bareos-webui/directors.ini* to match your +:raw-latex:`\file{/etc/bareos-webui/directors.ini}` to match your settings. The configuration file -*/etc/bareos-webui/directors.ini* should look similar +:raw-latex:`\file{/etc/bareos-webui/directors.ini}` should look similar to this: -.. raw:: latex - -* *begin{bconfig}{/etc/bareos-webui/directors.ini} - ; - ; Bareos WebUI Configuration File - ; - ; File: /etc/bareos-webui/directors.ini - ; - - ;------------------------------------------------------------------------------ - ; Section localhost-dir - ;------------------------------------------------------------------------------ - [localhost-dir] - - ; Enable or disable section. Possible values are "yes" or "no", the default is "yes". - enabled = "yes" - - ; Fill in the IP-Address or FQDN of you director. - diraddress = "localhost" - - ; Default value is 9101 - dirport = 9101 - - ; Set catalog to explicit value if you have multiple catalogs - ;catalog = "MyCatalog" - - ; TLS verify peer - ; Possible values: true or false - tls_verify_peer = false - - ; Server can do TLS - ; Possible values: true or false - server_can_do_tls = false - - ; Server requires TLS - ; Possible values: true or false - server_requires_tls = false - - ; Client can do TLS - ; Possible values: true or false - client_can_do_tls = false - - ; Client requires TLS - ; Possible value: true or false - client_requires_tls = false - - ; Path to the certificate authority file - ; E.g. ca_file = "/etc/bareos-webui/tls/BareosCA.crt" - ;ca_file = "" - - ; Path to the cert file which needs to contain the client certificate and the key in PEM encoding - ; E.g. ca_file = "/etc/bareos-webui/tls/restricted-named-console.pem" - ;cert_file = "" - - ; Passphrase needed to unlock the above cert file if set - ;cert_file_passphrase = "" - - ; Allowed common names - ; E.g. allowed_cns = "host1.example.com" - ;allowed_cns = "" - - ;------------------------------------------------------------------------------ - ; Section another-host-dir - ;------------------------------------------------------------------------------ - [another-host-dir] - enabled = "no" - diraddress = "192.168.120.1" - dirport = 9101 - ;catalog = "MyCatalog" - ;tls_verify_peer = false - ;server_can_do_tls = false - ;server_requires_tls = false - ;client_can_do_tls = false - ;client_requires_tls = false - ;ca_file = "" - ;cert_file = "" - ;cert_file_passphrase = "" - ;allowed_cns = "" - -* *end{bconfig} +:: + + {/etc/bareos-webui/directors.ini} + ; + ; Bareos WebUI Configuration File + ; + ; File: /etc/bareos-webui/directors.ini + ; + + ;------------------------------------------------------------------------------ + ; Section localhost-dir + ;------------------------------------------------------------------------------ + [localhost-dir] + + ; Enable or disable section. Possible values are "yes" or "no", the default is "yes". + enabled = "yes" + + ; Fill in the IP-Address or FQDN of you director. + diraddress = "localhost" + + ; Default value is 9101 + dirport = 9101 + + ; Set catalog to explicit value if you have multiple catalogs + ;catalog = "MyCatalog" + + ; TLS verify peer + ; Possible values: true or false + tls_verify_peer = false + + ; Server can do TLS + ; Possible values: true or false + server_can_do_tls = false + + ; Server requires TLS + ; Possible values: true or false + server_requires_tls = false + + ; Client can do TLS + ; Possible values: true or false + client_can_do_tls = false + + ; Client requires TLS + ; Possible value: true or false + client_requires_tls = false + + ; Path to the certificate authority file + ; E.g. ca_file = "/etc/bareos-webui/tls/BareosCA.crt" + ;ca_file = "" + + ; Path to the cert file which needs to contain the client certificate and the key in PEM encoding + ; E.g. ca_file = "/etc/bareos-webui/tls/restricted-named-console.pem" + ;cert_file = "" + + ; Passphrase needed to unlock the above cert file if set + ;cert_file_passphrase = "" + + ; Allowed common names + ; E.g. allowed_cns = "host1.example.com" + ;allowed_cns = "" + + ;------------------------------------------------------------------------------ + ; Section another-host-dir + ;------------------------------------------------------------------------------ + [another-host-dir] + enabled = "no" + diraddress = "192.168.120.1" + dirport = 9101 + ;catalog = "MyCatalog" + ;tls_verify_peer = false + ;server_can_do_tls = false + ;server_requires_tls = false + ;client_can_do_tls = false + ;client_requires_tls = false + ;ca_file = "" + ;cert_file = "" + ;cert_file_passphrase = "" + ;allowed_cns = "" You can add as many directors as you want, also the same host with a different name and different catalog, if you have multiple catalogs. @@ -415,61 +403,59 @@ Configure your /etc/bareos-webui/configuration.ini ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Since -16.2.2 +:raw-latex:`\sinceVersion{}{/etc/bareos-webui/configuration.ini}{16.2.2}` you are able to configure some parameters of the -|bareosWebui| to your needs. - -.. raw:: latex - -* *begin{bconfig}{/etc/bareos-webui/configuration.ini} - ; - ; Bareos WebUI Configuration File - ; - ; File: /etc/bareos-webui/configuration.ini - ; - - ;------------------------------------------------------------------------------ - ; SESSION SETTINGS - ;------------------------------------------------------------------------------ - ; - [session] - ; Default: 3600 seconds - timeout=3600 - - ;------------------------------------------------------------------------------ - ; DASHBOARD SETTINGS - ;------------------------------------------------------------------------------ - [dashboard] - ; Autorefresh Interval - ; Default: 60000 milliseconds - autorefresh_interval=60000 - - ;------------------------------------------------------------------------------ - ; TABLE SETTINGS - ;------------------------------------------------------------------------------ - [tables] - ; Possible values for pagination - ; Default: 10,25,50,100 - pagination_values=10,25,50,100 - - ; Default number of rows per page - ; for possible values see pagination_values - ; Default: 25 - pagination_default_value=25 - - ; State saving - restore table state on page reload. - ; Default: false - save_previous_state=false - - ;------------------------------------------------------------------------------ - ; VARIOUS SETTINGS - ;------------------------------------------------------------------------------ - [autochanger] - ; Pooltype for label to use as filter. - ; Default: none - labelpooltype=scratch - -* *end{bconfig} +:raw-latex:`\bareosWebui `to your needs. + +:: + + {/etc/bareos-webui/configuration.ini} + ; + ; Bareos WebUI Configuration File + ; + ; File: /etc/bareos-webui/configuration.ini + ; + + ;------------------------------------------------------------------------------ + ; SESSION SETTINGS + ;------------------------------------------------------------------------------ + ; + [session] + ; Default: 3600 seconds + timeout=3600 + + ;------------------------------------------------------------------------------ + ; DASHBOARD SETTINGS + ;------------------------------------------------------------------------------ + [dashboard] + ; Autorefresh Interval + ; Default: 60000 milliseconds + autorefresh_interval=60000 + + ;------------------------------------------------------------------------------ + ; TABLE SETTINGS + ;------------------------------------------------------------------------------ + [tables] + ; Possible values for pagination + ; Default: 10,25,50,100 + pagination_values=10,25,50,100 + + ; Default number of rows per page + ; for possible values see pagination_values + ; Default: 25 + pagination_default_value=25 + + ; State saving - restore table state on page reload. + ; Default: false + save_previous_state=false + + ;------------------------------------------------------------------------------ + ; VARIOUS SETTINGS + ;------------------------------------------------------------------------------ + [autochanger] + ; Pooltype for label to use as filter. + ; Default: none + labelpooltype=scratch Upgrade from 15.2 to 16.2 ========================= @@ -477,21 +463,22 @@ Upgrade from 15.2 to 16.2 Console/Profile changes ----------------------- -The |bareosWebui| Director profile shipped with Bareos 15.2 -*(:raw-latex:`*resourcename{Dir}{Profile}{webui}** in the file -*/etc/bareos/bareos-dir.d/webui-profiles.conf*) is not -sufficient to use the |bareosWebui| 16.2. This has several +The :raw-latex:`\bareosWebui `Director profile shipped with Bareos 15.2 +(:raw-latex:`\resourcename{Dir}{Profile}{webui}` in the file +:raw-latex:`\file{/etc/bareos/bareos-dir.d/webui-profiles.conf}`) is not +sufficient to use the :raw-latex:`\bareosWebui `16.2. This has several reasons: -*#. The handling of :raw-latex:`*dt{Acl}**s is more strict in Bareos 16.2 +#. The handling of :raw-latex:`\dt{Acl}`s is more strict in Bareos 16.2 then it has been in Bareos 15.2. Substring matching is no longer - enabled, therefore you need to change :kbd:**.bvfs_*** - to :kbd:**.bvfs_.*** in your -* :raw-latex:`*linkResourceDirective{Dir}{Profile}{Command ACL}** to + enabled, therefore you need to change :raw-latex:`\bcommand{.bvfs_*}` + to :raw-latex:`\bcommand{.bvfs_.*}` in your + :raw-latex:`\linkResourceDirective{Dir}{Profile}{Command ACL}` to have a proper regular expression. Otherwise the restore module won’t work any longer, especially the file browser. -#. The |bareosWebui| 16.2 uses following additional commands: +#. The :raw-latex:`\bareosWebui `16.2 uses following additional + commands: - .help @@ -512,32 +499,32 @@ reasons: - disable If you used an unmodified -*/etc/bareos/bareos-dir.d/webui-profiles.conf* file, +:raw-latex:`\file{/etc/bareos/bareos-dir.d/webui-profiles.conf}` file, the easiest way is to overwrite it with the new profile file -*/etc/bareos/bareos-dir.d/profile/webui-admin.conf*. -*The new :raw-latex:`*resourcename{Dir}{Profile}{webui-admin}** allows all +:raw-latex:`\file{/etc/bareos/bareos-dir.d/profile/webui-admin.conf}`. +The new :raw-latex:`\resourcename{Dir}{Profile}{webui-admin}` allows all commands, except of the dangerous ones, see -:ref:**sec:webui-profile**. +:raw-latex:`\nameref{sec-webui-profile}`. directors.ini ------------- Since -16.2.0 +:raw-latex:`\sinceVersion{general}{Webui offers limited support for multiple catalogs}{16.2.0}` it is possible to work with different catalogs. Therefore the catalog parameter has been introduced. If you don’t set a catalog explicitly the -*default :raw-latex:`*resourcename{Dir}{Catalog}{MyCatalog}** will be -used. Please see :ref:**sec:webui-configuration-files** +default :raw-latex:`\resourcename{Dir}{Catalog}{MyCatalog}` will be +used. Please see :raw-latex:`\nameref{sec-webui-configuration-files}` for more details. configuration.ini ----------------- -Since 16.2 the |bareosWebui| introduced an additional +Since 16.2 the :raw-latex:`\bareosWebui `introduced an additional configuration file besides the directors.ini file named configuration.ini where you are able to adjust some parameters of the webui to your needs. Please see -:ref:**sec:webui-configuration-files** for more details. +:raw-latex:`\nameref{sec-webui-configuration-files}` for more details. Additional information ====================== @@ -545,39 +532,49 @@ Additional information NGINX ----- +:raw-latex:`\index[general]{nginx!bareos-webui}` -.. index:: - triple: General; nginx; bareos-webui - -If you prefer to use |bareosWebui| on Nginx with php5-fpm +If you prefer to use :raw-latex:`\bareosWebui `on Nginx with php5-fpm instead of Apache, a basic working configuration could look like this: -*:raw-latex:`*todo{repair manually}** - -This will make the |bareosWebui| accessible at -http://bareos:9100/ (assuming your DNS resolve the hostname -**bareos** to the NGINX server). - -*.. |image| image:: *idir bareos-webui-jobs - :width: 80.0% - - - - - - - - - +:: + {bareos-webui on nginx} + server { + listen 9100; + server_name bareos; + root /var/www/bareos-webui/public; + location / { + index index.php; + try_files $uri $uri/ /index.php?$query_string; + } + location ~ .php$ { + include snippets/fastcgi-php.conf; + # php5-cgi alone: + # pass the PHP + # scripts to FastCGI server + # listening on 127.0.0.1:9000 + #fastcgi_pass 127.0.0.1:9000; + # php5-fpm: + fastcgi_pass unix:/var/run/php5-fpm.sock; + # APPLICATION_ENV: set to 'development' or 'production' + #fastcgi_param APPLICATION_ENV development; + fastcgi_param APPLICATION_ENV production; + } + } +This will make the :raw-latex:`\bareosWebui `accessible at +http://bareos:9100/ (assuming your DNS resolve the hostname +:raw-latex:`\host{bareos}` to the NGINX server). +.. |image| image:: \idir bareos-webui-jobs + :width: 80.0% diff --git a/docs/manuals/en/new_main_reference/source/win32.rst b/docs/manuals/en/new_main_reference/source/win32.rst index 37c66c58bda..8b137891791 100644 --- a/docs/manuals/en/new_main_reference/source/win32.rst +++ b/docs/manuals/en/new_main_reference/source/win32.rst @@ -1,892 +1 @@ -The Windows Version of Bareos -============================= -.. _sec:windows: - -.. index:: - triple: General; Platform; Windows -.. index:: General; Windows - -The Windows version of Bareos is a native Win32 port, but there are very -few source code changes to the Unix code, which means that the Windows -version is for the most part running code that has long proved stable on -Unix systems. - -Chapter :ref:`SupportedOSes` shows, what Windows -versions are supported. - -The Bareos component that is most often used in Windows is the File -daemon or Client program. As a consequence, when we speak of the Windows -version of Bareos below, we are mostly referring to the File daemon -(client). - -Once installed Bareos normally runs as a system service. This means that -it is immediately started by the operating system when the system is -booted, and runs in the background even if there is no user logged into -the system. - -Windows Installation --------------------- - -.. _Windows:Configuration:Files: - -.. index:: - triple: General; Installation; Windows - -.. index:: - triple: General; Windows!File Daemon; Installation - -Normally, you will install the Windows version of Bareos from the -binaries. The **winbareos** binary packages are provided -under http://download.bareos.org/bareos/release/latest/windows. -Additionally, there are http://www.opsi.org -packages available under -http://download.bareos.org/bareos/release/latest/windows/opsi. - -This install is standard Windows .exe that runs an install wizard using -the NSIS Free Software installer, so if you have already installed -Windows software, it should be very familiar to you. Providing you do -not already have Bareos installed, the installer installs the binaries -and dlls in *C:\Program Files\Bareos* and the -configuration files in *C:\ProgramData\Bareos* -(for Windows XP and older: -*C:\Documents and Settings\All Users\Application Data\Bareos*). - -In addition, the **Start:raw-latex:`\-{\textgreater}`All -Programs:raw-latex:`\-{\textgreater}`Bareos** menu item will be created -during the installation, and on that menu, you will find items for -editing the configuration files, displaying the document, and starting a -user interface. - -During installation you can decide, what Bareos components you want to -install. - -Typically, you only want to install the Bareos Client -( |bareosFd| ) and optionally some interface tools on a -Windows system. Normally, we recommend to let the server components run -on a Linux or other Unix system. However, it is possible, to run the - |bareosDir| , |bareosSd| and - |bareosWebui| on a Windows systems. You should be aware about -following limitations: - -:raw-latex:`\limitation{Windows}{\bareosDir does not support MySQL database backend}{ -When running the \bareosDir on Windows, only PostgreSQL (and SQLite) database backends are supported. -SQLite is best suited for test environments. -}` -:raw-latex:`\limitation{Windows}{\bareosSd only support backup to disk, not to tape}{ -}` -:raw-latex:`\limitation{Windows}{The default installation of \bareosWebui is only suitable for local access}{% -Normally the \bareosWebui is running on a Apache server on Linux. -While it is possible, to run the \bareosWebui under Apache or another Webserver which supports PHP under Windows, -the configuration shipped the the \package{winbareos} package uses the PHP internal webserver. -This is okay for local access, but not suitable for being accessed via the network. -To guarantee this, it is configured to only listen locally (\url{http://localhost:9100}). -}` - -Graphical Installation -~~~~~~~~~~~~~~~~~~~~~~ - -Here are the important steps. - -- You must be logged in as an Administrator to the local machine to do - a correct installation, if not, please do so before continuing. - -- For a standard installation you may only select the “Tray-Monitor” - and the “Open Firewall for Client” as additional optional components. - - |image| - -- You need to fill in the name of your bareos director in the client - configuration dialogue and the FQDN or ip address of your client. - - |image| - -- Add the client resource to your Bareos Director Configuration and a - job resource for the client as it is also described in the default - bareos-dir.conf - - |image| - -Command Line (Silent) Installation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Silent installation is possible since -12.4.4. -All inputs that are given during interactive install can now directly be -configured on the commandline, so that an automatic silent install is -possible. - -Commandline Switches -'''''''''''''''''''' - -/? - shows the list of available parameters. - -/S - sets the installer to silent. The Installation is done without user - interaction. This switch is also available for the uninstaller. - -/CLIENTADDRESS - network address of the client - -/CLIENTNAME - sets the name of the client resource - -/CLIENTMONITORPASSWORD - sets the password for monitor access - -/CLIENTPASSWORD - sets the password to access the client - -/DBADMINUSER=user - sets the database admin user, default=postgres. - 14.2.1 - -/DBADMINPASSWORD=password - sets the database admin password, default=\ *none*. - 14.2.1 - -/DIRECTORADDRESS - sets network address of the director for bconsole or bat access - -/DIRECTORNAME - sets the name of the director to access the client and of the - director to accessed by bconsole and bat - -/DIRECTORPASSWORD - set the password to access the director - -/SILENTKEEPCONFIG - keep configuration files on silent uninstall and use exinsting - config files during silent install. - 12.4.4 - -/INSTALLDIRECTOR - install the Bareos Director (and bconsole). - 14.2.1 - -/INSTALLSTORAGE - install the Bareos Storage Daemon. - 14.2.1 - -/WRITELOGS - makes also non-debug installer write a log file. - 14.2.1 - -/D=*C::raw-latex:`\specify`:raw-latex:`\installation`:raw-latex:`\directory`* - (Important: It has to be the last option!) - -By setting the Installation Parameters via commandline and using the -silent installer, you can install the bareos client without having to do -any configuration after the installation e.g. as follows: - - - -:: - - c:\winbareos.exe /S /CLIENTNAME=hostname-fd /CLIENTPASSWORD="verysecretpassword" /DIRECTORNAME=bareos-dir - - - -DBADMINUSER and DBADMINPASSWORD are used to create the bareos databases. -If login is not possible silent installer will abort - -Dealing with Windows Problems ------------------------------ - - -.. index:: - triple: General; Problem; Windows - -.. index:: - triple: General; Windows; Dealing with Problems - -Antivirus Program -~~~~~~~~~~~~~~~~~ - -If you are not using the portable option, and you have -Enable VSS (Volume -Shadow Copy) enabled in the |bareosDir| and you experience -problems with Bareos not being able to open files, it is most likely -that you are running an antivirus program that blocks Bareos from doing -certain operations. In this case, disable the antivirus program and try -another backup. If it succeeds, either get a different (better) -antivirus program or use something like -Client Run Before Job -to turn off the antivirus program while the backup is running. - -If turning off anti-virus software does not resolve your VSS problems, -you might have to turn on VSS debugging. The following link describes -how to do this: http://support.microsoft.com/kb/887013/en-us. - -Enable Debuggging -~~~~~~~~~~~~~~~~~ - -In case of problems, you can enable the creation of log files. For this -you have to use the :command:`bconsole` -:ref:`setdebug bcommandSetdebug` command: - -.. raw:: latex - - \begin{bconsole}{Enable debug} - *setdebug client=bareos-fd level=200 trace=1 - Connecting to Client bareos-fd at bareos.example.com:9102 - 2000 OK setdebug=200 trace=1 hangup=0 tracefile=c:\bareos-fd.trace - \end{bconsole} - -Windows Compatibility Considerations ------------------------------------- - - -.. index:: - triple: General; Windows; Compatibility Considerations - -Exclusively Opened Files -~~~~~~~~~~~~~~~~~~~~~~~~ - -If you are not using the :ref:`VSS` option and if any -applications are running during the backup and they have files opened -exclusively, Bareos will not be able to backup those files, so be sure -you close your applications (or tell your users to close their -applications) before the backup. Fortunately, most Microsoft -applications do not open files exclusively so that they can be backed -up. However, you will need to experiment. In any case, if Bareos cannot -open the file, it will print an error message, so you will always know -which files were not backed up. If Volume Shadow Copy Service is -enabled, Bareos is able to backing up any file. - -Backing up the Windows Registry -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -During backup, Bareos doesn’t know about the system registry, so you -will either need to write it out to an ASCII file using -:command:`regedit /e` or use a program specifically designed -to make a copy or backup the registry. - -Windows Reparse Points -~~~~~~~~~~~~~~~~~~~~~~ - -12.4.5 -:raw-latex:`\index[fd]{Windows!Symbolic links}` -:raw-latex:`\index[fd]{Windows!Junction points}` -:raw-latex:`\index[fd]{Windows!Volume Mount Points (VMP)}` - -Besides normal files and directories, Windows filesystems also support -special files, called “Reparse Points”. Bareos can handle the following -types of Reparse points: - -- Symbolic links to directories - -- Symbolic links to files - -- Junction Points - -- Volume Mount Points - -The Volume Mount Points are a special case of a Junction Point. To make -things easier, in the following when talking about Junction Points, we -mean only the Junction Points that are not Volume Mount Points. - -The Symbolic Links and the Junction Points are comparable to Symbolic -Links in Unix/Linux. They are files that point to another location in -the filesystem. - -Symbolic Links and Junction Points can be created with the Windows -commandline command :command:`mklink`. - -When doing a directory listing in the commandline (cmd) in Windows, it -shows the filetypes JUNCTION, SYMLINK or SYMLINKD and the target between -the square brackets: - -.. raw:: latex - - \begin{commands}{special files} - C:\linktest>dir - Volume in drive C has no label. - Volume Serial Number is C8A3-971F - - Directory of C:\linktest - - 08/07/2014 03:05 PM . - 08/07/2014 03:05 PM .. - 08/07/2014 02:59 PM dirlink [C:\Program Files\Bareos] - 08/07/2014 03:02 PM filelink [C:\Program Files\Bareos\bareos-dir.exe] - 08/07/2014 03:00 PM junction [C:\Program Files\Bareos] - 08/07/2014 03:05 PM volumemountpoint [\??\Volume{e960247d-09a1-11e3-93ec-005056add71d}\] - 1 File(s) 0 bytes - 5 Dir(s) 90,315,137,024 bytes free - \end{commands} - -Symbolic Links. Directory Symbolic Links, and Junctions that are not a -Volume MountPoint are treated by Bareos as symbolic links and are backed -up and restored as they are, so the object is restored and points to -where it pointed when it was backed up. - -Volume Mount Points are different. They allow to mount a harddisk -partition as a subfolder of a drive instead of a driveletter. - -When backing up a Volume Mount Point, it is backed up as directory. - -If :raw-latex:`\configdirective{OneFS}` is set to yes (default), the -Volume Mount Point (VMP) is backed up as directory but the content of -the VMP will not be backed up. Also, the Joblog will contain a message -like this: - -.. raw:: latex - - \begin{bmessage}{Warning on Volume Moint Point and OneFS=yes} - C:/linktest/vmp is a different filesystem. Will not descend from C:/linktest into it. - \end{bmessage} - -This is the normal behavior of the :raw-latex:`\configdirective{OneFS}` -option. - -If OneFS is set to no, the filedaemon will change into the VMP as if it -was a normal directory and will backup all files found inside of the -VMP. - -VMPs and VSS Snapshots -^^^^^^^^^^^^^^^^^^^^^^ - -As Virtual Mount Points mounts another Volume into the current -filesystem, it is desired that if the content of the VMP will be backed -up during the backup (:raw-latex:`\configline{onefs = no}`), we also -want to have this volume snapshotted via VSS. - -To achieve this, we now automatically check every volume added to the -VSS snapshotset if it contains VMPs, and add the volumes mounted by -those VMPs to the vss snapshotset recursively. - -Volumes can be mounted nested and multiple times, but can only be added -to the snapshotset once. This is the reason why the number of vmps can -be greater than the number of volumes added for the volume mount points. - -The Job Log will show how many VMPs were found like this: - -.. raw:: latex - - \begin{bmessage}{Volume Mount Points are added automatically to VSS snapshots (if onefs=no)} - Volume Mount Points found: 7, added to snapshotset: 5 - \end{bmessage} - -Accordingly, if OneFS is set to yes, we do not need to handle Volume -Mount Points this way. If OneFS is set to yes (default), the joblog will -contain the following information: - -.. raw:: latex - - \begin{bmessage}{Volume Mount Points are ignored on VSS snapshots (if onefs=yes)} - VolumeMountpoints are not processed as onefs = yes. - \end{bmessage} - -Hard Links -~~~~~~~~~~ - -Windows also supports hard links, even so they are seldom used. These -are treated as normal files and will be restored as individual files -(which will not be hardlinks again) - -FilesNotToBackup Registry Key -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -14.2.0 -:raw-latex:`\index[fd]{Windows!Exclude Files from Backup}` - -Windows supports a special Registry Key that specifies the names of the -files and directories that backup applications should not backup or -restore. - -The full path to this registry key is -:raw-latex:`\registrykey{HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\BackupRestore\FilesNotToBackup}` - -Bareos automatically converts these entries to wildcards which will be -automatically excluded from backup. - -The backup log shows a short information about the creation of the -exludes like this: - -.. raw:: latex - - \begin{bmessage}{Excludes according to the FilesNotToBackup registry key} - Created 28 wildcard excludes from FilesNotToBackup Registry key - \end{bmessage} - -More details can be found if the filedaemon is run in debug mode inside -of the *bareos-fd.trace* logfile. Each entry and the -resulting wildcard are logged. - -.. raw:: latex - - \begin{bmessage}{translation between registry key FilesNotToBackup and Bareos Exclude FileSet} - client-win-fd: win32.c:465-0 (1) "WER" : - client-win-fd: win32.c:482-0 "C:\ProgramData\Microsoft\Windows\WER\* /s" - client-win-fd: win32.c:527-0 -> "C:/ProgramData/Microsoft/Windows/WER/*" - client-win-fd: win32.c:465-0 (2) "Kernel Dumps" : - client-win-fd: win32.c:482-0 "C:\Windows\Minidump\* /s" - client-win-fd: win32.c:527-0 -> "C:/Windows/Minidump/*" - client-win-fd: win32.c:482-0 "C:\Windows\memory.dmp" - client-win-fd: win32.c:527-0 -> "C:/Windows/memory.dmp" - client-win-fd: win32.c:465-0 (3) "Power Management" : - client-win-fd: win32.c:482-0 "\hiberfil.sys" - client-win-fd: win32.c:527-0 -> "[A-Z]:/hiberfil.sys" - client-win-fd: win32.c:465-0 (4) "MS Distributed Transaction Coordinator" : - client-win-fd: win32.c:482-0 "C:\Windows\system32\MSDtc\MSDTC.LOG" - client-win-fd: win32.c:527-0 -> "C:/Windows/system32/MSDtc/MSDTC.LOG" - client-win-fd: win32.c:482-0 "C:\Windows\system32\MSDtc\trace\dtctrace.log" - client-win-fd: win32.c:527-0 -> "C:/Windows/system32/MSDtc/trace/dtctrace.log" - \end{bmessage} - -It is possible to disable this functionality by setting the FileSet -option :raw-latex:`\configdirective{AutoExclude}` to no. - -The JobLog will then show the following informational line: - -.. raw:: latex - - \begin{bmessage}{AutoExclude disabled} - Fileset has autoexclude disabled, ignoring FilesNotToBackup Registry key - \end{bmessage} - -For more details about the Windows registry key see -http://msdn.microsoft.com/en-us/library/windows/desktop/bb891959%28v=vs.85%29.aspx#filesnottobackup. - -Windows dedup support -~~~~~~~~~~~~~~~~~~~~~ - -12.4.5 - -Windows 2012 has dedup support which needs handling. - -Store all file attributes -~~~~~~~~~~~~~~~~~~~~~~~~~ - -12.4.5 - -Windows has gathered quite some special specific file flags over the -years but not all are saved during backup so some are never restored by -the restore process. The most important ones are the ARCHIVE flag which -is “misused” by some programs for storing some special information. -Others that are known not to be stored are the COMPRESSED flag which -means that a restored file looses it and will be restored as an -uncompressed file. - -Support for Windows EFS filesystems -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -12.4.5 - -Windows has support for a so called EFS filesystem. This is an encrypted -filesystem, to be able to backup the data and to restore it we need to -use a special API. With this API you in essence export the data on -backup and import it on restore. This way you never have access to the -unencrypted data but just import and export the encrypted data. This is -the cleanest way of handling encryption by just seeing the data as some -opaque data and not try to do anything special with it. - -Volume Shadow Copy Service (VSS) --------------------------------- - - -.. index:: - triple: General; Windows; Volume Shadow Copy Service - -.. index:: - triple: General; Windows; VSS}` :raw-latex:`\label{VSS - -VSS is available since Windows XP. From the perspective of a -backup-solution for Windows, this is an extremely important step. VSS -allows Bareos to backup open files and even to interact with -applications like RDBMS to produce consistent file copies. VSS aware -applications are called VSS Writers, they register with the OS so that -when Bareos wants to do a Snapshot, the OS will notify the register -Writer programs, which may then create a consistent state in their -application, which will be backed up. Examples for these writers are -“MSDE” (Microsoft database engine), “Event Log Writer”, “Registry -Writer” plus 3rd party-writers. If you have a non-vss aware application -a shadow copy is still generated and the open files can be backed up, -but there is no guarantee that the file is consistent. - -Bareos produces a message from each of the registered writer programs -when it is doing a VSS backup so you know which ones are correctly -backed up. - -Technically Bareos creates a shadow copy as soon as the backup process -starts. It does then backup all files from the shadow copy and destroys -the shadow copy after the backup process. Please have in mind, that VSS -creates a snapshot and thus backs up the system at the state it had when -starting the backup. It will disregard file changes which occur during -the backup process. - -VSS can be turned on by placing an - -:raw-latex:`\index[dir]{Enable VSS}` - -.. index:: - triple: General; VSS; Enable - -:: - - Enable VSS = yes - -in your FileSet resource. - -The VSS aware File daemon has the letters VSS on the signon line that it -produces when contacted by the console. For example: - -:: - - Tibs-fd Version: 1.37.32 (22 July 2005) VSS Windows XP MVS NT 5.1.2600 - -the VSS is shown in the line above. This only means that the File daemon -is capable of doing VSS not that VSS is turned on for a particular -backup. There are two ways of telling if VSS is actually turned on -during a backup. The first is to look at the status output for a job, -e.g.: - -:: - - Running Jobs: - JobId 1 Job NightlySave.2005-07-23_13.25.45 is running. - VSS Backup Job started: 23-Jul-05 13:25 - Files=70,113 Bytes=3,987,180,650 Bytes/sec=3,244,247 - Files Examined=75,021 - Processing file: c:/Documents and Settings/user/My Documents/My Pictures/Misc1/Sans titre - 39.pdd - SDReadSeqNo=5 fd=352 - -Here, you see under Running Jobs that JobId 1 is -“VSS Backup Job started ...” This means that VSS is enabled for that -job. If VSS is not enabled, it will simply show “Backup Job started ...” -without the letters VSS. - -The second way to know that the job was backed up with VSS is to look at -the Job Report, which will look something like the following: - - -:: - - 23-Jul 13:25 rufus-dir: Start Backup JobId 1, Job=NightlySave.2005-07-23_13.25.45 - 23-Jul 13:26 rufus-sd: Wrote label to prelabeled Volume "TestVolume001" on device "DDS-4" (/dev/nst0) - 23-Jul 13:26 rufus-sd: Spooling data ... - 23-Jul 13:26 Tibs: Generate VSS snapshots. Driver="VSS WinXP", Drive(s)="C" - 23-Jul 13:26 Tibs: VSS Writer: "MSDEWriter", State: 1 (VSS_WS_STABLE) - 23-Jul 13:26 Tibs: VSS Writer: "Microsoft Writer (Bootable State)", State: 1 (VSS_WS_STABLE) - 23-Jul 13:26 Tibs: VSS Writer: "WMI Writer", State: 1 (VSS_WS_STABLE) - 23-Jul 13:26 Tibs: VSS Writer: "Microsoft Writer (Service State)", State: 1 (VSS_WS_STABLE) - -In the above Job Report listing, you see that -the VSS snapshot was generated for drive C (if other drives are backed -up, they will be listed on the -:raw-latex:`\bconsoleOutput{Drive(s)="C"}` line. You also see the -reports from each of the writer program. Here they all report -VSS\_WS\_STABLE, which means that you will get a consistent snapshot of -the data handled by that writer. - -VSS Problems -~~~~~~~~~~~~ - - -.. index:: - triple: General; Windows!Problem; VSS - -.. index:: - triple: General; Windows!VSS; Problem -:raw-latex:`\index[fd]{Windows!Problem!VSS}` - -.. index:: - triple: General; Problem!Windows; VSS - -If you are experiencing problems such as VSS hanging on MSDE, first try -running **vssadmin** to check for problems, then try running -**ntbackup** which also uses VSS to see if it has similar problems. If -so, you know that the problem is in your Windows machine and not with -Bareos. - -The FD hang problems were reported with **MSDEwriter** when: - -- a local firewall locked local access to the MSDE TCP port (MSDEwriter - seems to use TCP/IP and not Named Pipes). - -- msdtcs was installed to run under “localsystem”: try running msdtcs - under networking account (instead of local system) (com+ seems to - work better with this configuration). - -Windows Firewalls ------------------ - - -.. index:: - triple: General; Firewall; Windows - -.. index:: - triple: General; Windows; Firewall - -The Windows buildin Firewall is enabled since Windows version WinXP SP2. -The Bareos installer opens the required network ports for Bareos. -However, if you are using another Firewall, you might need to manually -open the Bareos network ports. The |bareosFd| listens on -9102/TCP. - -Network TCP Port -~~~~~~~~~~~~~~~~ - -If you want to see if the File daemon has properly opened the port and -is listening, you can enter the following command in a shell window: - -.. raw:: latex - - \begin{commands}{} - netstat -an | findstr 910[123] - \end{commands} - -Windows Restore Problems ------------------------- - - -.. index:: - triple: General; Problem; Windows Restore - -.. index:: - triple: General; Windows; Restore Problem - -Please see the :ref:`sec:RestoreOnWindows` chapter for -problems that you might encounter doing a restore. - -Windows Backup Problems ------------------------ - - -.. index:: - triple: General; Problem; Windows Backup - -.. index:: - triple: General; Windows; Backup Problems - -If during a Backup, you get the message: **ERR=Access is denied** and -you are using the portable option, you should try both adding both the -non-portable (backup API) and the Volume Shadow Copy options to your -Director’s conf file. - -In the Options resource: - -:: - - portable = no - - - -In the FileSet resource: - -:: - - enablevss = yes - - - -In general, specifying these two options should allow you to backup any -file on a Windows system. However, in some cases, if users have allowed -to have full control of their folders, even system programs such a -Bareos can be locked out. In this case, you must identify which folders -or files are creating the problem and do the following: - -#. Grant ownership of the file/folder to the Administrators group, with - the option to replace the owner on all child objects. - -#. Grant full control permissions to the Administrators group, and - change the user’s group to only have Modify permission to the - file/folder and all child objects. - -Thanks to Georger Araujo for the above information. - -Windows Ownership and Permissions Problems ------------------------------------------- - - -.. index:: - triple: General; Problem; Windows Ownership and Permissions - -.. index:: - triple: General; Windows; Ownership and Permissions Problems - -If you restore files backed up from Windows to an alternate directory, -Bareos may need to create some higher level directories that were not -saved (or restored). In this case, the File daemon will create them -under the SYSTEM account because that is the account that Bareos runs -under as a service and with full access permission. However, there may -be cases where you have problems accessing those files even if you run -as administrator. In principle, Microsoft supplies you with the way to -cease the ownership of those files and thus change the permissions. -However, a much better solution to working with and changing Win32 -permissions is the program **SetACL**, which can be found at -http://setacl.sourceforge.net/. - -If you have not installed Bareos while running as Administrator and if -Bareos is not running as a Process with the userid (User Name) SYSTEM, -then it is very unlikely that it will have sufficient permission to -access all your files. - -Some users have experienced problems restoring files that participate in -the Active Directory. They also report that changing the userid under -which Bareos (bareos-fd.exe) runs, from SYSTEM to a Domain Admin userid, -resolves the problem. - -:raw-latex:`\hide{ -\section{Fixing the Windows Boot Record} -\index[general]{Windows!Fixing the Boot Record} - -An effective way to restore a Windows backup is to install Windows on a different -hard drive and restore the backup. Then run the -recovery CD and run - -\begin{verbatim} -diskpart - select disk 0 - select part 1 - active - exit - -bootrec /rebuldbcd -bootrec /fixboot -bootrec /fixmbr -\end{verbatim} -}` - -Advanced Windows Configuration ------------------------------- - -Windows Service -~~~~~~~~~~~~~~~ - -The |bareosFd| (and also the |bareosDir| and - |bareosSd| ) is started as a Windows service. - -This is configured in the Registry at - -- *Computer:raw-latex:`\HKEY`\_LOCAL\_MACHINE:raw-latex:`\SYSTEM`:raw-latex:`\CurrentControlSet`:raw-latex:`\services`:raw-latex:`\Bareos`-fd* - -You can use the command :command:`regedit` to modify the -settings. - -E.g. to always start Bareos in debug mode, modify -*Computer:raw-latex:`\HKEY`\_LOCAL\_MACHINE:raw-latex:`\SYSTEM`:raw-latex:`\CurrentControlSet`:raw-latex:`\services`:raw-latex:`\Bareos`-fd* -*ImagePath* - - - -:: - - "C:\Program Files\Bareos\bareos-fd.exe" /service - -to - - - -:: - - "C:\Program Files\Bareos\bareos-fd.exe" /service -d200 - -After restarting the service, you will find a file called -*C::raw-latex:`\bareos`-fd.trace* -the debug output created by the daemon. - -Installing multiple Windows filedaemon services -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -It is possible to run multiple |bareosFd| instances on -Windows. To achieve this, you need to create a service for each -instance, and a configuration file that at least has a individual fd -port for each instance. - -To create two bareos-fd services, you can call the following service -create calls on the commandline on windows as administrator: - -.. raw:: latex - - \begin{commands}{} - sc create bareosfd2 binpath="\"C:\Program Files\Bareos\bareos-fd.exe\" /service -c \"C:\ProgramData\Bareos\bareos-fd2.conf\"" depend= "tcpip/afd" - sc create bareosfd3 binpath="\"C:\Program Files\Bareos\bareos-fd.exe\" /service -c \"C:\ProgramData\Bareos\bareos-fd3.conf\"" depend= "tcpip/afd" - \end{commands} - -This will create two |bareosFd| services, one with the name -bareosfd2 and the second with the name bareosfd3. - -The configuration files for the two services are -*bareos-fd.conf* and -*bareos-fd2.conf*, and need to have different network -settings. - -The services can be started by calling - -.. raw:: latex - - \begin{commands}{} - sc start bareosfd2 - \end{commands} - -and - -.. raw:: latex - - \begin{commands}{} - sc start bareosfd3 - \end{commands} - -Windows Specific Command Line Options -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -.. index:: - triple: General; Windows!File Daemon; Command Line Options - -These options are not normally seen or used by the user, and are -documented here only for information purposes. At the current time, to -change the default options, you must either manually run **Bareos** or -you must manually edit the system registry and modify the appropriate -entries. - -In order to avoid option clashes between the options necessary for -**Bareos** to run on Windows and the standard Bareos options, all -Windows specific options are signaled with a forward slash character -(/), while as usual, the standard Bareos options are signaled with a -minus (-), or a minus minus (``--``). All the standard Bareos options -can be used on the Windows version. In addition, the following Windows -only options are implemented: - -/service - Start Bareos as a service - -/run - Run the Bareos application - -/install - Install Bareos as a service in the system registry - -/remove - Uninstall Bareos from the system registry - -/about - Show the Bareos about dialogue box - -/status - Show the Bareos status dialogue box - -/events - Show the Bareos events dialogue box (not yet implemented) - -/kill - Stop any running **Bareos** - -/help - Show the Bareos help dialogue box - -It is important to note that under normal circumstances the user should -never need to use these options as they are normally handled by the -system automatically once Bareos is installed. However, you may note -these options in some of the .bat files that have been created for your -use. - -.. |image| image:: \idir win-install-1 - :width: 80.0% -.. |image| image:: \idir win-install-2 - :width: 80.0% -.. |image| image:: \idir win-install-3 - :width: 80.0% diff --git a/docs/manuals/en/new_main_reference/tex2rst.sh b/docs/manuals/en/new_main_reference/tex2rst.sh index 0f51da6952b..fe584337c46 100755 --- a/docs/manuals/en/new_main_reference/tex2rst.sh +++ b/docs/manuals/en/new_main_reference/tex2rst.sh @@ -1,5 +1,7 @@ #!/bin/bash +set -x + ORIGIN_DIR="../main/" TARGET_DIR="./source/" @@ -20,19 +22,83 @@ echo '===========================' ############################################################################### -for file in general.tex state.tex install.tex webui.tex update.tex \ - quickstart.tex tutorial.tex critical.tex configure.tex dirdconf.tex \ - storedconf.tex filedconf.tex messagesres.tex consoleconf.tex monitorconf.tex \ - bconsole.tex restore.tex disk.tex recycling.tex pools.tex autochangers.tex \ - tape-without-autochanger.tex spooling.tex migration.tex \ - always-incremental.tex basejob.tex plugin.tex win32.tex \ - client-initiated-connection.tex passiveclient.tex lanaddress.tex tls.tex \ - dataencryption.tex ndmp.tex catmaintenance.tex security.tex requirements.tex \ - supportedoses.tex programs.tex bootstrap.tex verify.tex \ - backward-compability.tex tables.tex howto.tex rescue.tex troubleshooting.tex \ - debug.tex releasenotes.tex license.tex; -do + + for file in \ + general.tex \ + state.tex \ + install.tex \ + webui.tex \ + update.tex \ + quickstart.tex \ + tutorial.tex \ + critical.tex \ + configure.tex \ + dirdconf.tex \ + storedconf.tex \ + filedconf.tex \ + messagesres.tex \ + consoleconf.tex \ + monitorconf.tex \ + bconsole.tex \ + restore.tex \ + disk.tex \ + recycling.tex \ + pools.tex \ + autochangers.tex \ + tape-without-autochanger.tex \ + spooling.tex \ + migration.tex \ + always-incremental.tex \ + basejob.tex \ + plugin.tex \ + win32.tex \ + client-initiated-connection.tex \ + passiveclient.tex \ + lanaddress.tex \ + tls.tex \ + dataencryption.tex \ + ndmp.tex \ + catmaintenance.tex \ + security.tex \ + requirements.tex \ + supportedoses.tex \ + programs.tex \ + bootstrap.tex \ + verify.tex \ + backward-compability.tex \ + tables.tex \ + howto.tex \ + rescue.tex \ + troubleshooting.tex \ + debug.tex \ + releasenotes.tex \ + license.tex \ +; do filebase=`basename $file .tex` echo ${file} - pandoc --verbose -f latex+raw_tex -t rst ${ORIGIN_DIR}${file} -o ${TARGET_DIR}${filebase}.rst + + cat ${ORIGIN_DIR}${file} \ + | perl -pe 's#\{bconfig\}#{verbatim}#g' \ + | perl -pe 's#\{commands\}#{verbatim}#g' \ + | perl -pe 's#\{commandOut\}#{verbatim}#g' \ + | perl -pe 's#\{bareosConfigResource\}#{verbatim}#g' \ + | perl -pe 's#\{bconsole\}#{verbatim}#g' \ + | perl -pe 's#\\variable\{\$#\\textbf\{\\\$#g' \ + | perl -pe 's#sec:#sec-#g' \ + | perl -pe 's#(DIST=.*?)_#\1\\_#g' \ + | perl -pe 's#\$CONFIGDIR#CONFIGDIR#g'\ + | perl -pe 's#\$COMPONENT#COMPONENT#g'\ + | perl -pe 's#\$RESOURCE#RESOURCE#g'\ + | perl -pe 's#\$NAME#NAME#g'\ + | perl -pe 's#\$PATH#PATH#g'\ + | perl -pe 's#\\hide\{\$\}##g' \ + | perl -pe 's#\\hypertarget#\textbf#g' \ + > ${TARGET_DIR}${file} + + echo + echo + diff --color -ruN ${ORIGIN_DIR}${file} ${TARGET_DIR}${file} + echo + echo + pandoc --verbose -f latex+raw_tex -t rst ${TARGET_DIR}${file} -o ${TARGET_DIR}${filebase}.rst || exit "could not convert file $file" done