Bacula Edition Documentation text image transdoc
Search

Main


Baculum API and Web GUI Tools

This chapter presents the Bacula Web based interface that has been added to the Bacula project for version 7.0 and later.

New Features in 11.0.0

Upgrade to 11.0.0

Baculum 9.x and older does not work with Bacula 11.0 because of the new catalog format in Bacula 11.0.0.

Baculum 11.0 works with Bacula < 11.0 but two file list specific functions does not work:

  • searching jobs by filename in the restore wizard
  • the file list on the finished backup job page

Fully supported are the following relations:

  • Baculum 9.x with Bacula Director < 11.0
  • Baculum 11.0 with Bacula Director >= 11.0

Multi-user interface improvements

There have been added new functions and improvements to the multi-user interface and restricted access.

The Security page has new tabs:

  • Console ACLs
  • OAuth2 clients
  • API hosts

These new tabs help to configure OAuth2 accounts, create restricted Bacula Console for users and create API hosts. They ease the process of creating users with a restricted Bacula resources access.

Add searching jobs by filename in the restore wizard

In the restore wizard now is possible to select job to restore by filename of file stored in backups. There is also possible to limit results to specific path.

Show more detailed job file list

The job file list now displays file details like: file attributes, UID, GID, size, mtime and information if the file record for saved or deleted file.

Add graphs to job view page

On the job view page, new pie and bar graphs for selected job are available.

Implement graphical status storage

On the storage status page are available two new types of the status (raw and graphical). The graphical status page is modern and refreshed asynchronously.

Add Russian translations

Global messages log window

There has been added new window to browse Bacula logs in a friendly way.

Job status weather

Add the job status weather on job list page to express current job condition.

Restore wizard improvements

In the restore wizard has been added listing and browsing names encoded in non-UTF encoding.

New API endpoints

  • /oauth2/clients
  • /oauth2/clients/client_id
  • /jobs/files

New parameters in API endpoints

  • /jobs/jobid/files - 'details' parameter
  • /storages/show - 'output' parameter
  • /storages/storageid/show - 'output' parameter

Note Upgrade from Baculum 9.6 to Baculum 11.0 is fully supported both for installations using binary packages and using source archives.

New Features in 9.6.0

Upgrade to 9.6.4

There has been introduced new way of managing users. If you use default Basic authetication - no additional change is required. If you use custom auth method realized by web server - no additional change is requred. If it is LDAP auth please consider switching to new LDAP auth method in Baculum Web.

Import users

Importing Basic users from default user file to Baculum Web is done automatically. If you would like to import LDAP users to Baculum Web, you can use import option available on the Security page.

New dependency

There has been added a new dependency. It is PHP LDAP module. There is required to install this module (php-ldap package) after upgrade. Appropriate information about this dependency is displayed on the Baculum Web page. If you install Baculum using binary packages, no additional action is needed because this dependency will be installed automatically.

Support for commands that can take a long time

Some commands executed in bconsole can take a long time. They are for example: label tape volumes in autochanger, update slots without barcodes, estimate job command. To Baculum has been added support for these long time taking actions. Previously if command took time longer than 30 seconds, the request timed out.

Note On the Baculum API side has been changed way of sending requests for the above command. More details about it you can find in the Baculum API documentation.

Support for SELinux

There are new SELinux policy modules for Baculum API and Baculum Web. They can be applied manually or by installing new rpm packages available in Baculum repositories for CentOS and Fedora:

  • baculum-api-selinux
  • baculum-web-selinux

Graphical client status

In Baculum Web on the client page is available new graphical client client.

Graphical running job status

In Baculum Web on the running job page is available new graphical running job status that shows detailed information about current job. For backup job type the status also displays file and byte progress bars which base on estimated values.

Capability to start, stop and restart components

In Baculum API and Baculum Web are now available actions to start, stop and restart Bacula components. Actions can be defined by users and they can be executed from Baculum Web interface or directly by sending requests to Baculum API.

Statistics configuration

Statistics resource provides new feature in Bacula that enables saving Bacula component statistics to external databases such as Graphite or CSV file. The statistics are now configurable on the Baculum interface.

New graph types

In Baculum Web on graph page are available new graph types:

  • Job size / hour
  • Job size / day
  • Average job size / hour
  • Average job size / day
  • Job files / time
  • Job files / hour
  • Job files / day
  • Average job files / hour
  • Average job files / day
  • Job count / hour
  • Job count / day
  • Job duration / time
  • Average job speed / Time
  • Jobs status / day

Support for new directives

New Director directives support:

  • Director resource:
    • CommCompression
  • Job resource:
    • VirtualFullBackupPool
    • MaxVirtualFullInterval
    • BackupsToKeep
    • DeleteConsolidatedJobs
  • JobDefs resource:
    • VirtualFullBackupPool
    • MaxVirtualFullInterval
    • BackupsToKeep
    • DeleteConsolidatedJobs
  • Console resource:
    • RestoreClientAcl
    • BackupClientAcl
    • DirectoryAcl

