From 4778aadccfd416213a23472a9558cde5e0acbab6 Mon Sep 17 00:00:00 2001 From: Marcin Haba Date: Thu, 25 May 2017 12:21:36 +0200 Subject: [PATCH] Update Baculum documenation --- docs/manuals/en/console/baculum.tex | 789 +++++++++++++++++++++------- 1 file changed, 596 insertions(+), 193 deletions(-) diff --git a/docs/manuals/en/console/baculum.tex b/docs/manuals/en/console/baculum.tex index b185aa67..6e0c1300 100644 --- a/docs/manuals/en/console/baculum.tex +++ b/docs/manuals/en/console/baculum.tex @@ -1,7 +1,7 @@ %% %% -\chapter{Baculum Web GUI Tool} +\chapter{Baculum API and Web GUI Tools} \label{BaculumChapter} This chapter presents the Bacula Web based interface that has been added to @@ -13,6 +13,9 @@ 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 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. @@ -27,48 +30,63 @@ Baculum provides the following base features: \section{General Requirements} -Environment for Baculum installation should have following components +Environment for Baculum Web installation should have following components +installed: + +\begin{itemize} +\item A Web Server - with mod\_rewrite module loaded. Baculum Web has been +tested with Apache and Lighttpd web servers. +\item PHP 5.3.4 or higher with following modules installed: + \begin{itemize} + \item cURL PHP module. + \item MB String PHP module. + \item JSON PHP module. + \end{itemize} +\end{itemize} + +Environment for Baculum API installation should have following components installed: \begin{itemize} \item A Web Server - with mod\_rewrite module loaded. Baculum has been -tested with Apache, Nginx and Lighttpd web servers. -\item PHP 5.3 or higher with following modules installed: +tested with Apache and Lighttpd web servers. +\item PHP 5.3.4 or higher with following modules installed: \begin{itemize} \item PDO PHP 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 BCMath PHP module. - \item cURL PHP module. - \item MB String PHP module. \item JSON PHP module. \end{itemize} \item A working Bacula bconsole - configured Bacula text based console \item Direct access to the Bacula Catalog database (local or remote) \end{itemize} -All the above requirements are validated during Baculum start. If -an error is found you will be notified during the initial login. -See below for instructions on how to correct errors. With installation from binary packages (deb, rpm) all requirements will be automatically installed as packages dependencies. -\section{Installation from rpm binary packages} +\section{Installation Baculum API from rpm binary packages} + +{\bf Note} +Baculum API and Baculum Web version 9.0.0 are Beta version and before start using +them, 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 - main package with application files -\item baculum-selinux - SELinux policies module -\item baculum-httpd - Apache web server configuration files -\item baculum-lighttpd - Lighttpd web server configuration files +\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-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 \end{itemize} -You must install at a minimum the {\bf baculum} package and either -baculum-http or {\bf baculum-lighttpd}. - -\subsection{Add the Bacula rpm repository} +\subsection{Add the Baculum rpm repository} To add the Baculum repository, first you must import the Baculum public key: @@ -87,28 +105,28 @@ The for CentOS 7, put the following in the file just created: \begin{verbatim} [baculumrepo] -name=Baculum CentOS repository -baseurl=http://bacula.org/downloads/baculum/centos +name=Baculum Beta CentOS repository +baseurl=http://bacula.org/downloads/baculum/beta/centos gpgcheck=1 enabled=1 \end{verbatim} -For Fedora 23 the {\bf bacula.repo} file should have the following contents: +For Fedora 25 the {\bf bacula.repo} file should have the following contents: \begin{verbatim} [baculumrepo] -name=Baculum Fedora repository -baseurl=http://bacula.org/downloads/baculum/fedora +name=Baculum Beta Fedora repository +baseurl=http://bacula.org/downloads/baculum/beta/fedora gpgcheck=1 enabled=1 \end{verbatim} -\subsection{Installation for the Apache Web server} +\subsection{Installation for the Apache} -Install Baculum for the Apache Web server as follows: +Install the Baculum API for the Apache Web server as follows: \begin{verbatim} -yum install baculum baculum-httpd +yum install baculum-common baculum-api baculum-api-httpd \end{verbatim} Restart your Apache Web server: @@ -117,176 +135,264 @@ Restart your Apache Web server: service httpd restart \end{verbatim} -\subsection{Access to bconsole via sudo} -Baculum requires access to Bconsole. To configure Bconsole sudo access there -can use following entries in newly created Baculum sudoers.d file (usually in -path /etc/sudoers.d/baculum): +\subsection{Installation for Lighttpd} -In case default user both for Apache and Lighttpd: +Installation on system with access via Lighttpd is as follows \begin{verbatim} -Defaults:web-user !requiretty -web-user ALL=NOPASSWD: /usr/sbin/bconsole +yum install baculum-common baculum-api baculum-api-lighttpd \end{verbatim} -Where {\bf web-user} must be replaced by the Linux -username under which your Web server is running. +Please note that in case CentOS distribution the Lighttpd web server is +available in the distribution packages after enabling the EPEL repository. -For example, on Fedora the default Apache server name is {\bf apache}; -on Debian/Ubuntu it is {\bf www-data}, and on CentOS/RedHat it -is {\bf apache} or {\bf apache2}. +Start Baculum as application using the Lighttpd Web server: -\subsection{Running Baculum for the First Time} -Access Baculum from a Web browser: \textbf{http://localhost:9095} +\begin{verbatim} +service baculum-api-lighttpd start +\end{verbatim} -First time login: \textbf{admin} +\subsection{Access to bconsole via sudo for Apache and Lighttpd} -First time password: \textbf{admin} +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):\\ -\subsection{Debugging your First Login} -At each step of the initial login to Baculum, the -screen will have a test button that will allow you -to check to see if your parameters were correctly -entered. If not, you can get additional detail by -examining the Apache error log, that is usually -found at: +In case default Apache user, the file contents must be: \begin{verbatim} -/var/log/apache2/error.log +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 addition, special debug output is placed by Baculum in -the file: +In case default Lighttpd user the file contents must be: \begin{verbatim} -/etc/baculum/Data-apache/baculum.dbg +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} -With the information in those two files, you can usually quickly -find and correct most problems. +\section{Installation Baculum API from deb binary packages} +{\bf Note} +Baculum API and Baculum Web version 9.0.0 are Beta version and before start using +them, 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.\\ -\subsection{Installation for Lighttpd} +For deb binary there are the following packages: -Installation on system with SELinux enabled access and access via -Lighttpd is as follows +\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} -yum install baculum baculum-selinux baculum-lighttpd +wget -qO - http://bacula.org/downloads/baculum/baculum.pub | apt-key add - \end{verbatim} -You can skip installing baculum-selinux if you do not use SELinux. +Once the key is imported, the next step is to create +a new baculum file: -Please note that in case CentOS distribution the Lighttpd web server is -available in the distribution packages after enabling the EPEL repository. +\begin{verbatim} +/etc/apt/sources.list.d/baculum.list +\end{verbatim} -Start Baculum as application using the lighttpd Web server: +For Debian 8 Jessie the contents should be: \begin{verbatim} -service baculum-lighttpd start +deb http://bacula.org/downloads/baculum/beta/debian jessie main +deb-src http://bacula.org/downloads/baculum/beta/debian jessie main \end{verbatim} +For Ubuntu 16.04 Xenial the contents should be: +\begin{verbatim} +deb [ arch=amd64 ] http://bacula.org/downloads/baculum/beta/ubuntu xenial main +deb-src http://bacula.org/downloads/baculum/beta/ubuntu xenial main +\end{verbatim} -\subsection{Access to bconsole via sudo} -Baculum requires access to Bconsole. To configure Bconsole sudo access -we strongly recommend that you create a Baculum sudoers.d file, which -should be in /etc/sudoers.d/baculum: +After adding repository definition, please refresh repository indexes: +\begin{verbatim} +apt-get update +\end{verbatim} -In case default Apache user, the file contents must be: +\subsection{Installation for Apache} + +To install Baculum API access via Apache Web server by using apt +packages manager use the command: \begin{verbatim} -Defaults:apache !requiretty -apache ALL=NOPASSWD: /usr/sbin/bconsole +apt-get install baculum-common baculum-api baculum-api-apache2 \end{verbatim} -In case default Lighttpd user the file contents must be: +Next you must enable mod\_rewrite module for Apache, with the +following command: \begin{verbatim} -Defaults:lighttpd !requiretty -lighttpd ALL=NOPASSWD: /usr/sbin/bconsole +a2enmod rewrite \end{verbatim} -\subsection{Running Baculum for the First Time with Lighttpd} -Access Baculum from your Web browser: \textbf{http://localhost:9095} +and include Baculum VirtualHost definition in the Apache configuration +with: -First time login: \textbf{admin} +\begin{verbatim} +a2ensite baculum-api +\end{verbatim} -First time password: \textbf{admin} +The restart your Apache server with: + +\begin{verbatim} +service apache2 restart +\end{verbatim} -\section{Installation from deb binary packages} +\subsection{Installation for Lighttpd} -For deb binary packages format you will find the following packages: +Example installation with access via Lighttpd web server looks following: -\begin{itemize} -\item baculum - main package with application files -\item baculum-apache2 - Apache web server configuration files -\item baculum-lighttpd - Lighttpd web server configuration files -\end{itemize} +\begin{verbatim} +apt-get install baculum-common baculum-api baculum-api-lighttpd +\end{verbatim} -\subsection{Add deb repository} +Start Baculum API as application available through Lighttpd web server: -To add the Baculum repository, first import the Baculum public key: +\begin{verbatim} +service baculum-api-lighttpd start +\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 the Baculum. + +Both for Apache and Lighttpd user the file contents can be: \begin{verbatim} -wget -qO - http://bacula.org/downloads/baculum/baculum.pub | apt-key add - +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} -Once the key is imported, the next step is to create -a new baculum file: +\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 to see 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} -/etc/apt/sources.list.d/baculum.list +/var/log/httpd/baculum-api-error.log \end{verbatim} -For Debian 8 Jessie the contents should be: +If you use Lighttpd thento get additional detail you can check: \begin{verbatim} -deb http://bacula.org/downloads/baculum/debian jessie main -deb-src http://bacula.org/downloads/baculum/debian jessie main +/var/log/lighttpd/baculum-api-error.log \end{verbatim} -For Ubuntu 15.04 Vivid the contents should be: +In addition, special debug output is placed by Baculum in +the file: + \begin{verbatim} -deb [ arch=amd64 ] http://bacula.org/downloads/baculum/ubuntu vivid main -deb-src http://bacula.org/downloads/baculum/ubuntu vivid main +/usr/share/baculum/htdocs/protected/API/Logs/baculum-api.log \end{verbatim} -For Ubuntu 15.10 Wily the contents should be: +The debug you can enable in file: \begin{verbatim} -deb [ arch=amd64 ] http://bacula.org/downloads/baculum/ubuntu wily main -deb-src http://bacula.org/downloads/baculum/ubuntu wily main +/usr/share/baculum/htdocs/protected/API/Config/api.conf \end{verbatim} -After adding repository definition, please refresh repository indexes: +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 the Apache} + +Install the Baculum Web for the Apache Web server as follows: + \begin{verbatim} -apt-get update +yum install baculum-common baculum-web baculum-web-httpd \end{verbatim} +Restart your Apache Web server: + +\begin{verbatim} +service httpd restart +\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} +service baculum-web-lighttpd start +\end{verbatim} + +\section{Installation Baculum Web from deb binary packages} + \subsection{Installation for Apache} -To install Baculum access via Apache Web server by using apt +To install Baculum Web access via Apache Web server by using apt packages manager use the command: \begin{verbatim} -apt-get install baculum baculum-apache2 +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} -ln -s /etc/apache2/mods-available/rewrite.load \ - /etc/apache2/mods-enabled/rewrite.load +a2enmod rewrite \end{verbatim} and include Baculum VirtualHost definition in the Apache configuration with: \begin{verbatim} -ln -s /etc/apache2/sites-available/baculum.conf \ - /etc/apache2/sites-enabled/baculum.conf +a2ensite baculum-web \end{verbatim} The restart your Apache server with: @@ -295,33 +401,333 @@ The restart your Apache server with: service apache2 restart \end{verbatim} -and access Baculum from you Web browser with: \textbf{http://localhost:9095} - -First time login: \textbf{admin} - -First time password: \textbf{admin} - \subsection{Installation for Lighttpd} Example installation with access via Lighttpd web server looks following: \begin{verbatim} -apt-get install baculum baculum-lighttpd +apt-get install baculum-common baculum-web baculum-web-lighttpd \end{verbatim} -Start Baculum as application available through Apache web server: +Start Baculum Web as application available through Lighttpd web server: \begin{verbatim} -service baculum-lighttpd start +service baculum-web-lighttpd start \end{verbatim} -Access from web browser: \textbf{http://localhost:9095} +\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} + +\section{Installation wizards} + +\textbf{Installation with HTTP Basic authentication} + +\includegraphics[width=\linewidth]{baculum_install_basic.png} + +\smallskip + +\textbf{Installation with OAuth2 authorization} + +\includegraphics[width=\linewidth]{baculum_install_oauth2.png} + +\smallskip + +\section{Baculum API endpoints} + +\subsection{Clients} + +GET /api/clients - get records all clients + +GET /api/clients/limit/4 - get records first 4 clients + +GET /api/clients/2 - get records only for client with clientid equal 2 + +GET /api/clients/show - get 'show clients' bconsole command + +GET /api/clients/show/2 - get 'show client=xxx' bconsole command for client with clientid equal 2 + +GET /api/clients/status/2 - get 'status client=xxx' bconsole command for client with clientid equal 2 + +GET /api/clients/jobs/2 - get all jobs done by client with clientid equal 2\\ + + +Errors: + +0 - No errors. + +1 - Invalid command. + +2 - Problem with connection to database. + +3 - Database access is not supported by this API instance. + +4 - Problem with connection to bconsole. + +5 - Invalid director. + +6 - Problem with authorization to Baculum API. + +7 - Access attempt to not allowed resource. Permission denied. + +10 - Client with inputted clientid does not exists. + +1000 - Internal error. + +\subsection{Storages} + +GET /api/storages/ - get records all storages. + +GET /api/storages/limit/25 - get records first 25 storages. + +GET /api/storages/3 - get records only for storage with storageid equal 3. + +GET /api/storages/show - get 'show storages' bconsole command. + +GET /api/storages/show/3 - get 'show storage=xxx' bconsole command for storage with storageid equal 3. + +GET /api/storages/status/3 - get 'status storage=xxx' bconsole command for storage with storageid equal 3. + +GET /api/storages/mount/3/2/17 - mount storage with storageid equal 3, drive number 2 and volume in slot number 17. + +GET /api/storages/umount/3/1 - umount storage with storageid equal 3 and drive number 1. + +GET /api/storages/release/3 - release storage with storageid equal 3.\\ + + +Errors: + +0 - No errors. + +1 - Invalid command. + +2 - Problem with connection to database. + +3 - Database access is not supported by this API instance. + +4 - Problem with connection to bconsole. + +5 - Invalid director. + +6 - Problem with authorization to Baculum API. + +7 - Access attempt to not allowed resource. Permission denied. + +20 - Storage with inputted storageid does not exists. + +1000 - Internal error. + +\subsection{Volumes} + +GET /api/volumes/ - get records all volumes. + +GET /api/volumes/limit/50 - get records first 50 volumes. + +GET /api/volumes/5 - get records only for volume with mediaid equal 5. + +GET /api/volumes/prune/5 - call prune action on volume with mediaid equal 5. + +GET /api/volumes/purge/5 - call purge action on volume with mediaid equal 5. + +GET /api/volumes/jobs/5 - get all jobs done on volume with mediaid equal 5.\\ + + +Errors: + +0 - No errors. + +1 - Invalid command. + +2 - Problem with connection to database. + +3 - Database access is not supported by this API instance. + +4 - Problem with connection to bconsole. + +5 - Invalid director. + +6 - Problem with authorization to Baculum API. + +7 - Access attempt to not allowed resource. Permission denied. + +30 - Volume with inputted mediaid does not exists. + +1000 - Internal error. + +\subsection{Pools} + +GET /api/pools/ - get records all pools. + +GET /api/pools/limit/15 - get records first 15 pools. + +GET /api/pools/7 - get records only for pool with poolid equal 7. + +GET /api/pools/show - get 'show pools' bconsole command. + +GET /api/pools/show/7 - get 'show pool=xxx' bconsole command for pool with poolid equal 7. + +PUT /api/pools/update/7 - call 'update pool=xxx' bconsole command for pool with poolid equal 7.\\ + + +Errors: + +0 - No errors. + +1 - Invalid command. + +2 - Problem with connection to database. + +3 - Database access is not supported by this API instance. + +4 - Problem with connection to bconsole. + +5 - Invalid director. + +6 - Problem with authorization to Baculum API. + +7 - Access attempt to not allowed resource. Permission denied. + +40 - Pool with inputted poolid does not exists. + +1000 - internal error.\\ + +\subsection{Jobs} + +GET /api/jobs/ - get records all jobs. + +GET /api/jobs/limit/20 - get records first 20 jobs. + +GET /jobs/8 - get records only for job with jobid equal 8. + +POST /jobs/estimate/ - call estimate action on a job. + +POST /jobs/run/ - call run action on job (run job). + +POST /jobs/restore/ - call restore action. + +DELETE /jobs/8 - delete by bconsole job with jobid equal 8.\\ + +Errors: + +0 - No errors. + +1 - Invalid command. + +2 - Problem with connection to database. + +3 - Database access is not supported by this API instance. + +4 - Problem with connection to bconsole. + +5 - Invalid director. + +6 - Problem with authorization to Baculum API. + +7 - Access attempt to not allowed resource. Permission denied. + +50 - Job with inputted jobid does not exist. + +51 - Inputed job level is invalid. + +52 - Fileset resource with inputted filesetid does not exist. + +53 - Client with inputted clientid does not exist. + +54 - Storage with inputted storageid does not exist. + +55 - Pool with inputted poolid does not exist. + +56 - [restore only] inputted rpath for restore is invalid. Proper format +is b2[0-9]+. + +57 - [restore only] inputted "where" option is invalid. + +58 - [restore only] inputted "replace" option is invalid. + +1000 - internal error.\\ + +\subsection{Bvfs} + +GET /api/bvfs/lsdirs/9/?path=\%2Fhome\%2F - listing from Bvfs cache directories +for jobid equal 9 and path equal /home/. URL-encoded path with ending slash +is necessary. + +GET /api/bvfs/lsdirs/9/limit/250/?path=\%2Fhome\%2f - listing from Bvfs cache +directories limited to 250 elements for jobid equal 9 and path equal /home/. +URL-encoded path with ending slash is necessary. + +GET /api/bvfs/lsdirs/9/limit/250/100/?path=\%2fhome\%2f - listing from Bvfs +cache directories limited to 250 elements with offset equal 100 for jobid +equal 9 and path equal /home/. URL-encoded path with ending slash is necessary. + +GET /api/bvfs/lsfiles/9/?path=\%2fhome\%2f - listing from Bvfs cache files for +jobid equal 9 and path equal /home/. URL-encoded path with ending slash is +necessary. + +GET /api/bvfs/lsfiles/9/limit/60/?path=\%2fhome\%2f - listing from Bvfs cache +files limited to 60 elements for jobid equal 9 and path equal /home/. +URL-encoded path with ending slash is necessary. + +GET /api/bvfs/lsfiles/9/limit/120/60/?path=\%2fhome\%2f - listing from Bvfs +cache files limited to 120 elements with offset equal 60 for jobid equal +9 and path equal /home/. URL-encoded path with ending slash is necessary. + +GET /api/bvfs/versions/abc-fd/123/456/789/ - listing from Bvfs cache all +files versions for client named abc-fd, for jobid equal 123, for pathid +equal 456 and for filenameid equal 789. URL-encoded client name is necessary. + +GET /api/bvfs/getjobids/9/ - listing from Bvfs cache all elementary jobids which + are necessary for restore all files from job with jobid equal 9 (eg. if jobid 9 + is job type incremental or differential). + +PUT /api/bvfs/update/9 - updating Bvfs cache for jobid equal 9. + +PUT /api/bvfs/update/9,10,22 - updating Bvfs cache for jobids equal 9, 10 and 22. + +POST /api/bvfs/restore/ - preparing Bvfs paths for restore command. + +PUT /api/bvfs/clear/ - call '.bvfs\_clear\_cache yes' bconsole command.\\ + + +Errors: + +0 - No errors. + +1 - Invalid command. + +2 - Problem with connection to database. + +3 - Database access is not supported by this API instance. + +4 - Problem with connection to bconsole. + +5 - Invalid director. + +6 - Problem with authorization to Baculum API. + +7 - Access attempt to not allowed resource. Permission denied. + +70 - Job with inputted jobid does not exist. + +71 - Inputted path for restore is invalid. Proper format is b2[0-9]+. + +1000 - Internal error. + \section{Installation from the Source Tar File} You may also install Baculum from the source bacula-gui tar archive. @@ -336,13 +742,15 @@ cd ./web/baculum/ Then please run (depending on used distribution): -For rpm-based distributions (example with /tmp/baculum-runtime destination directory): +For rpm-based distributions (example with /tmp/baculum-runtime destination +directory): \begin{verbatim} make build DESTDIR=/tmp/baculum-runtime \end{verbatim} -For deb-based distributions (example with /tmp/baculum-runtime destination directory): +For deb-based distributions (example with /tmp/baculum-runtime destination +directory): \begin{verbatim} make build DESTDIR=/tmp/baculum-release SAMPLETYPE=deb-template \ @@ -373,13 +781,17 @@ symbolic links must be created as shown below: /usr/share/locale/pt/LC_MESSAGES/baculum.mo => /tmp/baculum-runtime/usr/share/baculum/htdocs/protected/Lang/pt/baculum.mo + +/usr/share/locale/ja/LC_MESSAGES/baculum.mo + => /tmp/baculum-runtime/usr/share/baculum/htdocs/protected/Lang/ja/baculum.mo \end{verbatim} Please also update the symbolic link to the Baculum settings directory in -the following path: +the following paths: \begin{verbatim} -/tmp/baculum-runtime/usr/share/baculum/htdocs/protected/Data +/tmp/baculum-runtime/usr/share/baculum/htdocs/protected/API/Config +/tmp/baculum-runtime/usr/share/baculum/htdocs/protected/Web/Config \end{verbatim} Other files are: web servers configuration files, systemd units, SELinux @@ -391,102 +803,89 @@ to the files and directories listed below: \begin{verbatim} ./baculum/assets/ -./baculum/protected/Data/ -./baculum/protected/Data/baculum.users +./baculum/protected/Web/Config +./baculum/protected/API/Config +./baculum/protected/Web/baculum.users +./baculum/protected/API/baculum.users ./baculum/protected/runtime/ \end{verbatim} +\section{OAuth2 authorization} -\section{Users and Restricted Consoles} - -Baculum supports customized and restricted consoles for each logged in user. +Baculum API can use OAuth2 for authorization and authentication. -General design permits one administrator and many users. For each -user it is possible to define a unique bconsole configuration file that will -allow the user access to specific resources only. +To obtain tokens there is used {\bf Authorization Code Grant} flow. +Authorization and access token URLs are as follows: -Resources limitation is realized by using Bacula Restricted Consoles -functionality. +\begin{verbatim} +Authorization URL: /api/auth/ +Access Token URL: /api/token/ +\end{verbatim} -Before using customized and restricted consoles with Baculum please check -the location for bconsole configuration files for each user. To do so, -please run the configuration wizard and then to go to "Console" wizard step -(fourth step). +Baculum API doesn't use refresh tokens. After expiration token the client +application has to re-authorize again. -In the "Console" wizard step there is a field "Bconsole custom config file -path". In this field you must define a location for restricted -consoles. In the defined path exists keyword \textbf{\{user\}}. -During login, Baculum will replace this keyword with the logged in -username. This permits using a single directory which contains -a different bconsole-xxx.conf for each user (where xxx is replaced by the -user login name. +Default expiration time for authorization code is 7 seconds, for access +token 60 seconds. These values are changed in: -For example, if there the user named "john", is logging in, Baculum -will replace the keyword \{user\} with {\bf john}. +\begin{verbatim} +/usr/share/baculum/htdocs/protected/Common/Class/OAuth2.php +\end{verbatim} -Example: +in constants AUTHORIZATION\_ID\_EXPIRES\_TIME and ACCESS\_TOKEN\_EXPIRES\_TIME. -"Bconsole custom config file path" is defined as: +Default OAuth2 callback URL in Baculum Web is following: \begin{verbatim} -/usr/local/bacula/etc/bconsole-{user}.conf +https://baculumgui:9095/web/redirect \end{verbatim} -Thus for user "john", Baculum will use the following file for -each access to bconsole: +\subsection{Before running OAuth2} -\begin{verbatim} -/usr/local/bacula/etc/bconsole-john.conf -\end{verbatim} +{\bf Important note before using OAuth2} -The permits defining user specific Console access (or restricted -access) for each Baculum user. +When you decide to use OAuth2, you must change default HTTP Basic authorization +setting. Otherwise OAuth2 will not work. It is for enabling OAuth2 acces for +/api/ endpoints but still keep HTTP Basic protection for the Baculum API panel +pages. -Note that it is possible to create users and which bconsole file -will be accessed using Baculum, but it is not currently possible -to use Baculum to create the bconsole configuration files. -For this reason please prepare -bconsole configuration files for each regular (non-administrator) user -and check the access by logging in to Baculum as the new user. +For Apache the change is about switching in Baculum API Apache config +the Location tag from / to /api/page. -For Baculum to work work correctly some Bconsole commands are necessary. -They are: +\begin{verbatim} +# NOTE: When you use OAuth2 then change this location section +# From: +# To: +# + + AuthType Basic + AuthName "Baculum Auth" + AuthUserFile /usr/share/baculum/htdocs/protected/API/Config/baculum.users + Require valid-user + +\end{verbatim} -\begin{itemize} -\item show -\item .client -\item .jobs -\item .fileset -\item .pool -\item .storage -\item .jobs -\item .bvfs\_update -\item .bvfs\_lsdirs -\item .bvfs\_lsfiles -\item .bvfs\_versions -\item .bvfs\_get\_jobids -\item .bvfs\_restore -\item restore -\end{itemize} -Example configuration of the Restricted Console can look like below: +For Lighttpd the change is about uncommenting in API Lighttpd config lines as +described in comment below. \begin{verbatim} -Console { - Name = "BaculaRestrictedUser" - Password = "XXXXXXXXX" - CommandACL = run,show,.client,.jobs,.fileset,.pool,.storage,.jobs,.bvfs_update, -.bvfs_lsdirs,.bvfs_lsfiles,.bvfs_versions,.bvfs_get_jobids,.bvfs_restore,restore - CatalogACL = *all* - ClientACL = user-fd - JobACL = somejob1,userjob - PoolACL = Full-Pool - StorageACL = VTL - FileSetACL = somejob1-fileset,userjobFileSet3 - WhereACL = *all* -} +# +# Uncomment this line and closing braces below when you use OAuth2 +# +# $HTTP["url"] =~ "^/web/page/.*$" { + 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{Screenshots} \includegraphics[width=\linewidth]{baculum01.png} @@ -510,3 +909,7 @@ Console { \smallskip \includegraphics[width=\linewidth]{baculum06.png} + +\smallskip + +\includegraphics[width=\linewidth]{baculum07.png} -- 2.39.5