4 \chapter{Baculum API and Web GUI Tools}
7 This chapter presents the Bacula Web based interface that has been added to
8 the Bacula project for version 7.0 and later.
10 \section{Base Features}
12 Baculum provides the following base features:
15 \item Running Bacula jobs (backup, restore, verify...).
16 \item Baculum API with OAuth2 authorization and HTTP Basic authentication
17 \item Baculum Web GUI interface
18 \item Configuring Bacula on local and remote hosts
19 \item Monitoring Bacula service status.
20 \item Bacula console available via a Web window.
21 \item Multi-user interface.
22 \item Support for customized and restricted consoles (Console ACL function).
23 \item Volume management.
24 \item User friendly graphs and metrics.
25 \item Basic storage daemon operations (mount, umount, release, ...).
26 \item Easy to use configuration and restore wizards.
27 \item Multiple Director support.
28 \item Live AJAX based statuses.
31 \section{General Requirements}
33 Environment for Baculum Web installation should have following components
37 \item A Web Server - with mod\_rewrite module loaded. Baculum Web has been
38 tested with Apache and Lighttpd web servers.
39 \item PHP 5.3.4 or higher with following modules installed:
41 \item cURL PHP module.
42 \item MB String PHP module.
43 \item JSON PHP module.
47 Environment for Baculum API installation should have following components
51 \item A Web Server - with mod\_rewrite module loaded. Baculum has been
52 tested with Apache and Lighttpd web servers.
53 \item PHP 5.3.4 or higher with following modules installed:
55 \item PDO PHP support - depending on your catalog database: PDO PostgreSQL
56 or PDO MySQL. Note, in case using MySQL database there is required to use MySQL
57 native driver. It is php-mysqlnd for PHP, not php-mysql.
58 \item BCMath PHP module.
59 \item JSON PHP module.
61 \item A working Bacula bconsole - configured Bacula text based console
62 \item Direct access to the Bacula Catalog database (local or remote)
66 With installation from binary packages (deb, rpm) all requirements
67 will be automatically installed as packages dependencies.
69 \section{Installation Baculum API from rpm binary packages}
72 Baculum API and Baculum Web version 9.0.0 are Beta version and before start using
73 them, please backup your Bacula configuration in safe place. It is specially
74 important because on first save config action the Bacula configuration is joined
75 into one file per Bacula component.\\
77 For rpm binary there are the following packages:
80 \item baculum-api - main Baculum API package with application files
81 \item baculum-api-httpd - Apache web server configuration files for Baculum API
82 \item baculum-api-lighttpd - Lighttpd web server configuration files for Baculum API
83 \item baculum-common - Common files for Baculum API and Baculum Web
84 \item baculum-web - main Baculum Web package with application files
85 \item baculum-web-httpd - Apache web server configuration files for Baculum Web
86 \item baculum-web-lighttpd - Lighttpd web server configuration files for Baculum Web
89 \subsection{Add the Baculum rpm repository}
91 To add the Baculum repository, first you must import the Baculum public key:
94 rpm --import http://bacula.org/downloads/baculum/baculum.pub
97 Once the key is imported, the next step is to add the repository
98 definition. First you must create the following file:
101 /etc/yum.repos.d/baculum.repo
104 The for CentOS 7, put the following in the file just created:
108 name=Baculum Beta CentOS repository
109 baseurl=http://bacula.org/downloads/baculum/beta/centos
114 For Fedora 25 the {\bf bacula.repo} file should have the following contents:
118 name=Baculum Beta Fedora repository
119 baseurl=http://bacula.org/downloads/baculum/beta/fedora
124 \subsection{Installation for the Apache}
126 Install the Baculum API for the Apache Web server as follows:
129 yum install baculum-common baculum-api baculum-api-httpd
132 Restart your Apache Web server:
135 service httpd restart
139 \subsection{Installation for Lighttpd}
141 Installation on system with access via Lighttpd is as follows
144 yum install baculum-common baculum-api baculum-api-lighttpd
147 Please note that in case CentOS distribution the Lighttpd web server is
148 available in the distribution packages after enabling the EPEL repository.
150 Start Baculum as application using the Lighttpd Web server:
153 service baculum-api-lighttpd start
156 \subsection{Access to bconsole via sudo for Apache and Lighttpd}
158 Baculum API requires access to Bconsole and to Bacula JSON programs.
159 To configure Bconsole sudo access and the Bacula JSON programs access
160 there can use following entries in newly created Baculum sudoers.d file
161 (usually in path /etc/sudoers.d/baculum):\\
163 In case default Apache user, the file contents must be:
166 Defaults:apache !requiretty
167 apache ALL=NOPASSWD: /usr/sbin/bconsole
168 apache ALL=NOPASSWD: /usr/sbin/bdirjson
169 apache ALL=NOPASSWD: /usr/sbin/bsdjson
170 apache ALL=NOPASSWD: /usr/sbin/bfdjson
171 apache ALL=NOPASSWD: /usr/sbin/bbconsjson
174 In case default Lighttpd user the file contents must be:
177 Defaults:lighttpd !requiretty
178 lighttpd ALL=NOPASSWD: /usr/sbin/bconsole
179 lighttpd ALL=NOPASSWD: /usr/sbin/bdirjson
180 lighttpd ALL=NOPASSWD: /usr/sbin/bsdjson
181 lighttpd ALL=NOPASSWD: /usr/sbin/bfdjson
182 lighttpd ALL=NOPASSWD: /usr/sbin/bbconsjson
185 \section{Installation Baculum API from deb binary packages}
188 Baculum API and Baculum Web version 9.0.0 are Beta version and before start using
189 them, please backup your Bacula configuration in safe place. It is specially
190 important because on first save config action the Bacula configuration is joined
191 into one file per Bacula component.\\
193 For deb binary there are the following packages:
196 \item baculum-api - main Baculum API package with application files
197 \item baculum-api-apache2 - Apache web server configuration files for Baculum API
198 \item baculum-api-lighttpd - Lighttpd web server configuration files for Baculum API
199 \item baculum-common - Common files for Baculum API and Baculum Web
200 \item baculum-web - main Baculum Web package with application files
201 \item baculum-web-apache2 - Apache web server configuration files for Baculum Web
202 \item baculum-web-lighttpd - Lighttpd web server configuration files for Baculum Web
205 \subsection{Add the Baculum deb repository}
207 To add the Baculum repository, first import the Baculum public key:
210 wget -qO - http://bacula.org/downloads/baculum/baculum.pub | apt-key add -
213 Once the key is imported, the next step is to create
217 /etc/apt/sources.list.d/baculum.list
220 For Debian 8 Jessie the contents should be:
223 deb http://bacula.org/downloads/baculum/beta/debian jessie main
224 deb-src http://bacula.org/downloads/baculum/beta/debian jessie main
227 For Ubuntu 16.04 Xenial the contents should be:
229 deb [ arch=amd64 ] http://bacula.org/downloads/baculum/beta/ubuntu xenial main
230 deb-src http://bacula.org/downloads/baculum/beta/ubuntu xenial main
234 After adding repository definition, please refresh repository indexes:
239 \subsection{Installation for Apache}
241 To install Baculum API access via Apache Web server by using apt
242 packages manager use the command:
245 apt-get install baculum-common baculum-api baculum-api-apache2
248 Next you must enable mod\_rewrite module for Apache, with the
255 and include Baculum VirtualHost definition in the Apache configuration
262 The restart your Apache server with:
265 service apache2 restart
268 \subsection{Installation for Lighttpd}
270 Example installation with access via Lighttpd web server looks following:
273 apt-get install baculum-common baculum-api baculum-api-lighttpd
276 Start Baculum API as application available through Lighttpd web server:
279 service baculum-api-lighttpd start
282 \subsection{Access to bconsole via sudo for Apache and Lighttpd}
284 Baculum API requires access to Bconsole and to the Bacula JSON programs.
285 To configure Bconsole sudo access we strongly recommend that you create
286 a Baculum sudoers.d file, which should be in /etc/sudoers.d/baculum:
288 {\bf Note}, please define sudo for the Bacula JSON programs only when
289 you are going use Bacula configuration module in the Baculum.
291 Both for Apache and Lighttpd user the file contents can be:
294 Defaults:www-data !requiretty
295 www-data ALL=NOPASSWD: /usr/sbin/bconsole
296 www-data ALL=NOPASSWD: /usr/sbin/bdirjson
297 www-data ALL=NOPASSWD: /usr/sbin/bsdjson
298 www-data ALL=NOPASSWD: /usr/sbin/bfdjson
299 www-data ALL=NOPASSWD: /usr/sbin/bbconsjson
302 \section{Debugging your First Baculum API Login}
303 At each step of the initial login to Baculum, the
304 screen will have a test button that will allow you
305 to check to see if your parameters were correctly
306 entered. If not, you will see error message on the
307 wizard page. You can also get additional detail by
308 examining the Apache error log, that is usually
312 /var/log/httpd/baculum-api-error.log
315 If you use Lighttpd thento get additional detail you can check:
318 /var/log/lighttpd/baculum-api-error.log
321 In addition, special debug output is placed by Baculum in
325 /usr/share/baculum/htdocs/protected/API/Logs/baculum-api.log
328 The debug you can enable in file:
330 /usr/share/baculum/htdocs/protected/API/Config/api.conf
333 by switching in [api] section option debug to "1".
335 With the information in those two files, you can usually quickly
336 find and correct most problems.
340 \section{Installation Baculum Web from rpm binary packages}
342 \subsection{Installation for the Apache}
344 Install the Baculum Web for the Apache Web server as follows:
347 yum install baculum-common baculum-web baculum-web-httpd
350 Restart your Apache Web server:
353 service httpd restart
356 \subsection{Installation for Lighttpd}
358 Installation on system with access via Lighttpd is as follows
361 yum install baculum-common baculum-web baculum-web-lighttpd
364 Please note that in case CentOS distribution the Lighttpd web server is
365 available in the distribution packages after enabling the EPEL repository.
367 Start Baculum as application using the Lighttpd Web server:
370 service baculum-web-lighttpd start
373 \section{Installation Baculum Web from deb binary packages}
375 \subsection{Installation for Apache}
377 To install Baculum Web access via Apache Web server by using apt
378 packages manager use the command:
381 apt-get install baculum-common baculum-web baculum-web-apache2
384 Next you must enable mod\_rewrite module for Apache, with the
391 and include Baculum VirtualHost definition in the Apache configuration
398 The restart your Apache server with:
401 service apache2 restart
404 \subsection{Installation for Lighttpd}
406 Example installation with access via Lighttpd web server looks following:
409 apt-get install baculum-common baculum-web baculum-web-lighttpd
412 Start Baculum Web as application available through Lighttpd web server:
415 service baculum-web-lighttpd start
418 \section{Running Baculum API and Web for the First Time}
420 \subsection{Running Baculum API}
422 Access to Baculum API from web browser: \textbf{http://localhost:9096}
424 First time login: \textbf{admin}
426 First time password: \textbf{admin}
429 \subsection{Running Baculum Web}
431 Access to Baculum Web from web browser: \textbf{http://localhost:9095}
433 First time login: \textbf{admin}
435 First time password: \textbf{admin}
437 \section{Installation wizards}
439 \textbf{Installation with HTTP Basic authentication}
441 \includegraphics[width=\linewidth]{baculum_install_basic.png}
445 \textbf{Installation with OAuth2 authorization}
447 \includegraphics[width=\linewidth]{baculum_install_oauth2.png}
451 \section{Baculum API endpoints}
455 GET /api/clients - get records all clients
457 GET /api/clients/limit/4 - get records first 4 clients
459 GET /api/clients/2 - get records only for client with clientid equal 2
461 GET /api/clients/show - get 'show clients' bconsole command
463 GET /api/clients/show/2 - get 'show client=xxx' bconsole command for client with clientid equal 2
465 GET /api/clients/status/2 - get 'status client=xxx' bconsole command for client with clientid equal 2
467 GET /api/clients/jobs/2 - get all jobs done by client with clientid equal 2\\
476 2 - Problem with connection to database.
478 3 - Database access is not supported by this API instance.
480 4 - Problem with connection to bconsole.
482 5 - Invalid director.
484 6 - Problem with authorization to Baculum API.
486 7 - Access attempt to not allowed resource. Permission denied.
488 10 - Client with inputted clientid does not exists.
490 1000 - Internal error.
492 \subsection{Storages}
494 GET /api/storages/ - get records all storages.
496 GET /api/storages/limit/25 - get records first 25 storages.
498 GET /api/storages/3 - get records only for storage with storageid equal 3.
500 GET /api/storages/show - get 'show storages' bconsole command.
502 GET /api/storages/show/3 - get 'show storage=xxx' bconsole command for storage with storageid equal 3.
504 GET /api/storages/status/3 - get 'status storage=xxx' bconsole command for storage with storageid equal 3.
506 GET /api/storages/mount/3/2/17 - mount storage with storageid equal 3, drive number 2 and volume in slot number 17.
508 GET /api/storages/umount/3/1 - umount storage with storageid equal 3 and drive number 1.
510 GET /api/storages/release/3 - release storage with storageid equal 3.\\
519 2 - Problem with connection to database.
521 3 - Database access is not supported by this API instance.
523 4 - Problem with connection to bconsole.
525 5 - Invalid director.
527 6 - Problem with authorization to Baculum API.
529 7 - Access attempt to not allowed resource. Permission denied.
531 20 - Storage with inputted storageid does not exists.
533 1000 - Internal error.
537 GET /api/volumes/ - get records all volumes.
539 GET /api/volumes/limit/50 - get records first 50 volumes.
541 GET /api/volumes/5 - get records only for volume with mediaid equal 5.
543 GET /api/volumes/prune/5 - call prune action on volume with mediaid equal 5.
545 GET /api/volumes/purge/5 - call purge action on volume with mediaid equal 5.
547 GET /api/volumes/jobs/5 - get all jobs done on volume with mediaid equal 5.\\
556 2 - Problem with connection to database.
558 3 - Database access is not supported by this API instance.
560 4 - Problem with connection to bconsole.
562 5 - Invalid director.
564 6 - Problem with authorization to Baculum API.
566 7 - Access attempt to not allowed resource. Permission denied.
568 30 - Volume with inputted mediaid does not exists.
570 1000 - Internal error.
574 GET /api/pools/ - get records all pools.
576 GET /api/pools/limit/15 - get records first 15 pools.
578 GET /api/pools/7 - get records only for pool with poolid equal 7.
580 GET /api/pools/show - get 'show pools' bconsole command.
582 GET /api/pools/show/7 - get 'show pool=xxx' bconsole command for pool with poolid equal 7.
584 PUT /api/pools/update/7 - call 'update pool=xxx' bconsole command for pool with poolid equal 7.\\
593 2 - Problem with connection to database.
595 3 - Database access is not supported by this API instance.
597 4 - Problem with connection to bconsole.
599 5 - Invalid director.
601 6 - Problem with authorization to Baculum API.
603 7 - Access attempt to not allowed resource. Permission denied.
605 40 - Pool with inputted poolid does not exists.
607 1000 - internal error.\\
611 GET /api/jobs/ - get records all jobs.
613 GET /api/jobs/limit/20 - get records first 20 jobs.
615 GET /jobs/8 - get records only for job with jobid equal 8.
617 POST /jobs/estimate/ - call estimate action on a job.
619 POST /jobs/run/ - call run action on job (run job).
621 POST /jobs/restore/ - call restore action.
623 DELETE /jobs/8 - delete by bconsole job with jobid equal 8.\\
631 2 - Problem with connection to database.
633 3 - Database access is not supported by this API instance.
635 4 - Problem with connection to bconsole.
637 5 - Invalid director.
639 6 - Problem with authorization to Baculum API.
641 7 - Access attempt to not allowed resource. Permission denied.
643 50 - Job with inputted jobid does not exist.
645 51 - Inputed job level is invalid.
647 52 - Fileset resource with inputted filesetid does not exist.
649 53 - Client with inputted clientid does not exist.
651 54 - Storage with inputted storageid does not exist.
653 55 - Pool with inputted poolid does not exist.
655 56 - [restore only] inputted rpath for restore is invalid. Proper format
658 57 - [restore only] inputted "where" option is invalid.
660 58 - [restore only] inputted "replace" option is invalid.
662 1000 - internal error.\\
666 GET /api/bvfs/lsdirs/9/?path=\%2Fhome\%2F - listing from Bvfs cache directories
667 for jobid equal 9 and path equal /home/. URL-encoded path with ending slash
670 GET /api/bvfs/lsdirs/9/limit/250/?path=\%2Fhome\%2f - listing from Bvfs cache
671 directories limited to 250 elements for jobid equal 9 and path equal /home/.
672 URL-encoded path with ending slash is necessary.
674 GET /api/bvfs/lsdirs/9/limit/250/100/?path=\%2fhome\%2f - listing from Bvfs
675 cache directories limited to 250 elements with offset equal 100 for jobid
676 equal 9 and path equal /home/. URL-encoded path with ending slash is necessary.
678 GET /api/bvfs/lsfiles/9/?path=\%2fhome\%2f - listing from Bvfs cache files for
679 jobid equal 9 and path equal /home/. URL-encoded path with ending slash is
682 GET /api/bvfs/lsfiles/9/limit/60/?path=\%2fhome\%2f - listing from Bvfs cache
683 files limited to 60 elements for jobid equal 9 and path equal /home/.
684 URL-encoded path with ending slash is necessary.
686 GET /api/bvfs/lsfiles/9/limit/120/60/?path=\%2fhome\%2f - listing from Bvfs
687 cache files limited to 120 elements with offset equal 60 for jobid equal
688 9 and path equal /home/. URL-encoded path with ending slash is necessary.
690 GET /api/bvfs/versions/abc-fd/123/456/789/ - listing from Bvfs cache all
691 files versions for client named abc-fd, for jobid equal 123, for pathid
692 equal 456 and for filenameid equal 789. URL-encoded client name is necessary.
694 GET /api/bvfs/getjobids/9/ - listing from Bvfs cache all elementary jobids which
695 are necessary for restore all files from job with jobid equal 9 (eg. if jobid 9
696 is job type incremental or differential).
698 PUT /api/bvfs/update/9 - updating Bvfs cache for jobid equal 9.
700 PUT /api/bvfs/update/9,10,22 - updating Bvfs cache for jobids equal 9, 10 and 22.
702 POST /api/bvfs/restore/ - preparing Bvfs paths for restore command.
704 PUT /api/bvfs/clear/ - call '.bvfs\_clear\_cache yes' bconsole command.\\
713 2 - Problem with connection to database.
715 3 - Database access is not supported by this API instance.
717 4 - Problem with connection to bconsole.
719 5 - Invalid director.
721 6 - Problem with authorization to Baculum API.
723 7 - Access attempt to not allowed resource. Permission denied.
725 70 - Job with inputted jobid does not exist.
727 71 - Inputted path for restore is invalid. Proper format is b2[0-9]+.
729 1000 - Internal error.
731 \section{Installation from the Source Tar File}
733 You may also install Baculum from the source bacula-gui tar archive.
735 To prepare Baculum runtime files one uses the Makefile file.
736 To do this, after unpacking bacula-gui archive please go to Baculum main
743 Then please run (depending on used distribution):
745 For rpm-based distributions (example with /tmp/baculum-runtime destination
749 make build DESTDIR=/tmp/baculum-runtime
752 For deb-based distributions (example with /tmp/baculum-runtime destination
756 make build DESTDIR=/tmp/baculum-release SAMPLETYPE=deb-template \
757 HTTPDNAME=apache2 HTTPDSITECONF=sites-available
760 After execution above command, in path /tmp/baculum-runtime should
761 contain all required runtime files.
763 The Base Baculum source files will be located in:
766 /tmp/baculum-runtime/usr/share/baculum/htdocs/
769 These are the files that should be placed in web server's document root (or
770 Virtual Host document root) directory.
772 Please note that for language files (including English)
773 symbolic links must be created as shown below:
776 /usr/share/locale/en/LC_MESSAGES/baculum.mo
777 => /tmp/baculum-runtime/usr/share/baculum/htdocs/protected/Lang/en/baculum.mo
779 /usr/share/locale/pl/LC_MESSAGES/baculum.mo
780 => /tmp/baculum-runtime/usr/share/baculum/htdocs/protected/Lang/pl/baculum.mo
782 /usr/share/locale/pt/LC_MESSAGES/baculum.mo
783 => /tmp/baculum-runtime/usr/share/baculum/htdocs/protected/Lang/pt/baculum.mo
785 /usr/share/locale/ja/LC_MESSAGES/baculum.mo
786 => /tmp/baculum-runtime/usr/share/baculum/htdocs/protected/Lang/ja/baculum.mo
789 Please also update the symbolic link to the Baculum settings directory in
793 /tmp/baculum-runtime/usr/share/baculum/htdocs/protected/API/Config
794 /tmp/baculum-runtime/usr/share/baculum/htdocs/protected/Web/Config
797 Other files are: web servers configuration files, systemd units, SELinux
798 policy module and others. Please select and copy appropriate files to your
799 system environment and edit their content if needed.
801 You must set read/write privileges for the Web server user
802 to the files and directories listed below:
806 ./baculum/protected/Web/Config
807 ./baculum/protected/API/Config
808 ./baculum/protected/Web/baculum.users
809 ./baculum/protected/API/baculum.users
810 ./baculum/protected/runtime/
813 \section{OAuth2 authorization}
815 Baculum API can use OAuth2 for authorization and authentication.
817 To obtain tokens there is used {\bf Authorization Code Grant} flow.
818 Authorization and access token URLs are as follows:
821 Authorization URL: /api/auth/
822 Access Token URL: /api/token/
825 Baculum API doesn't use refresh tokens. After expiration token the client
826 application has to re-authorize again.
828 Default expiration time for authorization code is 7 seconds, for access
829 token 60 seconds. These values are changed in:
832 /usr/share/baculum/htdocs/protected/Common/Class/OAuth2.php
835 in constants AUTHORIZATION\_ID\_EXPIRES\_TIME and ACCESS\_TOKEN\_EXPIRES\_TIME.
837 Default OAuth2 callback URL in Baculum Web is following:
840 https://baculumgui:9095/web/redirect
843 \subsection{Before running OAuth2}
845 {\bf Important note before using OAuth2}
847 When you decide to use OAuth2, you must change default HTTP Basic authorization
848 setting. Otherwise OAuth2 will not work. It is for enabling OAuth2 acces for
849 /api/ endpoints but still keep HTTP Basic protection for the Baculum API panel
852 For Apache the change is about switching in Baculum API Apache config
853 the Location tag from / to /api/page.
856 # NOTE: When you use OAuth2 then change this location section
858 # To: <Location /api/page>
862 AuthName "Baculum Auth"
863 AuthUserFile /usr/share/baculum/htdocs/protected/API/Config/baculum.users
869 For Lighttpd the change is about uncommenting in API Lighttpd config lines as
870 described in comment below.
874 # Uncomment this line and closing braces below when you use OAuth2
876 # $HTTP["url"] =~ "^/web/page/.*$" {
877 auth.backend = "htpasswd"
878 auth.backend.htpasswd.userfile = "/usr/share/baculum/htdocs/protected/API/Config/baculum.users"
879 auth.require = ( "/" => (
881 "realm" => "Baculum Auth",
882 "require" => "valid-user"
889 \section{Screenshots}
891 \includegraphics[width=\linewidth]{baculum01.png}
895 \includegraphics[width=\linewidth]{baculum02.png}
899 \includegraphics[width=\linewidth]{baculum03.png}
903 \includegraphics[width=\linewidth]{baculum04.png}
907 \includegraphics[width=\linewidth]{baculum05.png}
911 \includegraphics[width=\linewidth]{baculum06.png}
915 \includegraphics[width=\linewidth]{baculum07.png}