New Storage Daemon directives support:

  • Storage resource:
    • CommCompression
  • Device resource:
    • WormCommand
    • Cloud
  • Cloud resource:
    • Name
    • Description
    • Driver
    • HostName
    • BucketName
    • AccessKey
    • SecretKey
    • Region
    • Protocol
    • UriStyle
    • TruncateCache
    • Upload
    • MaximumConcurrentUploads
    • MaximumConcurrentDownloads
    • MaximumUploadBandwidth
    • MaximumDownloadBandwidth

New File Daemon directives support:

  • FileDaemon resource:
    • CommCompression

New Console directives support:

  • Console resource:
    • CommCompression

Changes in API endpoints

Please note that in Baculum API have been changed endpoints with access to API panel and with access OAuth2 tokens. New endpoints are follow:

  • / - Baculum API panel
  • /oauth/authorize - to authorize in authorization server
  • /oauth/token - to get token from authorization server

For backward compatibility previous panel and OAuth2 endpoints are still available, but they will be removed in the future.

Note For future versions Baculum API users, who use OAuth2 authorization and call API by own scripts, need to switch in theris scripts old OAuth2 endpoints to the new ones. Users, who install Baculum API from source archive, have to update the web server configuration to support new endpoints. Users, who install Baculum from binary packages, do not need to take any additional action.

Note Starting from version 9.6.0 there has been finished support for old API endpoints that do not contain version 'v1' in paths.

New API functions

In Baculum API are added the following new functions:

  • label volume with barcodes
  • label volume without barcode
  • update slots with barcodes
  • update slots without barcodes
  • start, stop and restart Bacula components
  • status client
  • set bandwidth limit for client
  • set bandwidth limit for job
  • list job files

New Web controls

The Baculum Web are added new controls to support:

  • password directives with show/hide option
  • speed type directives
  • multiple the same Console ACL directives

Miscellaneous improvements

Miscellaneous improvements in Baculum API and Baculum Web:

  • add option to show size unit values as decimal or binary bytes
  • add version number to API and Web
  • restore wizard improvements to use restore file browsers on different screen sizes and on mobile devices
  • add on status client page client and job bandwidth limit setting
  • add list job files tab to the job history page
  • add job history list on job page

Base Features

Baculum provides the following base features:

  • Running Bacula jobs (backup, restore, verify...).
  • Baculum API with OAuth2 authorization and HTTP Basic authentication.
  • Baculum Web GUI - modern mobile-friendly web interface.
  • Configuring Bacula on local and remote hosts.
  • Monitoring Bacula service status.
  • Bacula console available via a Web window.
  • Multi-user interface.
  • Support for customized and restricted consoles (Console ACL function).
  • Volume management.
  • User friendly graphs and metrics.
  • Basic storage daemon operations (mount, umount, release, ...).
  • Easy to use configuration and restore wizards.
  • Live AJAX based statuses.

To try Baculum features without installation, please visit the Baculum online demo page available at the following address:

https://baculum.app

General Requirements

Environment for Baculum Web installation should have following components installed:

  • A web server - with URL rewrite module loaded. Baculum Web has been tested with Apache and Lighttpd web servers.
  • PHP 5.4.0 or higher with following modules installed:
    • PHP cURL module
    • PHP DOM module
    • PHP JSON module
    • PHP LDAP module

Environment for Baculum API installation should have following components installed:

  • A web server - with URL rewrite module loaded. Baculum has been tested with Apache and Lighttpd web servers.
  • PHP 5.4.0 or higher with following modules installed:
    • PHP PDO support - depending on your catalog database: PDO PostgreSQL or PDO MySQL. Note, in case using MySQL database there is required to use MySQL native driver. It is php-mysqlnd for PHP, not php-mysql.
    • PHP BCMath module
    • PHP DOM module
    • PHP JSON module
  • A working Bacula bconsole - configured Bacula text based console
  • Access to the Bacula Catalog database (local or remote)
  • In case using config module, read and write access to Bacula configuration files

With installation from binary packages (deb, rpm) all requirements will be automatically installed as packages dependencies.

Installation Baculum API from rpm binary packages

Note Before start using Baculum API and Baculum Web version 9.0.0 and later please backup your Bacula configuration in safe place. It is specially important because on first save config action the Bacula configuration is joined into one file per Bacula component.

For rpm binary there are the following packages:

  • baculum-api - main Baculum API package with application files
  • baculum-api-httpd - Apache web server configuration files for Baculum API
  • baculum-api-lighttpd - Lighttpd web server configuration files for Baculum API
  • baculum-api-selinux - SELinux policy module for Baculum API
  • baculum-common - Common files for Baculum API and Baculum Web
  • baculum-web - main Baculum Web package with application files
  • baculum-web-httpd - Apache web server configuration files for Baculum Web
  • baculum-web-lighttpd - Lighttpd web server configuration files for Baculum Web
  • baculum-web-selinux - SELinux policy module for Baculum Web

Add the Baculum rpm repository

To add the Baculum repository, first you must import the Baculum public key: 

