%% %% \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: # ...section body... # # To: # ...section body... # # # AuthType Basic AuthName "Baculum Auth" AuthUserFile /usr/share/baculum/htdocs/protected/API/Config/baculum.users Require valid-user # \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}