From b69a2ec0a6db2199d8a463980fac16c8bf02264f Mon Sep 17 00:00:00 2001 From: Joerg Steffens Date: Thu, 22 Aug 2019 17:11:04 +0200 Subject: [PATCH] docs: fix some formatting --- .../source/Appendix/BareosPrograms.rst | 27 +++++++++---------- docs/manuals/source/Appendix/Debugging.rst | 24 ++++++++--------- .../Appendix/DisasterRecoveryUsingBareos.rst | 15 +++-------- .../manuals/source/Configuration/Director.rst | 2 +- .../SpecificFormatting.rst | 3 +++ .../example/code-block-shell-session.rst.inc | 2 +- .../IntroductionAndTutorial/Tutorial.rst | 4 +-- .../UpdatingBareos.rst | 17 ++++++------ .../TasksAndConcepts/AutochangerSupport.rst | 10 ++++--- .../NdmpBackupsWithBareos.rst | 3 ++- .../source/TasksAndConcepts/Plugins.rst | 4 +-- 11 files changed, 53 insertions(+), 58 deletions(-) diff --git a/docs/manuals/source/Appendix/BareosPrograms.rst b/docs/manuals/source/Appendix/BareosPrograms.rst index f6f1862f77c..d1855d0905c 100644 --- a/docs/manuals/source/Appendix/BareosPrograms.rst +++ b/docs/manuals/source/Appendix/BareosPrograms.rst @@ -285,7 +285,7 @@ For example: .. code-block:: shell-session - bls FileStorage -V Full1 + root@host:~# 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 @@ -308,7 +308,7 @@ To retrieve information, about how a file is stored on the volume, you can use : .. code-block:: shell-session - bls FileStorage -V TestVolume001 -v + root@host:~# 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 @@ -339,7 +339,7 @@ Using the :strong:`-L` the label information of a Volume is shown: .. code-block:: shell-session :caption: bls: show volume label - bls -L /var/lib/bareos/storage/testvol + root@host:~# 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). @@ -367,7 +367,7 @@ If you are listing a Volume to determine what Jobs to restore, normally the :str .. code-block:: shell-session :caption: bls: list jobs - bls /var/lib/bareos/storage/testvol -j + root@host:~# 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 @@ -402,7 +402,7 @@ Normally, except for debugging purposes, you will not need to list Bareos blocks .. code-block:: shell-session - bls -k /tmp/File002 + root@host:~# bls -k /tmp/File002 bls: butil.c:148 Using device: /tmp Block: 1 size=64512 Block: 2 size=64512 @@ -416,7 +416,7 @@ By adding the :strong:`-v` option, you can get more information, which can be us .. code-block:: shell-session - bls -k -v /tmp/File002 + root@host:~# 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 @@ -434,7 +434,7 @@ If you want to know even more, add a second :strong:`-v` to the command line to .. code-block:: shell-session - bls -k -vv /tmp/File002 + root@host:~# 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 @@ -559,20 +559,19 @@ Extracting Under Windows :index:`\ `\ +.. warning:: + If you use :command:`bextract` under Windows, the ordering of the parameters is essential. - .. 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 :file:`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: -.. code-block:: shell-session +.. code-block:: doscon :caption: Call of bextract - C:\Program Files\Bareos .\bextract.exe -c "C:\ProgrammData\Bareos\bareos-sd.conf" -V + C:\Program Files\Bareos> .\bextract.exe -c "C:\ProgrammData\Bareos\bareos-sd.conf" -V 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: @@ -582,10 +581,10 @@ If you want to use exclude or include files you need to write them like you do o /Program Files/Bareos/bareos-dir.exe /ProgramData/ -.. code-block:: shell-session +.. code-block:: doscon :caption: Call bextract with exclude list - C:\Program Files\Bareos .\bextract.exe -e exclude.list -c "C:\ProgrammData\Bareos\bareos-sd.conf" -V + C:\Program Files\Bareos> .\bextract.exe -e exclude.list -c "C:\ProgrammData\Bareos\bareos-sd.conf" -V .. _bscan: diff --git a/docs/manuals/source/Appendix/Debugging.rst b/docs/manuals/source/Appendix/Debugging.rst index 5260f340968..09020f1d265 100644 --- a/docs/manuals/source/Appendix/Debugging.rst +++ b/docs/manuals/source/Appendix/Debugging.rst @@ -30,7 +30,7 @@ For this to work, you need to ensure that a few things are setup correctly on yo .. code-block:: shell-session :caption: 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 + root@host:~# test -e /proc/sys/kernel/yama/ptrace_scope && echo 0 > /proc/sys/kernel/yama/ptrace_scope 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. @@ -44,7 +44,7 @@ To "manually" test the traceback feature, you simply start Bareos then obtain th .. code-block:: shell-session :caption: get the process ID of a running Bareos daemon - ps fax | grep bareos-dir + root@host:~# ps fax | grep bareos-dir 2103 ? S 0:00 /usr/sbin/bareos-dir 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: @@ -52,14 +52,15 @@ which in this case is 2103. Then while Bareos is running, you call the program g .. code-block:: shell-session :caption: get traceback of running Bareos director daemon - btraceback /usr/sbin/bareos-dir 2103 + root@host:~# btraceback /usr/sbin/bareos-dir 2103 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:`\ `\ 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 :file:`btraceback.gdb` script to have appropriate commands for your debugger. +It should be possible to produce a similar traceback on systems other than Linux, either using :command:`gdb` or some other debugger. +:index:`Solaris `\ 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 :file:`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 @@ -74,10 +75,11 @@ If for some reason you cannot get the automatic traceback, or if you want to int .. code-block:: shell-session :caption: run the Bareos Storage daemon in the debugger - gdb --args /usr/sbin/bareos-sd -f -s -d 200 - (gdb) run + root@host:~# su - bareos -s /bin/bash + bareos@host:~# gdb --args /usr/sbin/bareos-sd -f -s -d 200 + (gdb) run - Parameter: + Bareos Parameter: -f foreground @@ -99,12 +101,8 @@ If for some reason you cannot get the automatic traceback, or if you want to int #. To get a general traceback of all threads, issue the following command: .. code-block:: shell-session - :caption: run the Bareos Storage daemon in the debugger + :caption: Bareos Storage daemon in a debugger session - (gdb) thread apply all bt + (gdb) thread apply all bt After that you can issue any debugging command. - - - - diff --git a/docs/manuals/source/Appendix/DisasterRecoveryUsingBareos.rst b/docs/manuals/source/Appendix/DisasterRecoveryUsingBareos.rst index a33a488976b..c456d1c4ab2 100644 --- a/docs/manuals/source/Appendix/DisasterRecoveryUsingBareos.rst +++ b/docs/manuals/source/Appendix/DisasterRecoveryUsingBareos.rst @@ -113,7 +113,7 @@ If you have installed and configured ReaR on your system, type .. code-block:: shell-session :caption: Create Rescue Image - rear -v mkrescue + root@host:~# rear -v mkrescue 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. @@ -135,7 +135,7 @@ In case, you want to recover your system, boot it using the generated ReaR recov .. code-block:: shell-session :caption: Restore your system using Rear and Bareos - rear recover + root@host:~# rear recover 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 :file:`/mnt/local` directory. When you are done< with the 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. @@ -143,18 +143,13 @@ ReaR will restore your bootloader. Recovery is complete. - - +.. _section-RestoreServer: Restoring a Bareos Server ------------------------- :index:`\ `\ -.. _section-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. @@ -186,7 +181,3 @@ The second suggestion is probably a much simpler solution, and one I have done m - 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:`section-RestoreCatalog` chapter. - - - - diff --git a/docs/manuals/source/Configuration/Director.rst b/docs/manuals/source/Configuration/Director.rst index 3afddff8d3f..a10772fceac 100644 --- a/docs/manuals/source/Configuration/Director.rst +++ b/docs/manuals/source/Configuration/Director.rst @@ -1572,7 +1572,7 @@ Now lets take a slight variation on the above and suppose you want to save all y .. code-block:: shell-session :caption: df - df + user@host:~$ df Filesystem 1k-blocks Used Available Use% Mounted on /dev/hda5 5044156 439232 4348692 10% / /dev/hda1 62193 4935 54047 9% /boot diff --git a/docs/manuals/source/DocumentationStyleGuide/SpecificFormatting.rst b/docs/manuals/source/DocumentationStyleGuide/SpecificFormatting.rst index 9d9c5addf4f..23710c6e209 100644 --- a/docs/manuals/source/DocumentationStyleGuide/SpecificFormatting.rst +++ b/docs/manuals/source/DocumentationStyleGuide/SpecificFormatting.rst @@ -82,6 +82,9 @@ Unix Commmand Prompt Unix command prompts should look identical thoughout the documentation. Normally, we assume a root console on Linux: ``root@host:~#``\ . Mind a space after the ``#``. +If no specific user is required, we use the username **user**. +The prompt of a no-root user looks like: ``user@host:~$``\ . + The hostname **host** is used, if it is a generic host. If the command runs on a specific Bareos server, the specific host name from :ref:`DocumentationStyleGuide/BareosSpecificFormatting/BareosHostNames:Bareos Host Names` should be used. diff --git a/docs/manuals/source/DocumentationStyleGuide/example/code-block-shell-session.rst.inc b/docs/manuals/source/DocumentationStyleGuide/example/code-block-shell-session.rst.inc index 6ee02349248..06b5c086207 100644 --- a/docs/manuals/source/DocumentationStyleGuide/example/code-block-shell-session.rst.inc +++ b/docs/manuals/source/DocumentationStyleGuide/example/code-block-shell-session.rst.inc @@ -9,6 +9,6 @@ root@host:/etc/bareos# cd root@host:~# ssh root@bareos-dir.example.com root@bareos-dir:~# su - postgres - postgres@bareos-dir:~> psql bareos + postgres@bareos-dir:~$ psql bareos Welcome to psql 8.3.23, the PostgreSQL interactive terminal. ... diff --git a/docs/manuals/source/IntroductionAndTutorial/Tutorial.rst b/docs/manuals/source/IntroductionAndTutorial/Tutorial.rst index 8a882f65ef5..59b3b729222 100644 --- a/docs/manuals/source/IntroductionAndTutorial/Tutorial.rst +++ b/docs/manuals/source/IntroductionAndTutorial/Tutorial.rst @@ -65,7 +65,7 @@ The :command:`bconsole` runs the Bareos Console program, which connects to the | .. code-block:: shell-session :caption: bconsole - bconsole + root@host:~# bconsole Connecting to Director bareos:9101 Enter a period to cancel a command. * @@ -562,7 +562,7 @@ After exiting the Console program, you can examine the files in :file:`/tmp/bare .. code-block:: shell-session :caption: remove restore directory - rm -rf /tmp/bareos-restore + root@host:~# rm -rf /tmp/bareos-restore Quitting the Console Program ---------------------------- diff --git a/docs/manuals/source/IntroductionAndTutorial/UpdatingBareos.rst b/docs/manuals/source/IntroductionAndTutorial/UpdatingBareos.rst index 9c5c8f5b3f3..d68e11b1443 100644 --- a/docs/manuals/source/IntroductionAndTutorial/UpdatingBareos.rst +++ b/docs/manuals/source/IntroductionAndTutorial/UpdatingBareos.rst @@ -26,9 +26,10 @@ Sometimes improvements in Bareos make it necessary to update the database scheme - .. warning:: +.. warning:: + + If the Bareos catalog database does not have the current schema, the Bareos Director refuses to start. - 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 :file:`/var/log/bareos/bareos.log`. @@ -36,24 +37,24 @@ Take a look into the :ref:`Release Notes ` to see which Bareos upd - .. warning:: +.. warning:: - Especially the upgrade to Bareos >= 17.2.0 restructures the **File** database table. In larger installations this is very time consuming and temporarily doubles the amount of required database disk space. + Especially the upgrade to Bareos >= 17.2.0 restructures the **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 :sinceVersion:`14.2.0: dbconfig-common (Debian)` the Debian (and Ubuntu) based packages support the **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. +.. 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 .. code-block:: shell-session - su - postgres -c /usr/lib/bareos/scripts/grant_bareos_privileges + root@host:~# su - postgres -c /usr/lib/bareos/scripts/grant_bareos_privileges + For details see :ref:`section-dbconfig`. diff --git a/docs/manuals/source/TasksAndConcepts/AutochangerSupport.rst b/docs/manuals/source/TasksAndConcepts/AutochangerSupport.rst index 424399df476..b91ab08e547 100644 --- a/docs/manuals/source/TasksAndConcepts/AutochangerSupport.rst +++ b/docs/manuals/source/TasksAndConcepts/AutochangerSupport.rst @@ -623,12 +623,13 @@ Direct access to Volumes with with non-default block sizes To be able to read a volume written with an arbitrary block size, you need to set the :config:option:`sd/device/LabelBlockSize`\ (to be able to to read the label block) and the :config:option:`sd/device/MaximumBlockSize`\ (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 with another blocksize than the ``DEFAULT_BLOCK_SIZE``\ (63k), but with the default label block size of 63k: +Example using :command:`bls` with a tape that was written with another blocksize than the ``DEFAULT_BLOCK_SIZE``\ (63k), +but with the default label block size of 63k: .. code-block:: shell-session :caption: bls with non-default block size - bls FC-Drive-1 -V A00007L4 + root@host:~# 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. @@ -643,7 +644,7 @@ As can be seen, :command:`bls` manages to read the label block as it knows what .. code-block:: shell-session :caption: dmesg - dmesg + root@host:~# dmesg [...] st2: Failed to read 131072 byte block with 64512 byte transfer. [...] @@ -673,13 +674,14 @@ Now we can call bls again, and everything works as expected: .. code-block:: shell-session :caption: bls with non-default block size - bls FC-Drive-1 -V A00007L4 + root@host:~# 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/manuals/source/TasksAndConcepts/NdmpBackupsWithBareos.rst b/docs/manuals/source/TasksAndConcepts/NdmpBackupsWithBareos.rst index 1a8bb6745c5..47adcbac042 100644 --- a/docs/manuals/source/TasksAndConcepts/NdmpBackupsWithBareos.rst +++ b/docs/manuals/source/TasksAndConcepts/NdmpBackupsWithBareos.rst @@ -372,10 +372,11 @@ Now restart the |sd|. If everything is correct, the |sd| starts and listens now .. code-block:: shell-session - netstat -lntp | grep bareos-sd + root@host:~# netstat -lntp | grep bareos-sd tcp 0 0 0.0.0.0:9103 0.0.0.0:* LISTEN 10661/bareos-sd tcp 0 0 0.0.0.0:10000 0.0.0.0:* LISTEN 10661/bareos-sd + Bareos Director: Configure a Paired Storage ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/manuals/source/TasksAndConcepts/Plugins.rst b/docs/manuals/source/TasksAndConcepts/Plugins.rst index 6d1e6acfb04..c36e5b39197 100644 --- a/docs/manuals/source/TasksAndConcepts/Plugins.rst +++ b/docs/manuals/source/TasksAndConcepts/Plugins.rst @@ -406,7 +406,7 @@ As of http://kb.vmware.com/kb/2075984 manually enabling CBT is currently not wor .. code-block:: shell-session :caption: usage of vmware\_cbt\_tool.py - # vmware_cbt_tool.py --help + user@host:~$ 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] [--vm-uuid VM_UUID] [--enablecbt] [--disablecbt] @@ -444,7 +444,7 @@ For the above configuration example, the command to enable CBT would be .. code-block:: shell-session :caption: 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 + user@host:~$ vmware_cbt_tool.py -s vcenter.example.org -u bakadm@vsphere.local -p Bak.Adm-1234 -d mydc1 -f /webservers -v websrv1 --enablecbt Note: CBT does not work if the virtual hardware version is 6 or earlier.