rpm --import http://www.bacula.org/downloads/baculum/baculum.pub

Once the key is imported, the next step is to add the repository definition. First you must create the following file: 

/etc/yum.repos.d/baculum.repo

For CentOS 7 the baculum.repo file should have the following content:

For Bacula Director <= 9.6 

[baculumrepo]
name=Baculum CentOS repository
baseurl=http://www.bacula.org/downloads/baculum/stable/centos
gpgcheck=1
enabled=1

For Bacula Director >= 11.0 

[baculumrepo]
name=Baculum CentOS repository
baseurl=http://www.bacula.org/downloads/baculum/stable-11/centos
gpgcheck=1
enabled=1

For CentOS 8 the baculum.repo file should have the following content:

For Bacula Director <= 9.6 

[baculumrepo]
name=Baculum CentOS repository
baseurl=http://www.bacula.org/downloads/baculum/stable/centos8
gpgcheck=1
enabled=1

For Bacula Director >= 11.0 

[baculumrepo]
name=Baculum CentOS repository
baseurl=http://www.bacula.org/downloads/baculum/stable-11/centos8
gpgcheck=1
enabled=1

For Fedora 33 the baculum.repo file should have the following content:

For Bacula Director <= 9.6 

[baculumrepo]
name=Baculum Fedora repository
baseurl=http://www.bacula.org/downloads/baculum/stable/fedora33
gpgcheck=1
enabled=1

For Bacula Director >= 11.0 

[baculumrepo]
name=Baculum Fedora repository
baseurl=http://www.bacula.org/downloads/baculum/stable-11/fedora33
gpgcheck=1
enabled=1

For Fedora 34 the baculum.repo file should have the following content:

For Bacula Director >= 11.0 

[baculumrepo]
name=Baculum Fedora repository
baseurl=http://www.bacula.org/downloads/baculum/stable-11/fedora34
gpgcheck=1
enabled=1

Installation for Apache

Install Baculum API for the Apache web server as follows: 

yum install baculum-common baculum-api baculum-api-httpd

Restart your Apache web server: 

systemctl restart httpd

Installation for Lighttpd

Installation on system with access via Lighttpd is as follows: 

yum install baculum-common baculum-api baculum-api-lighttpd

Please note that in case CentOS distribution the Lighttpd web server is available in the distribution packages after enabling the EPEL repository.

Start Baculum API as application using the Lighttpd web server: 

systemctl start baculum-api-lighttpd

SELinux support

To enable Baculum API support for SELinux is needed to install the following binary package: 

yum install baculum-api-selinux

Access to bconsole via sudo for Apache and Lighttpd

Baculum API requires access to Bconsole and to Bacula JSON programs. To configure Bconsole sudo access and the Bacula JSON programs access there can use following entries in newly created Baculum sudoers.d file (usually in path /etc/sudoers.d/baculum):

Note, please define sudo for the Bacula JSON programs only when you are going use Bacula configuration module in Baculum.

In case default Apache user, the file contents must be: 

Defaults:apache !requiretty
apache  ALL=NOPASSWD:  /usr/sbin/bconsole
apache  ALL=NOPASSWD:  /usr/sbin/bdirjson
apache  ALL=NOPASSWD:  /usr/sbin/bsdjson
apache  ALL=NOPASSWD:  /usr/sbin/bfdjson
apache  ALL=NOPASSWD:  /usr/sbin/bbconsjson

In case default Lighttpd user the file contents must be: 

Defaults:lighttpd !requiretty
lighttpd  ALL=NOPASSWD:  /usr/sbin/bconsole
lighttpd  ALL=NOPASSWD:  /usr/sbin/bdirjson
lighttpd  ALL=NOPASSWD:  /usr/sbin/bsdjson
lighttpd  ALL=NOPASSWD:  /usr/sbin/bfdjson
lighttpd  ALL=NOPASSWD:  /usr/sbin/bbconsjson

Installation Baculum API from deb binary packages

Note Before start using Baculum API and Baculum Web version 9.0.0 and later please backup your Bacula configuration in safe place. It is specially important because on first save config action the Bacula configuration is joined into one file per Bacula component.

For deb binary there are the following packages:

  • baculum-api - main Baculum API package with application files
  • baculum-api-apache2 - Apache web server configuration files for Baculum API
  • baculum-api-lighttpd - Lighttpd web server configuration files for Baculum API
  • baculum-common - Common files for Baculum API and Baculum Web
  • baculum-web - main Baculum Web package with application files
  • baculum-web-apache2 - Apache web server configuration files for Baculum Web
  • baculum-web-lighttpd - Lighttpd web server configuration files for Baculum Web

Add the Baculum deb repository

To add the Baculum repository, first import the Baculum public key: 

wget -qO - http://www.bacula.org/downloads/baculum/baculum.pub | apt-key add -

Once the key is imported, the next step is to create a new baculum file: 

/etc/apt/sources.list.d/baculum.list

For Debian 9 Stretch the baculum.list file should have the following content:

