%%
%%

\chapter{Baculum API and Web GUI Tools}
\label{BaculumChapter}

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

\section{New Features in 11.0.0}

\subsection{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:
\begin{bitemize}
\item searching jobs by filename in the restore wizard
\item the file list on the finished backup job page
\end{bitemize}

Fully supported are the following relations:

\begin{bitemize}
\item Baculum 9.x with Bacula Director < 11.0
\item Baculum 11.0 with Bacula Director >= 11.0
\end{bitemize}

\subsection{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:

\begin{bitemize}
\item Console ACLs
\item OAuth2 clients
\item API hosts
\end{bitemize}

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.

\subsection{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.

\subsection{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.

\subsection{Add graphs to job view page}

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

\subsection{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.

\subsection{Add Russian translations}

\subsection{Global messages log window}

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

\subsection{Job status weather}

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

\subsection{Restore wizard improvements}

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

\subsection{New API endpoints}

\begin{bitemize}
\item /oauth2/clients
\item /oauth2/clients/{client\_id}
\item /jobs/files
\end{bitemize}

\subsection{New parameters in API endpoints}

\begin{bitemize}
\item /jobs/{jobid}/files - 'details' parameter
\item /storages/show - 'output' parameter
\item /storages/{storageid}/show - 'output' parameter
\end{bitemize}

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

\section{New Features in 9.6.0}

\subsection{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.

{\bf 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.

{\bf 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.

\subsection{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.

{\bf 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.

\subsection{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:

\begin{itemize}
\item baculum-api-selinux
\item baculum-web-selinux
\end{itemize}

\subsection{Graphical client status}

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

\subsection{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.

\subsection{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.

\subsection{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.

\subsection{New graph types}

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

\begin{itemize}
\item Job size / hour
\item Job size / day
\item Average job size / hour
\item Average job size / day
\item Job files / time
\item Job files / hour
\item Job files / day
\item Average job files / hour
\item Average job files / day
\item Job count / hour
\item Job count / day
\item Job duration / time
\item Average job speed / Time
\item Jobs status / day
\end{itemize}

\subsection{Support for new directives}

New Director directives support:

\begin{itemize}
\item Director resource:
 \begin{itemize}
 \item CommCompression
 \end{itemize}
\item Job resource:
 \begin{itemize}
 \item VirtualFullBackupPool
 \item MaxVirtualFullInterval
 \item BackupsToKeep
 \item DeleteConsolidatedJobs
 \end{itemize}
\item JobDefs resource:
 \begin{itemize}
 \item VirtualFullBackupPool
 \item MaxVirtualFullInterval
 \item BackupsToKeep
 \item DeleteConsolidatedJobs
 \end{itemize}
\item Console resource:
 \begin{itemize}
 \item RestoreClientAcl
 \item BackupClientAcl
 \item DirectoryAcl
 \end{itemize}
\end{itemize}

New Storage Daemon directives support:

\begin{itemize}
\item Storage resource:
 \begin{itemize}
 \item CommCompression
 \end{itemize}
\item Device resource:
 \begin{itemize}
 \item WormCommand
 \item Cloud
 \end{itemize}
\item Cloud resource:
 \begin{itemize}
 \item Name
 \item Description
 \item Driver
 \item HostName
 \item BucketName
 \item AccessKey
 \item SecretKey
 \item Region
 \item Protocol
 \item UriStyle
 \item TruncateCache
 \item Upload
 \item MaximumConcurrentUploads
 \item MaximumConcurrentDownloads
 \item MaximumUploadBandwidth
 \item MaximumDownloadBandwidth
 \end{itemize}
\end{itemize}

New File Daemon directives support:

\begin{itemize}
\item FileDaemon resource:
 \begin{itemize}
  \item CommCompression
 \end{itemize}
\end{itemize}

New Console directives support:

\begin{itemize}
\item Console resource:
 \begin{itemize}
  \item CommCompression
 \end{itemize}
\end{itemize}

\subsection{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:

\begin{itemize}
\item / - Baculum API panel
\item /oauth/authorize - to authorize in authorization server
\item /oauth/token - to get token from authorization server
\end{itemize}

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

{\bf 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.

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

\subsection{New API functions}

In Baculum API are added the following new functions:

\begin{itemize}
\item label volume with barcodes
\item label volume without barcode
\item update slots with barcodes
\item update slots without barcodes
\item start, stop and restart Bacula components
\item status client
\item set bandwidth limit for client
\item set bandwidth limit for job
\item list job files
\end{itemize}

\subsection{New Web controls}

The Baculum Web are added new controls to support:

\begin{itemize}
\item password directives with show/hide option
\item speed type directives
\item multiple the same Console ACL directives
\end{itemize}

\subsection{Miscellaneous improvements}

Miscellaneous improvements in Baculum API and Baculum Web:

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

\section{Base Features}

Baculum provides the following base features:

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

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

\bref{https://baculum.app}{https://baculum.app}

\section{General Requirements}

Environment for Baculum Web installation should have following components
installed:

\begin{itemize}
\item A web server - with URL rewrite module loaded.  Baculum Web has been
tested with Apache and Lighttpd web servers.
\item PHP 5.4.0 or higher with following modules installed:
 \begin{itemize}
 \item PHP cURL module
 \item PHP DOM module
 \item PHP JSON module
 \item PHP LDAP module
 \end{itemize}
\end{itemize}

Environment for Baculum API installation should have following components
installed:

\begin{itemize}
\item A web server - with URL rewrite module loaded. Baculum has been
tested with Apache and Lighttpd web servers.
\item PHP 5.4.0 or higher with following modules installed:
 \begin{itemize}
 \item 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.
 \item PHP BCMath module
 \item PHP DOM module
 \item PHP JSON module
 \end{itemize}
\item A working Bacula bconsole - configured Bacula text based console
\item Access to the Bacula Catalog database (local or remote)
\item In case using config module, read and write access to Bacula configuration
files
\end{itemize}


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

\section{Installation Baculum API from rpm binary packages}

{\bf 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:

\begin{itemize}
\item baculum-api - main Baculum API package with application files
\item baculum-api-httpd - Apache web server configuration files for Baculum API
\item baculum-api-lighttpd - Lighttpd web server configuration files for Baculum API
\item baculum-api-selinux - SELinux policy module for Baculum API
\item baculum-common - Common files for Baculum API and Baculum Web
\item baculum-web - main Baculum Web package with application files
\item baculum-web-httpd - Apache web server configuration files for Baculum Web
\item baculum-web-lighttpd - Lighttpd web server configuration files for Baculum Web
\item baculum-web-selinux - SELinux policy module for Baculum Web
\end{itemize}

\subsection{Add the Baculum rpm repository}

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

\begin{verbatim}
rpm --import http://www.bacula.org/downloads/baculum/baculum.pub
\end{verbatim}

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

\begin{verbatim}
/etc/yum.repos.d/baculum.repo
\end{verbatim}

For CentOS 7 the {\bf baculum.repo} file should have the following content:

For Bacula Director <= 9.6

\begin{verbatim}
[baculumrepo]
name=Baculum CentOS repository
baseurl=http://www.bacula.org/downloads/baculum/stable/centos
gpgcheck=1
enabled=1
\end{verbatim}

For Bacula Director >= 11.0

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

For CentOS 8 the {\bf baculum.repo} file should have the following content:

For Bacula Director <= 9.6

\begin{verbatim}
[baculumrepo]
name=Baculum CentOS repository
baseurl=http://www.bacula.org/downloads/baculum/stable/centos8
gpgcheck=1
enabled=1
\end{verbatim}

For Bacula Director >= 11.0

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

For Fedora 33 the {\bf baculum.repo} file should have the following content:

For Bacula Director <= 9.6

\begin{verbatim}
[baculumrepo]
name=Baculum Fedora repository
baseurl=http://www.bacula.org/downloads/baculum/stable/fedora33
gpgcheck=1
enabled=1
\end{verbatim}

For Bacula Director >= 11.0

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

For Fedora 34 the {\bf baculum.repo} file should have the following content:

For Bacula Director >= 11.0

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

\subsection{Installation for Apache}

Install Baculum API for the Apache web server as follows:

\begin{verbatim}
yum install baculum-common baculum-api baculum-api-httpd
\end{verbatim}

Restart your Apache web server:

\begin{verbatim}
systemctl restart httpd
\end{verbatim}


\subsection{Installation for Lighttpd}

Installation on system with access via Lighttpd is as follows:

\begin{verbatim}
yum install baculum-common baculum-api baculum-api-lighttpd
\end{verbatim}

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:

\begin{verbatim}
systemctl start baculum-api-lighttpd
\end{verbatim}

\subsection{SELinux support}

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

\begin{verbatim}
yum install baculum-api-selinux
\end{verbatim}

\subsection{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):\\

{\bf 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:

\begin{verbatim}
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
\end{verbatim}

In case default Lighttpd user the file contents must be:

\begin{verbatim}
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
\end{verbatim}

\section{Installation Baculum API from deb binary packages}

{\bf 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:

\begin{itemize}
\item baculum-api - main Baculum API package with application files
\item baculum-api-apache2 - Apache web server configuration files for Baculum API
\item baculum-api-lighttpd - Lighttpd web server configuration files for Baculum API
\item baculum-common - Common files for Baculum API and Baculum Web
\item baculum-web - main Baculum Web package with application files
\item baculum-web-apache2 - Apache web server configuration files for Baculum Web
\item baculum-web-lighttpd - Lighttpd web server configuration files for Baculum Web
\end{itemize}

\subsection{Add the Baculum deb repository}

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

\begin{verbatim}
wget -qO - http://www.bacula.org/downloads/baculum/baculum.pub | apt-key add -
\end{verbatim}

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

\begin{verbatim}
/etc/apt/sources.list.d/baculum.list
\end{verbatim}

For Debian 9 Stretch the {\bf baculum.list} file should have the following content:

For Bacula Director <= 9.6

\begin{verbatim}
deb http://www.bacula.org/downloads/baculum/stable/debian stretch main
deb-src http://www.bacula.org/downloads/baculum/stable/debian stretch main
\end{verbatim}

For Bacula Director >= 11.0

\begin{verbatim}
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
\end{verbatim}

For Debian 10 Buster the {\bf baculum.list} file should have the following content:

For Bacula Director <= 9.6

\begin{verbatim}
deb http://www.bacula.org/downloads/baculum/stable/debian buster main
deb-src http://www.bacula.org/downloads/baculum/stable/debian buster main
\end{verbatim}

For Bacula Director >= 11.0

\begin{verbatim}
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
\end{verbatim}

For Debian 11 Bullseye the {\bf baculum.list} file should have the following content:

For Bacula Director >= 11.0

\begin{verbatim}
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
\end{verbatim}

For Ubuntu 18.04 Bionic the {\bf baculum.list} file should have the following content:

For Bacula Director <= 9.6

\begin{verbatim}
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
\end{verbatim}

For Bacula Director >= 11.0

\begin{verbatim}
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
\end{verbatim}

For Ubuntu 20.04 Focal the {\bf baculum.list} file should have the following content:

For Bacula Director <= 9.6

\begin{verbatim}
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
\end{verbatim}

For Bacula Director >= 11.0

\begin{verbatim}
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
\end{verbatim}

After adding repository definition, please refresh repository indexes:
\begin{verbatim}
apt-get update
\end{verbatim}

\subsection{Installation for Apache}

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

\begin{verbatim}
apt-get install baculum-common baculum-api baculum-api-apache2
\end{verbatim}

Next you must enable mod\_rewrite module for Apache, with the
following command:

\begin{verbatim}
a2enmod rewrite
\end{verbatim}

and include Baculum VirtualHost definition in the Apache configuration
with:

\begin{verbatim}
a2ensite baculum-api
\end{verbatim}

Then restart your Apache server with:

\begin{verbatim}
systemctl restart apache2
\end{verbatim}

\subsection{Installation for Lighttpd}

Example installation with access via Lighttpd web server looks following:

\begin{verbatim}
apt-get install baculum-common baculum-api baculum-api-lighttpd
\end{verbatim}

Start Baculum API as application available through Lighttpd web server:

\begin{verbatim}
systemctl start baculum-api-lighttpd
\end{verbatim}

\subsection{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:

{\bf 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:

\begin{verbatim}
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
\end{verbatim}

\section{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:

\begin{verbatim}
/var/log/httpd/baculum-api-error.log
\end{verbatim}

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

\begin{verbatim}
/var/log/lighttpd/baculum-api-error.log
\end{verbatim}

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

\begin{verbatim}
/usr/share/baculum/htdocs/protected/API/Logs/baculum-api.log
\end{verbatim}

The debug you can enable in file:
\begin{verbatim}
/usr/share/baculum/htdocs/protected/API/Config/api.conf
\end{verbatim}

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.

\section{Installation Baculum Web from rpm binary packages}

\subsection{Installation for Apache}

Install Baculum Web for the Apache web server as follows:

\begin{verbatim}
yum install baculum-common baculum-web baculum-web-httpd
\end{verbatim}

Restart your Apache web server:

\begin{verbatim}
systemctl restart httpd
\end{verbatim}

\subsection{Installation for Lighttpd}

Installation on system with access via Lighttpd is as follows

\begin{verbatim}
yum install baculum-common baculum-web baculum-web-lighttpd
\end{verbatim}

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:

\begin{verbatim}
systemctl start baculum-web-lighttpd
\end{verbatim}

\subsection{SELinux support}

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

\begin{verbatim}
yum install baculum-web-selinux
\end{verbatim}

\section{Installation Baculum Web from deb binary packages}

\subsection{Installation for Apache}

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

\begin{verbatim}
apt-get install baculum-common baculum-web baculum-web-apache2
\end{verbatim}

Next you must enable mod\_rewrite module for Apache, with the
following command:

\begin{verbatim}
a2enmod rewrite
\end{verbatim}

and include Baculum VirtualHost definition in the Apache configuration with:

\begin{verbatim}
a2ensite baculum-web
\end{verbatim}

The restart your Apache server with:

\begin{verbatim}
systemctl restart apache2
\end{verbatim}

\subsection{Installation for Lighttpd}

Example installation with access via Lighttpd web server looks following:

\begin{verbatim}
apt-get install baculum-common baculum-web baculum-web-lighttpd
\end{verbatim}

Start Baculum Web as application available through Lighttpd web server:

\begin{verbatim}
systemctl start baculum-web-lighttpd
\end{verbatim}

\section{Running Baculum API and Web for the First Time}

\subsection{Running Baculum API}

Access to Baculum API from web browser: \textbf{http://localhost:9096}

First time login: \textbf{admin}

First time password: \textbf{admin}


\subsection{Running Baculum Web}

Access to Baculum Web from web browser: \textbf{http://localhost:9095}

First time login: \textbf{admin}

First time password: \textbf{admin}

\subsection{Installation wizards}

\textbf{Installation with HTTP Basic authentication}

\bimageH{baculum_install_basic}{Baculum installation with HTTP Basic authentication}{fig:baculuminstallbasic}

\smallskip

\textbf{Installation with OAuth2 authorization}

\bimageH{baculum_install_oauth2}{Baculum installation with HTTP Basic authentication}{fig:baculuminstalloauth2}

\smallskip

\subsection{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:

\begin{verbatim}
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).
\end{verbatim}

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.

\section{Baculum API documentation}

\subsection{API version 1}

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

\bref{https://www.bacula.org/downloads/baculum/baculum-api-v1/}{https://www.bacula.org/downloads/baculum/baculum-api-v1/}

\subsection{API version 2}

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

\bref{https://www.bacula.org/downloads/baculum/baculum-api-v2/}{https://www.bacula.org/downloads/baculum/baculum-api-v2/}

Changes in API version 2:

\begin{bitemize}
 \item Send request body parameters to the API in JSON format instead of
	 POST form parameters.
 \item Drop using the create[] and update[] surrounds in the POST and PUT
	request body parameters.
 \item 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.
 \item Unify /jobs/\{jobid\}/files endpoint output for detailed and normal modes.
 \item Stop using OAuth2 'status' scope.
 \item API version 1 is still possible to use and it is preserved. Nothing
	changes here.
 \item New and modern API admin panel.
\end{bitemize}

\subsubsection{Example usage}

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

\begin{verbatim}
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"}'
\end{verbatim}

where:

\begin{bitemize}
 \item API instance address is: baculum-api
 \item OAuth2 access token is: 6bd7c887e768efb9a031d0545aa0552de0140fe2
\end{bitemize}

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

\begin{verbatim}
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"}'
\end{verbatim}

where:

\begin{bitemize}
 \item API instance address is: baculum-api
 \item Basic user is: myuser
 \item Basic user password is: mypass
\end{bitemize}

\section{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:

\begin{verbatim}
cd bacula-gui-9.6.0/baculum/
\end{verbatim}

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:
{\bf /var/www/baculum}. This location can be changed during installation in
the {\bf WWWDIR} parameter value.

\subsection{Manual installation on rpm-based Linux distributions}

To prepare all Baculum files to installation please execute from the source
files path the following command:
\begin{verbatim}
make build DESTDIR=/tmp/baculum-files WWWDIR=/var/www/baculum
\end{verbatim}

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

Install the Baculum API and the Baculum Web dependencies:
\begin{verbatim}
yum install httpd php php-common php-pdo php-mysqlnd php-pgsql php-bcmath php-json php-xml
\end{verbatim}

Copy to the destination path all Baculum web type files:
\begin{verbatim}
cp -R /tmp/baculum-files/var/www/baculum/ /var/www
\end{verbatim}

Copy the web server configuration files:
\begin{verbatim}
cp /tmp/baculum-files/etc/httpd/conf.d/baculum-*conf /etc/httpd/conf.d/
\end{verbatim}

Copy the HTTP Basic authentication files:
\begin{verbatim}
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
\end{verbatim}

Copy translation files:
\begin{verbatim}
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
\end{verbatim}

Set recursively owner and group for files and directories:
\begin{verbatim}
chown -R apache:apache /var/www/baculum
\end{verbatim}

Prepare and install the SELinux module (if SELinux is used in operating system):
\begin{verbatim}
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
\end{verbatim}

Start the Apache web server
\begin{verbatim}
systemctl start httpd
\end{verbatim}

\subsection{Manual installation on deb-based Linux distributions}

To prepare all Baculum files to installation please execute from the source
files path the following command:
\begin{verbatim}
make build DESTDIR=/tmp/baculum-files SAMPLETYPE=deb-template HTTPDNAME=apache2 HTTPDSITECONF=sites-available WWWDIR=/var/www/baculum
\end{verbatim}

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

Install the Baculum Web and the Baculum API dependencies:

\begin{verbatim}
apt-get install apache2 libapache2-mod-php php-bcmath php-cgi php-mysql php-pgsql php-json php-xml php-curl
\end{verbatim}

Copy to the destination path all Baculum web type files:
\begin{verbatim}
cp -R /tmp/baculum-files/var/www/baculum/ /var/www
\end{verbatim}

Copy the web server configuration files:
\begin{verbatim}
cp /tmp/baculum-files/etc/apache2/sites-available/baculum-*conf /etc/apache2/sites-available/
\end{verbatim}

Copy the HTTP Basic authentication files:
\begin{verbatim}
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
\end{verbatim}

Copy translation files:
\begin{verbatim}
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
\end{verbatim}

Set recursively owner and group for files and directories:
\begin{verbatim}
chown -R www-data:www-data /var/www/baculum
\end{verbatim}

Enable the web server Baculum API and Baculum Web sites:
\begin{verbatim}
a2ensite baculum-api
a2ensite baculum-web
\end{verbatim}

Enable the URL rewrite module for the Apache web server:
\begin{verbatim}
a2enmod rewrite
\end{verbatim}

Start the Apache web server
\begin{verbatim}
systemctl start apache2
\end{verbatim}

\subsection{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:
\begin{verbatim}
/tmp/baculum-files/baculum-install-checker.sh -a
\end{verbatim}

To check files for installation with Lighttpd web server:
\begin{verbatim}
/tmp/baculum-files/baculum-install-checker.sh -l
\end{verbatim}

\section{OAuth2 authorization}

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

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

\begin{verbatim}
Authorization URL: /oauth/authorize
Access Token URL: /oauth/token
\end{verbatim}

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:

\begin{verbatim}
/usr/share/baculum/htdocs/protected/Common/Class/OAuth2.php
\end{verbatim}

in constants AUTHORIZATION\_ID\_EXPIRES\_TIME and ACCESS\_TOKEN\_EXPIRES\_TIME.

Default OAuth2 callback URL in Baculum Web is following:

\begin{verbatim}
https://baculumgui:9095/web/redirect
\end{verbatim}

\subsection{Before running OAuth2}

{\bf 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

\begin{verbatim}
#
# 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>

\end{verbatim}


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

\begin{verbatim}
#
# 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"
                )
        )
#}
\end{verbatim}

\section{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.

{\bf 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 {\bf 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).

\begin{verbatim}
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"
}
\end{verbatim}

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

\bimageH{baculum_add_oauth2_user_account}{Add OAuth2 user account}{fig:baculumaddoauth2}

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.

\bimageH{baculum_add_new_api_host}{Add new API host}{fig:baculumaddapihost}

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

\bimageH{baculum_define_user_to_api_host}{Define user to API host}{fig:baculumdefineuserapihost}
\bimageH{baculum_assign_user_to_api_host}{Assing user to API host}{fig:baculumassignuserapihost}

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.

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

\bimageH{baculum_multi_user_admin_mode}{Multi user interface - admin user}{fig:baculummultiuseradminmode}

\smallskip

\bimageH{baculum_multi_user_user_mode}{Multi user interface - normal user}{fig:baculummultiuserusermode}

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

\bimageH{baculum_normal_user_dashboard}{Normal user dashboard}{fig:baculumnormaluserdashboard}

\subsection{Multi-user interface setup in steps}

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

\begin{enumerate}
 \item Install Baculum API.
 \item Change the Baculum API web server config file to support OAuth2 and
 restart the web server.
 \item Go to the Baculum API installation wizard and fill needed forms on wizard
 steps.
 \item 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.
 \item Finish the Baculum API wizard.
 \item Install Baculum Web. Go to the installation wizard and fill forms on each
 wizard step.
 \item 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.
 \item Finish the Baculum Web wizard.
 \item 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.
 \item 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.
 \item 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.
 \item Go to the "Users" tab on the "Security" page, create new users and
 assign API hosts to them.
\end{enumerate}

{\bf 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.

\section{Autochanger management}
From version 11.0.2.1 Baculum provides an interface to manage tape
autochangers. This function enables to do the following tasks:

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

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.

\section{Screenshots}

\bimageH{baculum01}{Baculum dashboard}{fig:baculumdashboard}

\smallskip

\bimageH{baculum02}{Dashboard on mobile phone}{fig:baculummobdashboard}

\smallskip

\bimageH{baculum03}{Menu on mobile phone}{fig:baculummobmenu}

\smallskip

\bimageH{baculum04}{Job history list}{fig:baculumjobhistory}

\smallskip

\bimageH{baculum05}{Run job window}{fig:baculumrunjob}

\smallskip

\bimageH{baculum06}{Job details}{fig:baculumjobdetails}

\smallskip

\bimageH{baculum07}{Create new job}{fig:baculumnewjob}

\smallskip

\bimageH{baculum08}{Job status graph}{fig:baculumjobstatusgraph}

\smallskip

\bimageH{baculum09}{Client status}{fig:baculumclientstatus}
