%%
%%
-\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
\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.
\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:
\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:
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:
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.
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 \
/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
\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: <Location />
+# To: <Location /api/page>
+#
+<Location />
+ AuthType Basic
+ AuthName "Baculum Auth"
+ AuthUserFile /usr/share/baculum/htdocs/protected/API/Config/baculum.users
+ Require valid-user
+</Location>
+\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}
\smallskip
\includegraphics[width=\linewidth]{baculum06.png}
+
+\smallskip
+
+\includegraphics[width=\linewidth]{baculum07.png}
projects / bacula / docs / commitdiff