For Bacula Director <= 9.6 

deb http://www.bacula.org/downloads/baculum/stable/debian stretch main
deb-src http://www.bacula.org/downloads/baculum/stable/debian stretch main

For Bacula Director >= 11.0 

deb http://www.bacula.org/downloads/baculum/stable-11/debian stretch main
deb-src http://www.bacula.org/downloads/baculum/stable-11/debian stretch main

For Debian 10 Buster the baculum.list file should have the following content:

For Bacula Director <= 9.6 

deb http://www.bacula.org/downloads/baculum/stable/debian buster main
deb-src http://www.bacula.org/downloads/baculum/stable/debian buster main

For Bacula Director >= 11.0 

deb http://www.bacula.org/downloads/baculum/stable-11/debian buster main
deb-src http://www.bacula.org/downloads/baculum/stable-11/debian buster main

For Debian 11 Bullseye the baculum.list file should have the following content:

For Bacula Director >= 11.0 

deb http://www.bacula.org/downloads/baculum/stable-11/debian bullseye main
deb-src http://www.bacula.org/downloads/baculum/stable-11/debian bullseye main

For Ubuntu 18.04 Bionic the baculum.list file should have the following content:

For Bacula Director <= 9.6 

deb [ arch=amd64 ] http://www.bacula.org/downloads/baculum/stable/ubuntu bionic main
deb-src http://www.bacula.org/downloads/baculum/stable/ubuntu bionic main

For Bacula Director >= 11.0 

deb [ arch=amd64 ] http://www.bacula.org/downloads/baculum/stable-11/ubuntu bionic main
deb-src http://www.bacula.org/downloads/baculum/stable-11/ubuntu bionic main

For Ubuntu 20.04 Focal the baculum.list file should have the following content:

For Bacula Director <= 9.6 

deb [ arch=amd64 ] http://www.bacula.org/downloads/baculum/stable/ubuntu focal main
deb-src http://www.bacula.org/downloads/baculum/stable/ubuntu focal main

For Bacula Director >= 11.0 

deb [ arch=amd64 ] http://www.bacula.org/downloads/baculum/stable-11/ubuntu focal main
deb-src http://www.bacula.org/downloads/baculum/stable-11/ubuntu focal main

After adding repository definition, please refresh repository indexes: 

apt-get update

Installation for Apache

To install Baculum API access via Apache web server by using apt packages manager use the command: 

apt-get install baculum-common baculum-api baculum-api-apache2

Next you must enable mod_rewrite module for Apache, with the following command: 

a2enmod rewrite

and include Baculum VirtualHost definition in the Apache configuration with: 

a2ensite baculum-api

Then restart your Apache server with: 

systemctl restart apache2

Installation for Lighttpd

Example installation with access via Lighttpd web server looks following: 

apt-get install baculum-common baculum-api baculum-api-lighttpd

Start Baculum API as application available through Lighttpd web server: 

systemctl start baculum-api-lighttpd

Access to bconsole via sudo for Apache and Lighttpd

Baculum API requires access to Bconsole and to the Bacula JSON programs. To configure Bconsole sudo access, we strongly recommend that you create a Baculum sudoers.d file, which should be in /etc/sudoers.d/baculum:

Note, please define sudo for the Bacula JSON programs only when you are going use Bacula configuration module in Baculum.

Both for Apache and Lighttpd user the file contents can be: 

Defaults:www-data !requiretty
www-data  ALL=NOPASSWD:  /usr/sbin/bconsole
www-data  ALL=NOPASSWD:  /usr/sbin/bdirjson
www-data  ALL=NOPASSWD:  /usr/sbin/bsdjson
www-data  ALL=NOPASSWD:  /usr/sbin/bfdjson
www-data  ALL=NOPASSWD:  /usr/sbin/bbconsjson

Debugging your First Baculum API Login

At each step of the initial login to Baculum, the screen will have a test button, that will allow you to check if your parameters were correctly entered. If not, you will see error message on the wizard page. You can also get additional detail by examining the Apache error log, that is usually found at: 

/var/log/httpd/baculum-api-error.log

If you use Lighttpd thento get additional detail you can check: 

/var/log/lighttpd/baculum-api-error.log

In addition, special debug output is placed by Baculum in the file: 

/usr/share/baculum/htdocs/protected/API/Logs/baculum-api.log

The debug you can enable in file: 

/usr/share/baculum/htdocs/protected/API/Config/api.conf

by switching in [api] section option debug to "1".

With the information in those two files, you can usually quickly find and correct most problems.

Installation Baculum Web from rpm binary packages

Installation for Apache

Install Baculum Web for the Apache web server as follows: 

yum install baculum-common baculum-web baculum-web-httpd

Restart your Apache web server: 

systemctl restart httpd

Installation for Lighttpd

Installation on system with access via Lighttpd is as follows 

yum install baculum-common baculum-web baculum-web-lighttpd

Please note that in case CentOS distribution the Lighttpd web server is available in the distribution packages after enabling the EPEL repository.

