Ceph/GlusterFS backends: change in configuration

bareos-15.2 uses Device Options instead of misusinng Archive Device to
define Ceph and GlusterFS storage.

manuals/en/main/bareos-sd-resource-device-definitions.tex

@@ -55,11 +55,11 @@
 
 \defDirective{Sd}{Device}{Archive Device}{}{}{%
 Specifies where to read and write the backup data.
-The type of the Archive Device can be specified by the {\bf Device Type} directive.
+The type of the Archive Device can be specified by the \linkResourceDirective{Sd}{Device}{Device Type} directive.
 If Device Type is not specified, Bareos tries to guess the Device Type
 accordingly to the type of the specified Archive Device file type.
 
-There are three different types that are supported:
+There are different types that are supported:
 \begin{description}
     \item[device] Usually the device file
 name of a removable storage device (tape drive),  for example \path|/dev/nst0|
@@ -82,13 +82,15 @@
 A FIFO is a special kind of file that connects two programs
 via kernel memory. If a FIFO device is specified  for a backup operation, you
 must have a program that reads what Bareos  writes into the FIFO. When the
-Storage daemon starts the job, it  will wait for {\bf MaximumOpenWait} seconds
+Storage daemon starts the job,
+it  will wait for \linkResourceDirective{Sd}{Device}{Maximum Open Wait} seconds
 for the read program to start reading, and then time it out and  terminate
 the job. As a consequence, it is best to start the read  program at the
-beginning of the job perhaps with the {\bf RunBeforeJob}  directive. For this
-kind of device, you never want to specify  {\bf AlwaysOpen}, because you want
-the Storage daemon to open it only  when a job starts, so you must explicitly
-set it to {\bf No}.  Since a FIFO is a one way device, Bareos will not attempt
+beginning of the job perhaps with the  \linkResourceDirective{Dir}{Job}{Run Before Job} directive.
+For this kind of device,
+you always want to specify \linkResourceDirective{Sd}{Device}{Always Open} = no,
+because you want the Storage daemon to open it only  when a job starts.
+Since a FIFO is a one way device, Bareos will not attempt
 to read  a label of a FIFO device, but will simply write on it. To create a
 FIFO Volume in the catalog, use the {\bf add} command rather than the {\bf
 label} command to avoid attempting to write a label.
@@ -97,32 +99,23 @@
 
 During a restore operation, if the Archive Device is a FIFO, Bareos  will
 attempt to read from the FIFO, so you must have an external program  that
-writes into the FIFO. Bareos will wait {\bf MaximumOpenWait} seconds  for the
+writes into the FIFO. 
+Bareos will wait \linkResourceDirective{Sd}{Device}{Maximum Open Wait} seconds  for the
 program to begin writing and will then time it out and  terminate the job. As
-noted above, you may use the {\bf RunBeforeJob}  to start the writer program
+noted above, you may use the \linkResourceDirective{Dir}{Job}{Run Before Job} to start the writer program
 at the beginning of the job.
 
 A FIFO device can also be used to test your configuration, see the \ilink{Howto section}{TestUsingFifoDevice}.
 
     \item[GlusterFS Storage] \label{GlusterArchiveType}
-    A GlusterFS Storage can be used as Storage backend of Bareos.
-    Prerequistes are a working GlusterFS storage system and the package \package{bareos-storage-glusterfs}.
-    See \url{//http://www.gluster.org/} for more information regarding GlusterFS installation and configuration.
-    You can use following snippet to configure it as storage device:
-    \bconfigInput{config/SdDeviceArchiveDevice2.conf}
-    Adapt server and volume name to your environment.
-
-    \sinceVersion{sd}{GlusterFS Storage}{14.2.2}
-
+	don't use this directive,
+	but only \linkResourceDirective{Sd}{Device}{Device Type} and \linkResourceDirective{Sd}{Device}{Device Options}
+	(this behavior have changed with \sinceVersion{Sd}{Device Options}{15.2.0}).
+
    \item[Ceph Object Store] \label{CephArchiveType}
-   Here you configure the Ceph object store, which is accessed by the SD using the Rados library. Prerequistes are a
-   working Ceph object store and the package \package{bareos-storage-ceph}. See \url{http://ceph.com} for more information regarding Ceph installation and configuration.
-   Assuming that you have an object store with name \file{your_bareos_store}
-   and your Ceph access is configured in \file{/etc/ceph/ceph.conf}, you can use following snippet to configure it as storage device:
-   \bconfigInput{config/SdDeviceArchiveDevice3.conf}
-
-   \sinceVersion{sd}{Ceph Storage}{14.2.2}
-
+	don't use this directive,
+	but only \linkResourceDirective{Sd}{Device}{Device Type} and \linkResourceDirective{Sd}{Device}{Device Options}.
+	(this behavior have changed with \sinceVersion{Sd}{Device Options}{15.2.0}).
 \end{description}
 }
 
@@ -337,32 +330,61 @@
 \defDirective{Sd}{Device}{Description}{}{}{%
 }
 
+\defDirective{Sd}{Device}{Device Options}{}{}{%
+Some \linkResourceDirective{Sd}{Device}{Device Type} require additional configuration.
+This can be specified in this directive, e.g. for
+\begin{description}
+    \item[GlusterFS Storage]
+	A GlusterFS Storage can be used as Storage backend of Bareos.
+	Prerequistes are a working GlusterFS storage system and the package \package{bareos-storage-glusterfs}.
+	See \url{http://www.gluster.org/} for more information regarding GlusterFS installation and configuration.
+	You can use following snippet to configure it as storage device:
+	\bconfigInput{config/SdDeviceDeviceOptionsGfapi1.conf}
+	Adapt server and volume name to your environment.
+
+	\sinceVersion{sd}{GlusterFS Storage}{15.2.0}
+
+   \item[Ceph Object Store]
+	Here you configure the Ceph object store, which is accessed by the SD using the Rados library. Prerequistes are a
+	working Ceph object store and the package \package{bareos-storage-ceph}. See \url{http://ceph.com} for more information regarding Ceph installation and configuration.
+	Assuming that you have an object store with name \file{poolname}
+	and your Ceph access is configured in \file{/etc/ceph/ceph.conf},
+	you can use following snippet to configure it as storage device:
+	\bconfigInput{config/SdDeviceDeviceOptionsRados1.conf}
+
+	\sinceVersion{sd}{Ceph Storage}{15.2.0}
+\end{description}
+
+Before the Device Options directive have been introduced,
+these options have to be configured in the \linkResourceDirective{Sd}{Device}{Archive Device} directive.
+This behavior have changed with \sinceVersion{sd}{Device Options}{15.2.0}.
+}
+
+
 \defDirective{Sd}{Device}{Device Type}{}{}{%
-The Device Type specification allows you to explicitly tell Bareos
-what kind of device you are defining. It the {\bf type-specification}
-may be one of the following:
+The Device Type specification allows you to explicitly define the kind of device you want to use.
+It may be one of the following:
 \begin{description}
-\item [Tape]
-  The device is a tape device and thus is sequential access. Tape devices
+\item [Tape] is used to access tape device and thus has sequential access. Tape devices
   are controlled using ioctl() calls.
 \item [File]
-  Tells Bareos that the device is a file. It may either be a
+  tells Bareos that the device is a file. It may either be a
   file defined on fixed medium or a removable filesystem such as
   USB.  All files must be random access devices.
-\item [Fifo]
-  The device is a first-in-first-out sequential access read-only
+\item [Fifo] is a first-in-first-out sequential access read-only
   or write-only device.
-\item [GFAPI]
-  The gfapi device is used to access a GlusterFS storage.
+\item [GFAPI] is used to access a GlusterFS storage.
+  It must be configured using \linkResourceDirective{Sd}{Device}{Device Options}.
   \sinceVersion{sd}{GlusterFS (gfapi)}{14.2.2}
-\item [Rados]
-  The Rados device is used to access a Ceph object store.
+\item [Rados] is used to access a Ceph object store.
+  It must be configured using \linkResourceDirective{Sd}{Device}{Device Options}.
   \sinceVersion{sd}{Ceph (Rados)}{14.2.2}
 \end{description}
 
-The Device Type directive is not required, and if not specified, Bareos
-will attempt to guess what kind of device has been specified using the
-Archive Device specification supplied. There are several advantages to
+The Device Type directive is not required in all cases.
+If it is not specified, Bareos will attempt to guess what kind of device has been specified using the
+\linkResourceDirective{Sd}{Device}{Archive Device} specification supplied.
+There are several advantages to
 explicitly specifying the Device Type. First, on some systems, block and
 character devices have the same type.
 Secondly, if you explicitly specify the Device Type, the mount point
@@ -372,6 +394,7 @@
 must exist when the Storage daemon starts.
 }
 
+
 \defDirective{Sd}{Device}{Diagnostic Device}{}{}{%
 }
 

manuals/en/main/bareos.sty

@@ -108,6 +108,11 @@
 \url{https://download.bareos.com/bareos/release/#1/}%
 }
 
+% handle links to the Bareos Developer Guide via own commands
+% to keep track of cross links
+\newcommand{\bareosDeveloperGuideDotCommands}{%
+\url{http://doc.bareos.org/master/html/bareos-developer-guide.html\#dot-commands}%
+}
 
 %
 % special characters

manuals/en/main/bconsole.tex

@@ -1645,31 +1645,7 @@ \subsection{Special dot (.) 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.
-The following
-is the list of dot commands:
-
-\footnotesize
-\begin{verbatim}
-.backups job=xxx      list backups for specified job
-.clients              list all client names
-.defaults client=xxx fileset=yyy  list defaults for specified client
-.die                  cause the Director to segment fault (for debugging)
-.dir                  when in tree mode prints the equivalent to the dir command,
-                        but with fields separated by commas rather than spaces.
-.exit                 quit
-.filesets             list all fileset names
-.help                 help command output
-.jobs                 list all job names
-.levels               list all levels
-.messages             get quick messages
-.msgs                 return any queued messages
-.pools                list all pool names
-.quit                 quit
-.status               get status output
-.storage              return storage resource names
-.types                list job types
-\end{verbatim}
-\normalsize
+For details, see \bareosDeveloperGuideDotCommands.
 
 
 \subsection{Special At (@) Commands}

manuals/en/main/config/SdDeviceArchiveDevice2.conf → manuals/en/main/config/SdDeviceDeviceOptionsGfapi1.conf

@@ -1,6 +1,7 @@
 Device {
   Name = GlusterStorage
-  Archive Device = gluster://server.example.com/volumename/bareos
+  Archive Device = "Gluster Device"
+  Device Options = "uri=gluster://server.example.com/volumename/bareos"
   Device Type = gfapi
   Media Type = GlusterFile
   Label Media = yes

manuals/en/main/config/SdDeviceDeviceOptionsRados1.conf

@@ -0,0 +1,12 @@
+Device {
+  Name = RadosStorage
+  Archive Device = "Rados Device"
+  Device Options = "conffile=/etc/ceph/ceph.conf,poolname=poolname"
+  Device Type = rados
+  Media Type = RadosFile
+  Label Media = yes
+  Random Access = yes
+  Automatic Mount = yes
+  Removable Media = no
+  Always Open = no
+}

manuals/en/main/releasenotes.tex

@@ -30,6 +30,14 @@ \section*{Bareos-15.2}
 
 \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 \parameter{yes} to \parameter{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 = <text>
+% #    Device Options = "conffile=/etc/ceph/ceph.conf,poolname=poolname"
 \end{itemize}
 
 }