Advanced Topics

Restricted Consoles

As shown above the REST-API administrator defines which bconsole.conf configuration file that will be used by each user defined to use the REST-API. The bconsole.conf file can either be unrestricted or restricted. In the case of a restricted console, REST-API must have a few minimum permissions. At a minimum, you must define in the bacula-dir.conf file the following ACLs for the user:

CatalogACL = <your-catalog>
CommandACL = "use, .catalogs"

Of course, for the REST-API to be useful, you will generally also need to include the JobACL and possible ClientACL. A simple example in bacula-dir.conf might be:

Console {
  Name = "JohnDoe"
  Password = "secret"
  JobACL = "Johns-NightlySave"
  CatalogACL = MyCatalog
  CommandACL = "use, .catalogs, list"
}

Basic Authentication

As an alternative to use OAuth2 authentication or as an addition to OAuth2, with lighttpd, you may add basic authentification, similar to what Apache permits.

Warning

The Basic authentication should be used for tests purposes. In production environments please use the OAuth2 authorization.

The following lighttpd configuration example implements basic authentication.

# in file /opt/bacula/rest-api/etc/lighttpd.conf
...
server.modules += ( "mod_auth")     # if not already done

auth.backend = "htpasswd"
auth.backend.htpasswd.userfile =  "/opt/bacula/rest-api/etc/htpasswd.rest-api"
auth.require = ( "/" =>
        (
        "method" => "basic",
        "realm" => "Password protected area",
        "require" => "valid-user"
        )
   )
...

The ligghtpd command htpasswd allows you to manage the list of users that can authenticate.

# htpasswd -c /opt/bacula/rest-api/etc/htpasswd.rest-api admin
New password:
Re-type new password:
Adding password for user admin

Using Scopes

Scopes are an additional feature that permits you to limit particular users to specific URIs using regular expressions.

When configuring Users authorized to use the REST API, on the Add User Panel, the last item on the screen is Scope with a default value of /*, which permits the user to enter any URI. Scopes consist of one or more regular expressions separated by spaces. For each URI that a particular user enters, his URI is compared to the Scopes that were entered when the user was defined. If no regular expression matches the URI presented, the URI will be rejected. Each scope regular expression that is entered by the administrator will be prefixed by the uparrow character. So the default scope of /* is parsed as the following regular expression:

^/*

which will permit all URIs that begin with a forward slash. The scope:

/cat/*

will permit only catalog commands.

The scope:

/cat/* /cmd/list/*

will permit all catalog commands and all Bacula list commands.

If a URI is given that has no matching scope, you will get the following error.

{
  "error": "invalid scope"
}


\smallskip
Note, if you specify a scope that you want to match a question mark, because
a scope is a regular expression, you must explicitly escape the
scope.  For example the following scope:

\begin{verbatim}
/cmd/list/[?]{1}[mp]+.*

will match all URI’s beginning with /cmd/list? and followed by a m or a p. For example

/cmd/list?media

or

/cmd/list?pools

Disabling OAuth2 Authorization

If you wish to disable OAuth2 authorization to Bacula REST API Server, then you can edit file located in:

/opt/bacula/rest-api/www/protected/Data/settings.conf

In the file you may find the option:

enable_oauth2 = "1"

For disabling OAuth2 authorization, please set above value to 0 (zero), eg:

enable_oauth2 = "0"

From now you may get all requests to REST API directly and without any authorization, eg.:

https://localhost/cat/Media/

https://localhost/cmd/list?jobs

Please be careful disabling this option. We strongly recommend that in a production environment that this option should always be turned on (set to “1”).

OAuth2 Token Expiration

The OAuth2 protocol works by acquiring a token from the authentication server, and the REST-API then uses that token for a certain amount of time and then refreshes the token. The token refresh takes a bit more time than a normal transaction. Currently the value is set to 12 seconds. If you wish to adjust it to a larger value (slightly less secure) such as 30 seconds, you can simply edit the file:

/opt/bacula/rest-api/www/porotected/Class/OAuth2/OAuth2.php

and change the line:

const ACCESS_TOKEN_EXPIRES_TIME = 12

to the value you want.

Architecture

The basic components in the Bacula Enterprise REST API as well as the flow of information and authorization is shown in the next figure.

The diagram in figure ACL Protection shows what is protected by Bacula Restricted Consoles and Bacula ACLs.

Working with cPanel

The REST API interface can also be used with various vendor panels such as cPanel.

The diagram in figure Example cPanel Plugin shows where the Bacula cPanel Plugin is placed and how it works.

Files for Bacula example cPanel Plugin are located in directory:

/opt/bacula/rest-api/www/protected/tools/cPanel_example_module/

with the front end files for the cPanel plugin visable part of the functionality in the following subdirectories of the cPanel_example_module:

./bbackup
./bbackup/runrestore.html
./bbackup/runbackup.html
./bbackup/index.html

The backend is found in:

/opt/bacula/rest-api/www/protected/tools//cPanel_example_module/Bbackup.pm

and the installation pack that contains icon and link to functionalities in the above files:

/opt/bacula/rest-api/www/protected/tools/cPanel_example_module/bbackup.cpanelplugin

The ISP Accounts plugin visible on diagram is integreted with Bacula REST API code as plugin located in:

/opt/bacula/rest-api/www/protected/Pages/Plugins/Accounts.php

It makes available the following interface:

/accounts/username123?action=list - lists backups
/accounts/username123?action=backup - performing backup home directory of username123
/accounts/username123?action=restore&jobid=XXX - performing restore from backup with jobid XXX to directory /home/restore/current date/

For using example Bacula REST API plugin one must force users to use ISP Accounts plugin by defining scopes. For example the user user321 must have the following scope definition:

/accounts/user321/*

The Bacula jobs associated with user321 would then be prefixed with the user name as follows:

user321-Full-Backup

The FileSets much also be prefixed as follows:

user321-FileSet

and the clients likewise:

user321-fd

These parameters can be changed in the file:

/opt/bacula/rest-api/www/protected/Pages/Plugins/Accounts.php

and in

/opt/bacula/rest-api/www/protected/tools//cPanel_example_module/Bbackup.pm