Start Baculum as application using the Lighttpd web server: 

systemctl start baculum-web-lighttpd

SELinux support

To enable Baculum Web support for SELinux is needed to install the following binary package: 

yum install baculum-web-selinux

Installation Baculum Web from deb binary packages

Installation for Apache

To install Baculum Web access via Apache web server by using apt packages manager use the command: 

apt-get install baculum-common baculum-web baculum-web-apache2

Next you must enable mod_rewrite module for Apache, with the following command: 

a2enmod rewrite

and include Baculum VirtualHost definition in the Apache configuration with: 

a2ensite baculum-web

The restart your Apache server with: 

systemctl restart apache2

Installation for Lighttpd

Example installation with access via Lighttpd web server looks following: 

apt-get install baculum-common baculum-web baculum-web-lighttpd

Start Baculum Web as application available through Lighttpd web server: 

systemctl start baculum-web-lighttpd

Running Baculum API and Web for the First Time

Running Baculum API

Access to Baculum API from web browser: http://localhost:9096

First time login: admin

First time password: admin

Running Baculum Web

Access to Baculum Web from web browser: http://localhost:9095

First time login: admin

First time password: admin

Installation wizards

Installation with HTTP Basic authentication

Baculum installation with HTTP Basic authentication

Installation with OAuth2 authorization

Baculum installation with HTTP Basic authentication

Configuring Bacula

During first use the Bacula configuration feature when 'Save' button is clicked, there can be visible an permission error similar to this error: 

Error 1000: Internal error.
[Warning] file_put_contents(/etc/bacula/bacula-dir.conf): failed to open stream:
Permission denied (@line 56 in file
/usr/share/baculum/htdocs/protected/Common/Class/ConfigBacula.php).

It means that the Baculum API web server user does not have permission to write Bacula configuration file. To solve it, please setup permissions for Bacula configuration files to allow web server user have write access.

Baculum API documentation

API version 1

The documentation for Baculum API version 1 is placed at the following link:

https://www.bacula.org/downloads/baculum/baculum-api-v1/

API version 2

The documentation for Baculum API version 2 is placed at the following link:

https://www.bacula.org/downloads/baculum/baculum-api-v2/

Changes in API version 2:

  • Send request body parameters to the API in JSON format instead of POST form parameters.
  • Drop using the create[] and update[] surrounds in the POST and PUT request body parameters.
  • Move the /api/v1/status/{director|storage|client}/ endpoints to: /api/v2/clients/{clientid}/status, /api/v2/storages/{storageid}/status, /api/v2/directors/{director_name}/status.
  • Unify /jobs/{jobid}/files endpoint output for detailed and normal modes.
  • Stop using OAuth2 'status' scope.
  • API version 1 is still possible to use and it is preserved. Nothing changes here.
  • New and modern API admin panel.

Example usage

Example request to run a job when the OAuth2 authorization is enabled: 

curl \
  -X POST \
  'https://baculum-api:9096/api/v2/jobs/run' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 6bd7c887e768efb9a031d0545aa0552de0140fe2' \
  --data-raw '{"name": "BackupClient1", "level": "F", "client": "darkstar-fd","storage": "UP","pool": "Full-VTL","fileset": "ETC FS"}'

where:

  • API instance address is: baculum-api
  • OAuth2 access token is: 6bd7c887e768efb9a031d0545aa0552de0140fe2

Example request to run a job when the Basic authentication is enabled: 

curl \
  -X POST \
  'https://baculum-api:9096/api/v2/jobs/run' \
  --basic \
  -u 'myuser:mypass' \
  -H 'Content-Type: application/json' \
  --data-raw '{"name": "BackupClient1", "level": "F", "client": "darkstar-fd","storage": "UP","pool": "Full-VTL","fileset": "ETC FS"}'

where:

  • API instance address is: baculum-api
  • Basic user is: myuser
  • Basic user password is: mypass

Installation from the source tar file

There is possible to install Baculum from the source bacula-gui tar archive. To install please unpack the bacula-gui source archive and go to this unpacked directory: 

cd bacula-gui-9.6.0/baculum/

Then please prepare the Baculum API and the Baculum Web files depending on used distribution in the way described below.

In this description the document root directory for web files is path: /var/www/baculum. This location can be changed during installation in the WWWDIR parameter value.

Manual installation on rpm-based Linux distributions

To prepare all Baculum files to installation please execute from the source files path the following command: 

make build DESTDIR=/tmp/baculum-files WWWDIR=/var/www/baculum

After executing above command, the directory /tmp/baculum-files should contain all required files ready to copy to destination system paths.

Install the Baculum API and the Baculum Web dependencies: 

yum install httpd php php-common php-pdo php-mysqlnd php-pgsql php-bcmath php-json php-xml

Copy to the destination path all Baculum web type files: 

cp -R /tmp/baculum-files/var/www/baculum/ /var/www

Copy the web server configuration files: 

cp /tmp/baculum-files/etc/httpd/conf.d/baculum-*conf /etc/httpd/conf.d/

