.. _ConsoleConfChapter:

Console Configuration
=====================

.. index::
   single: Configuration; Console
   single: 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 password. It simply contains the information necessary
to contact the 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:`Configuration <ConfigureChapter>` chapter of this
manual.

The following Console Resource definition must be defined:

.. _ConsoleResourceDirector:

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

.. index::
   single: Director Resource
   single: Resource; Director

The Director resource defines the attributes of the Director running on the network. You may have
multiple Director resource specifications in a single Console configuration file. If you have more
than one, you will be prompted to choose one when you start the Console program.

.. include:: /include/autogenerated/bconsole-resource-director-table.rst.inc

.. include:: /include/autogenerated/bconsole-resource-director-description.rst.inc

An actual example might be:



.. code-block:: bareosconfig
   :caption: bconsole: Director resource example

   Director {
     Name = bareos-dir
     address = bareos-dir.example.com
     password = "PASSWORD"
   }





.. _ConsoleResourceConsole:

Console Resource
----------------

.. index::
   single: Console Resource
   single: 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 **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.

-  The second type of console is a "named" or "restricted" console defined within a Console resource
   in both the Director’s configuration file and in the Console’s configuration file. Both the names
   and the passwords in these two entries must match much as is the case for Client programs.

   This second type of console begins with absolutely no privileges except those explicitly
   specified in the Director’s Console resource. Note, the definition of what these restricted
   consoles can do is determined by the Director’s conf file.

   Thus you may define within the Director’s conf file multiple Consoles with different names and
   passwords, sort of like multiple users, each with different privileges. As a default, these
   consoles can do absolutely nothing – no commands what so ever. You give them privileges or rather
   access to commands and resources by specifying access control lists in the Director’s Console
   resource. This gives the administrator fine grained control over what particular consoles
   (or users) can do.

-  The third type of console is similar to the above mentioned restricted 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 = directive, is the same as a Client name, the user of that
   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 their current IP address.

The Console resource is optional and need not be specified. However, if it is specified, you can use
**ACLs** (Access Control Lists) in the Director’s configuration file to restrict the particular
console (or user) to see only information pertaining to his jobs or client machine.

You may specify as many Console resources in the console’s conf file. If you do so, generally the
first Console resource will be used. However, if you have multiple Director resources (i.e. you want
to connect to different directors), you can bind one of your Console resources to a particular
Director resource, and thus when you choose a particular Director, the appropriate Console
configuration resource will be used. See the "Director" directive in the Console resource described
below for more information.

Note, the Console resource is optional, but can be useful for restricted consoles as noted above.

.. include:: /include/autogenerated/bconsole-resource-console-table.rst.inc

.. include:: /include/autogenerated/bconsole-resource-console-description.rst.inc

Example Console Configuration File
----------------------------------

.. index::
   single: Configuration; bconsole


A Console configuration file might look like this:

.. code-block:: bareosconfig
   :caption: 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
|dir| named **bareos.example.com-dir** at the network address :strong:`bareos.example.com` and
authenticate to the admin console using the password **PASSWORD**.

.. _section-ConsoleAccessExample:

.. _section-named-console:

Using Named Consoles
~~~~~~~~~~~~~~~~~~~~

The following configuration files were supplied by Phil Stracchino.

To use named consoles from :command:`bconsole`, use a :file:`bconsole.conf` configuration file
like this:

.. code-block:: bareosconfig
   :caption: bconsole: restricted-user

   Director {
      Name = bareos-dir
      Address = myserver
      Password = "XXXXXXXXXXX"
   }

   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 :strong:`restricted-user`. Then in the Director configuration (not
directly accessible by the user), we define:

.. code-block:: bareosconfig
   :caption: bareos-dir.d/console/restricted-user.conf

   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
:config:option:`Dir/Console = restricted-user`\  and he will only be able to see or access
a Job with the name :config:option:`Dir/Job = Restricted Client Save`\ ,
a Client with the name :config:option:`Dir/Client = restricted-client`\ ,
a storage device :config:option:`Dir/Storage = main-storage`\ ,
any Schedule or Pool, a FileSet named :config:option:`Dir/FileSet = Restricted Client's FileSet`\ ,
a Catalog named :config:option:`Dir/Catalog = MyCatalog`\  and the only command he can use in the
Console is the :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 :strong:`Acl` data type description.

The following is an example of a :file:`bconsole.conf` file that can access several Directors and
has different Consoles depending on the Director:

.. code-block:: bareosconfig
   :caption: 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.
   }

   Console {
      Name = restricted-user
      Password = "RUPASSWORD"
      Director = bareos-dir
   }

   Console {
      Name = restricted-user2
      Password = "OTHERPASSWORD"
      Director = SecondDirector
   }

The second Director referenced at :config:option:`Dir/Director = secondserver`\  might look like
the following:

.. code-block:: bareosconfig
   :caption: bareos-dir.d/console/restricted-user2.conf

   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 = "/"
   }
