.. _StoredConfChapter:

Storage Daemon Configuration
============================

.. index::
   single: Configuration
   single: Storage Daemon; Configuration
   single: Configuration; Storage Daemon

The |sd| configuration file has relatively few resource definitions. However, due to the great variation
in backup media and system capabilities, the storage daemon must be highly configurable. As a consequence,
there are quite a large number of directives in the Device Resource definition that allow you to define
all the characteristics of your Storage device (normally a tape drive). Fortunately, with modern
storage devices, the defaults are sufficient, 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:`Configuration <ConfigureChapter>` chapter of this manual.

The following Storage Resource definitions must be defined:

-  :ref:`Storage <StorageResourceStorage>` – to define the name of the Storage daemon.

-  :ref:`Director <StorageResourceDirector>` – to define the Director’s name and its access password.

-  :ref:`Device <StorageResourceDevice>` – to define the characteristics of your storage device (tape drive).

-  :ref:`Messages <MessagesChapter>` – to define where error and information messages are to be sent.

Following resources are optional:

-  :ref:`StorageResourceAutochanger` – to define Autochanger devices.

-  :ref:`StorageResourceNDMP` – to define the NDMP authentication context.

.. _StorageResourceStorage:

Storage Resource
----------------

.. index::
   single: Resource; Storage
   single: Storage; Resource

In general, the properties specified under the Storage resource define global properties of the
Storage daemon. Each Storage daemon configuration file must have one and only one Storage resource
definition.

.. include:: /include/autogenerated/bareos-sd-resource-storage-table.rst.inc

.. include:: /include/autogenerated/bareos-sd-resource-storage-description.rst.inc

The following is a typical Storage daemon storage resource definition.

.. code-block:: bareosconfig
   :caption: Storage daemon storage definition

   #
   # "Global" Storage daemon configuration specifications appear
   # under the Storage resource.
   #
   Storage {
     Name = "Storage daemon"
     Address = bareos-sd.example.com
   }

.. _StorageResourceDirector:

Director Resource
-----------------

.. index::
   single: Resource; Director
   single: 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 multiple Director resources. The Director Name and Password must
match the corresponding values in the Director’s configuration file.

.. include:: /include/autogenerated/bareos-sd-resource-director-table.rst.inc

.. include:: /include/autogenerated/bareos-sd-resource-director-description.rst.inc

The following is an example of a valid Director resource definition:

.. code-block:: bareosconfig
   :caption: Storage daemon Director definition

   Director {
     Name = MainDirector
     Password = my_secret_password
   }

.. _NDMPResource:

.. _StorageResourceNDMP:

NDMP Resource
-------------

.. index::
   single: Resource; NDMP
   single: NDMP; Resource

The NDMP Resource specifies the authentication details of each NDMP client. There may be multiple
NDMP resources for a single Storage daemon. In general, the properties specified within the NDMP
resource are specific to one client.

.. include:: /include/autogenerated/bareos-sd-resource-ndmp-table.rst.inc

.. include:: /include/autogenerated/bareos-sd-resource-ndmp-description.rst.inc


.. _StorageResourceDevice:

Device Resource
---------------

.. index.:
   single: Resource; Device
   single: 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 multiple Device resources for a single Storage daemon. In general,
the properties specified within the Device resource are specific to the Device.

.. include:: /include/autogenerated/bareos-sd-resource-device-table.rst.inc

.. include:: /include/autogenerated/bareos-sd-resource-device-description.rst.inc

.. _mountcodes:

Edit Codes for Mount and Unmount Directives
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. index::
   single: Edit Codes for Mount and Unmount Directives
   single: Mount and Unmount: use variables in directives

Before submitting the Mount Command, or Unmount Command directives to the operating system, Bareos
performs character substitution of the following characters:



::

       %% = %
       %a = Archive device name
       %e = erase (set if cannot mount and first part)
       %n = part number
       %m = mount point
       %v = last part name (i.e. filename)



Devices that require a mount (USB)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. index::
   single: Devices that require a mount (USB)

:config:option:`sd/device/RequiresMount`
   You must set this directive to :strong:`yes` for removable devices such as
   USB unless they are automounted, and to :strong:`no` for all other devices
   (tapes/files).  This directive indicates if the device requires to be
   mounted to be read, and if it must be written in a special way.  If it
   set, :config:option:`sd/device/MountPoint`\ ,
   :config:option:`sd/device/MountCommand`\  and
   :config:option:`sd/device/UnmountCommand`\
   directives must also be defined.

:config:option:`sd/device/MountPoint`
   Directory where the device can be mounted.

:config:option:`sd/device/MountCommand`
   Command that must be executed to mount the device. Before the command is
   executed, \%a is replaced with the Archive Device, and \%m with the Mount
   Point.

   Most frequently, you will define it as follows:

   .. code-block:: bareosconfig

      Mount Command = "/bin/mount -t iso9660 -o ro %a %m"


   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:

   .. code-block:: bareosconfig

      Mount Command = "/usr/local/bin/mymount"

   Where that script contains:

   .. code-block:: sh

      #!/bin/sh
      ndasadmin enable -s 1 -o w
      sleep 2
      mount /dev/ndas-00323794-0p1 /backup


   Similar consideration should be given to all other Command parameters.