Copy the HTTP Basic authentication files: 

cp /tmp/baculum-files/etc/baculum/Config-api-apache/baculum.users /var/www/baculum/protected/API/Config
cp /tmp/baculum-files/etc/baculum/Config-web-apache/baculum.users /var/www/baculum/protected/Web/Config

Copy translation files: 

cp --remove-destination /tmp/baculum-files/usr/share/locale/en/LC_MESSAGES/baculum-api.mo /var/www/baculum/protected/API/Lang/en/messages.mo
cp --remove-destination /tmp/baculum-files/usr/share/locale/pl/LC_MESSAGES/baculum-api.mo /var/www/baculum/protected/API/Lang/pl/messages.mo
cp --remove-destination /tmp/baculum-files/usr/share/locale/pt/LC_MESSAGES/baculum-api.mo /var/www/baculum/protected/API/Lang/pt/messages.mo
cp --remove-destination /tmp/baculum-files/usr/share/locale/ru/LC_MESSAGES/baculum-api.mo /var/www/baculum/protected/API/Lang/ru/messages.mo
cp --remove-destination /tmp/baculum-files/usr/share/locale/en/LC_MESSAGES/baculum-web.mo /var/www/baculum/protected/Web/Lang/en/messages.mo
cp --remove-destination /tmp/baculum-files/usr/share/locale/pl/LC_MESSAGES/baculum-web.mo /var/www/baculum/protected/Web/Lang/pl/messages.mo
cp --remove-destination /tmp/baculum-files/usr/share/locale/pt/LC_MESSAGES/baculum-web.mo /var/www/baculum/protected/Web/Lang/pt/messages.mo
cp --remove-destination /tmp/baculum-files/usr/share/locale/ja/LC_MESSAGES/baculum-web.mo /var/www/baculum/protected/Web/Lang/ja/messages.mo
cp --remove-destination /tmp/baculum-files/usr/share/locale/ru/LC_MESSAGES/baculum-web.mo /var/www/baculum/protected/Web/Lang/ru/messages.mo

Set recursively owner and group for files and directories: 

chown -R apache:apache /var/www/baculum

Prepare and install the SELinux module (if SELinux is used in operating system): 

yum install selinux-policy-devel

make -C examples/selinux/ -f /usr/share/selinux/devel/Makefile baculum-api.pp
make -C examples/selinux/ -f /usr/share/selinux/devel/Makefile baculum-web.pp
install -D -m 644 examples/selinux/baculum-api.pp /usr/share/selinux/packages/baculum-api/baculum-api.pp
install -D -m 644 examples/selinux/baculum-web.pp /usr/share/selinux/packages/baculum-web/baculum-web.pp
semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/baculum/protected/API/Config(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/baculum/protected/API/Logs(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/baculum/protected/Web/Config(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/baculum/protected/Web/Logs(/.*)?'
semanage fcontext -a -t httpd_cache_t '/var/www/baculum/assets(/.*)?'
semanage fcontext -a -t httpd_cache_t '/var/www/baculum/protected/runtime(/.*)?'
restorecon -i -R '/var/www/baculum/protected/API/Config' '/var/www/baculum/protected/API/Logs' '/var/www/baculum/protected/Web/Config' '/var/www/baculum/protected/Web/Logs' '/var/www/baculum/assets' '/var/www/baculum/protected/runtime'
semodule -i /usr/share/selinux/packages/baculum-api/baculum-api.pp
semodule -i /usr/share/selinux/packages/baculum-web/baculum-web.pp

Start the Apache web server 

systemctl start httpd

Manual installation on deb-based Linux distributions

To prepare all Baculum files to installation please execute from the source files path the following command: 

make build DESTDIR=/tmp/baculum-files SAMPLETYPE=deb-template HTTPDNAME=apache2 HTTPDSITECONF=sites-available WWWDIR=/var/www/baculum

After executing above command, the directory /tmp/baculum-files should contain all required files ready to copy to destination system paths.

Install the Baculum Web and the Baculum API dependencies: 

apt-get install apache2 libapache2-mod-php php-bcmath php-cgi php-mysql php-pgsql php-json php-xml php-curl

Copy to the destination path all Baculum web type files: 

cp -R /tmp/baculum-files/var/www/baculum/ /var/www

Copy the web server configuration files: 

cp /tmp/baculum-files/etc/apache2/sites-available/baculum-*conf /etc/apache2/sites-available/

Copy the HTTP Basic authentication files: 

cp /tmp/baculum-files/etc/baculum/Config-api-apache/baculum.users /var/www/baculum/protected/API/Config
cp /tmp/baculum-files/etc/baculum/Config-web-apache/baculum.users /var/www/baculum/protected/Web/Config

Copy translation files: 

cp --remove-destination /tmp/baculum-files/usr/share/locale/en/LC_MESSAGES/baculum-api.mo /var/www/baculum/protected/API/Lang/en/messages.mo
cp --remove-destination /tmp/baculum-files/usr/share/locale/pl/LC_MESSAGES/baculum-api.mo /var/www/baculum/protected/API/Lang/pl/messages.mo
cp --remove-destination /tmp/baculum-files/usr/share/locale/pt/LC_MESSAGES/baculum-api.mo /var/www/baculum/protected/API/Lang/pt/messages.mo
cp --remove-destination /tmp/baculum-files/usr/share/locale/ru/LC_MESSAGES/baculum-api.mo /var/www/baculum/protected/API/Lang/ru/messages.mo
cp --remove-destination /tmp/baculum-files/usr/share/locale/en/LC_MESSAGES/baculum-web.mo /var/www/baculum/protected/Web/Lang/en/messages.mo
cp --remove-destination /tmp/baculum-files/usr/share/locale/pl/LC_MESSAGES/baculum-web.mo /var/www/baculum/protected/Web/Lang/pl/messages.mo
cp --remove-destination /tmp/baculum-files/usr/share/locale/pt/LC_MESSAGES/baculum-web.mo /var/www/baculum/protected/Web/Lang/pt/messages.mo
cp --remove-destination /tmp/baculum-files/usr/share/locale/ja/LC_MESSAGES/baculum-web.mo /var/www/baculum/protected/Web/Lang/ja/messages.mo
cp --remove-destination /tmp/baculum-files/usr/share/locale/ru/LC_MESSAGES/baculum-web.mo /var/www/baculum/protected/Web/Lang/ru/messages.mo

Set recursively owner and group for files and directories: 

chown -R www-data:www-data /var/www/baculum

Enable the web server Baculum API and Baculum Web sites: 

a2ensite baculum-api
a2ensite baculum-web

Enable the URL rewrite module for the Apache web server: 

a2enmod rewrite

Start the Apache web server 

systemctl start apache2

Validating manual installation

To check manually installed the Baculum API and the Baculum Web files please use a script, which checks whether files and directories exist in proper paths, if they have set valid permissions, ownership and other requirements.

To check files for installation with Apache web server: 

/tmp/baculum-files/baculum-install-checker.sh -a

To check files for installation with Lighttpd web server: 

/tmp/baculum-files/baculum-install-checker.sh -l

OAuth2 authorization

In Baculum API you can setup OAuth2 for authorization and authentication.

To get an access token there is used Authorization Code Grant flow. Authorization and access token URLs are as follow: 

Authorization URL: /oauth/authorize
Access Token URL: /oauth/token

Baculum API does not use refresh tokens. After expiration token the client application has to re-authorize again.

Default expiration time for authorization code is 7 seconds, for access token 120 seconds. These values can be changed in: 

/usr/share/baculum/htdocs/protected/Common/Class/OAuth2.php

in constants AUTHORIZATION_ID_EXPIRES_TIME and ACCESS_TOKEN_EXPIRES_TIME.

Default OAuth2 callback URL in Baculum Web is following: 

https://baculumgui:9095/web/redirect

Before running OAuth2

Important note before using OAuth2

When you decide to use OAuth2, you must change default HTTP Basic authentication setting. Otherwise OAuth2 will not work. It is all about enabling OAuth2 acces to /api/ endpoints but still keeping the HTTP Basic protection for the Baculum API panel pages.

For Apache this change consists in replacing in the Baculum API Apache config the Directory tag /usr/share/baculum/htdocs into Location tag /panel 

#
# NOTE: When you use OAuth2 then change this Directory section
# From: <Directory /usr/share/baculum/htdocs>
#            ...section body...
#       </Directory>
# To:   <Location /panel>
#            ...section body...
#       </Location>
#
<Directory /usr/share/baculum/htdocs>
#<Location /panel>
        AuthType Basic
        AuthName "Baculum Auth"
        AuthUserFile /usr/share/baculum/htdocs/protected/API/Config/baculum.users
        Require valid-user
#</Location>
</Directory>

For Lighttpd this change consists in uncommenting in the Baculum API Lighttpd config lines as shown in the comment below. 

#
# Uncomment this line and closing braces below when you use OAuth2
#
#$HTTP["url"] =~ "^/panel.*$" {
        auth.backend = "htpasswd"
        auth.backend.htpasswd.userfile = "/usr/share/baculum/htdocs/protected/API/Config/baculum.users"
        auth.require = ( "/" => (
                "method" => "basic",
                "realm" => "Baculum Auth",
                "require" => "valid-user"
                )
        )
#}

Multi-user interface

Baculum enables access to Bacula resources for defined users, where every user uses own resources (Jobs, Clients, FileSets ...etc.). These resources are assigned to users by the Bacula Restricted Consoles and then they are used by Baculum.

To setup this multi-user interface there is needed to enable the OAuth2 authorization on Baculum API hosts, that are used by the Baculum Web interface. There is also necessary to configure in the Director the Console resources for users and Bconsole config files dedicated for them.

Note Since Baculum version 9.6.6.1 all the process described below can be done directly from the Baculum Web interface.

Minimal Console resource configuration can look as below. These CommandAcl values in the configuration are required to proper working all available functions for normal Baculum users (run job, restore backup, cancel job, delete job and others). 

Console {
  Name = "Limited User 144"
  Password = "A6cTimESfLs7xPNOMC/ein92BF4="
  JobAcl = "BackupCatalog"
  JobAcl = "RestoreFiles"
  ClientAcl = "myhost-fd"
  StorageAcl = "File1"
  PoolAcl = "File"
  CommandAcl = "gui"
  CommandAcl = ".api"
  CommandAcl = ".jobs"
  CommandAcl = ".ls"
  CommandAcl = ".client"
  CommandAcl = ".fileset"
  CommandAcl = ".pool"
  CommandAcl = ".status"
  CommandAcl = ".storage"
  CommandAcl = ".bvfs_get_jobids"
  CommandAcl = ".bvfs_update"
  CommandAcl = ".bvfs_lsdirs"
  CommandAcl = ".bvfs_lsfiles"
  CommandAcl = ".bvfs_versions"
  CommandAcl = ".bvfs_restore"
  CommandAcl = ".bvfs_cleanup"
  CommandAcl = "restore"
  CommandAcl = "show"
  CommandAcl = "estimate"
  CommandAcl = "run"
  CommandAcl = "delete"
  CommandAcl = "cancel"
  FilesetAcl = "Full Set"
  CatalogAcl = "MyCatalog"
  WhereAcl = "/tmp/restore"
}

Assigning Restricted Consoles to users is realized during configuring OAuth2 accounts on API hosts panel as on attached screenshot.

Add OAuth2 user account

Please note that in the OAuth2 scopes there is not "config" scope defined, because normal users don't have access to configuring Bacula resources by Baculum API hosts.

Once the OAuth2 accounts with assigned dedicated consoles are done, now you can connect Baculum Web to those new Baculum API OAuth2 accounts.

Add new API host

At the end there is needed to create Baculum Web users and assign them to appropriate OAuth2 user accounts on API hosts.

Define user to API host
Assing user to API host

Images below show example access to Baculum API hosts by a normal user and by an admin user. In this setting the administrator is able to manage Host A, Host B, Host C and the normal user is able to use Host B only.

Note Since version 11.0.2.2 there is possible to assign multiple API hosts to one user account.

Multi user interface - admin user

Multi user interface - normal user

Normal (non-admin) user interface can look as on screenshot:

Normal user dashboard

Multi-user interface setup in steps

Below you can find list with steps needed to setup the Baculum multi-user interface:

  1. Install Baculum API.
  2. Change the Baculum API web server config file to support OAuth2 and restart the web server.
  3. Go to the Baculum API installation wizard and fill needed forms on wizard steps.
  4. In "Authentication" step please select OAuth2 authorization option and define there administrator OAuth2 client account. It is an account without any dedicated Bconsole config file path (full bconsole access) and with all scopes.
  5. Finish the Baculum API wizard.
  6. Install Baculum Web. Go to the installation wizard and fill forms on each wizard step.
  7. In the "Add API host" step please select OAuth2 authorization option and please provide the administrator OAuth2 account parameters defined previously in the Baculum API installation wizard.
  8. Finish the Baculum Web wizard.
  9. Define in the Bacula Director configuration dedicated Consoles for users. You can do it on the Baculum interface or manually in the Director configuration file. At the end please reload the Director configuration.
  10. In Baculum API panel on the "OAuth2 clients" page create new OAuth2 client accounts, each account for separate user or group of users. For each OAuth2 account in field "Dedicated Bconsole config file path" define separate Bconsole config file with access only to selected restricted console (the bconsole configuration files must be prepared manually before this step). In scopes field please be careful to not set "config" or "actions" scopes to regular user if it isn't your intention.
  11. In Baculum Web on the "Security" page in "API hosts" tab please click "Add API host" button and add there created in previous point all OAuth2 client accounts.
  12. Go to the "Users" tab on the "Security" page, create new users and assign API hosts to them.

Note Since Baculum version 9.6.6.1 if your use the OAuth2 account with 'oauth2' scope you can perform all above steps, that are doing on API side (add OAuth2 client, create dedicated Bconsole configuration file), directly in the Baculum Web interface on the Security page.

Autochanger management

From version 11.0.2.1 Baculum provides an interface to manage tape autochangers. This function enables to do the following tasks:

  • Load tape from slot to tape drive (with and without mounting tape).
  • Unload tape from tape drive to slot.
  • Update slots using barcordes.
  • Update slots reading labels directly from volumes (for changers without barcode reader).
  • Move tape(s) to import/export slots.
  • Release single import/export slot.
  • Release all import/export slots at once.

To manage autochanger there is needed to define autochanger tape drives and autochanger device setting on dedicated Device page for that available in the Baculum API panel. After that the autochanger management should be available on the Baculum Web side on the Storage page after selecting the Storage resource associated with the autochanger device.

Screenshots

Baculum dashboard

Dashboard on mobile phone

Menu on mobile phone

Job history list

Run job window

Job details

Create new job

Job status graph

Client status