:config:option:`sd/device/UnmountCommand`
   Command that must be executed to unmount the device. Before the command  is
   executed, \%a is replaced with the Archive Device, and \%m with the  Mount
   Point.

   Most frequently, you will define it as follows:

   .. code-block:: bareosconfig

      Unmount Command = "/bin/umount %m"


   If you need to specify multiple commands, create a shell script.


.. _AutochangerRes:

.. _StorageResourceAutochanger:

Autochanger Resource
--------------------

.. index::
   single: Autochanger Resource
   single: Resource; Autochanger

The Autochanger resource supports single or multiple drive autochangers by grouping one or more
Device resources into one unit called an autochanger in Bareos (often referred to as a "tape library"
by autochanger manufacturers).

.. include:: /include/autogenerated/bareos-sd-resource-autochanger-table.rst.inc

.. include:: /include/autogenerated/bareos-sd-resource-autochanger-description.rst.inc

The following is an example of a valid Autochanger resource definition:

.. code-block:: bareosconfig
   :caption: Autochanger Configuration Example

   Autochanger {
     Name = "LTO8-changer"
     Device = LTO8-1, LTO8-2, LTO8-3
     Changer Device = /dev/sg0
     Changer Command = "/usr/lib/bareos/scripts/mtx-changer %c %o %S %a %d"
   }
   Device {
     Name = "LTO8-1"
     Drive Index = 0
     Autochanger = yes
     ...
   }
   Device {
     Name = "LTO8-2"
     Drive Index = 1
     Autochanger = yes
     ...
   Device {
     Name = "LTO8-3"
     Drive Index = 2
     Autochanger = yes
     Autoselect = no
     ...
   }

Please note that it is important to include the :config:option:`sd/device/Autochanger = yes`\  directive
in each device definition that belongs to an Autochanger. A device definition should not belong to more
than one Autochanger resource.

Also, your :config:option:`dir/storage/Device`\  must refer to the Autochanger’s resource name rather
than a name of one of the Devices.

For details refer to the :ref:`AutochangersChapter` chapter.

.. _StorageResourceMultipliedDevice:

Multiplied Device
-----------------

The Multiplied Device feature can be used when multiple identical devices are needed.
In this case the :config:option:`sd/device/Count` can be added to the regarding Device resource.

Note that this option only has an effect if the assigned value is greater than 1.

When the configuration is loaded, the |bareosSD| will automatically multiply this device :config:option:`sd/device/Count` + 1 times adding suffixes to the names starting from "0000". 

The multiplied device with the suffix "0000" serves a special purpose, it is implicitly assigned :config:option:`sd/device/AutoSelect` to "no".
All other multiplied devices are an exact copy of the original device.

Additionally, specifying :config:option:`sd/device/Count` also implicitly creates an autochanger with the same name as the original device with all devices listed in that autochanger.
This only happens if the original device is not already associated to another autochanger.

.. code-block:: bareosconfig
   :caption: bareos-sd.d/device/multiplied_device.conf

   Device {
     Count = 3 # create devices MultiFileStorage0000, ..., MultiFileStorage0003

     Name = MultiFileStorage
     Description = "File device. Will be multiplied 4 times"
     Media Type = File
     Archive Device = /home/testuser/multiplied-device-test/storage
     LabelMedia = yes
     Random Access = yes
     AutomaticMount = yes
     RemovableMedia = no
     AlwaysOpen = no
   }

In the |bareosDir| any of the Multiplied Devices can be referred to using their numbered names.

However, in the autochanger resource of the |bareosSD| the original name of the initial
Multiplied Device Resource can be used.

You do not have to explicitly create an autochanger resource in order to use the multiplied devices.
However, if you decide to do so, for additional customizations, this could be done as follows.

.. code-block:: bareosconfig
   :caption: bareos-sd.d/autochanger/autochanger.conf

   Autochanger {
     Name = "virtual-autochanger"

     # list here only the name of the initial multiplied device resource
     Device = MultiFileStorage

     Changer Device = /dev/null
     Changer Command = ""
   }

When the configuration is exported, again only the name of the initial Multiplied Device Resource will be printed.

The Multiplied Device feature can be used when multiple identical devices are needed, e.g.
when you want to run multiple jobs at once to the same storage :config:option:`sd/device/ArchiveDevice` location.

Since the :config:option:`sd/device/Count` directive creates an implicit autochanger of the same name as the device,
you don't have to touch your storage configuration in the director.

.. code-block:: bareosconfig
   :caption: bareos-dir.d/storage/File.conf
   
   Storage {
      Name = File
      Address = @hostname@
      Password = "@sd_password@"
      Device = MultiFileStorage
      Media Type = File
      Maximum Concurrent Jobs = 10
   }

Just make sure that :config:option:`dir/storage/MaximumConcurrentJobs` is specified, otherwise jobs will still not run in parallel.
We advise to set it to the same value as the :config:option:`sd/device/Count` used.

.. _MessagesResource1:

Messages Resource
-----------------

.. index::
   single: Resource; Messages
   single: Messages; Resource

For a description of the Messages Resource, please see the :ref:`MessagesChapter` chapter of this manual.
