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.
620 +-----------------------------------------------------------------------------+
621 | /api/jobs/estimate/ POST request |
622 +-------------------+---------+-----------------------------------------------+
623 | Name | Type | Description |
624 +-------------------+---------+-----------------------------------------------+
625 | create[id] * | integer | job id to get job name for estimate purpose |
626 | | | (used instead job name) |
627 +-------------------+---------+-----------------------------------------------+
628 | create[name] * | string | job name to estimate (used instead of jobid) |
630 +-------------------+---------+-----------------------------------------------+
631 | create[fileset] * | string | FileSet resource name |
633 +-------------------+---------+-----------------------------------------------+
634 | create[level] * | string | Job level in short form. |
635 | | | One case sensitive letter: |
637 | | | I => Incremental |
638 | | | D => Differential |
640 | | | f => VirtualFull |
641 | | | V => InitCatalog |
643 | | | O => VolumeToCatalog |
644 | | | d => DiskToCatalog |
645 +-------------------+---------+-----------------------------------------------+
646 | create[clientid] *| integer | Client identifier |
647 | | | (used instead of client name) |
648 +-------------------+---------+-----------------------------------------------+
649 | create[client] * | string | Client name (used instead of client id) |
651 +-------------------+---------+-----------------------------------------------+
652 | create[accurate] *| integer | Enable accurate mode: 0 - no, 1 - yes |
654 +-------------------+---------+-----------------------------------------------+
659 POST /jobs/run/ - call run action on job (run job).
662 +-----------------------------------------------------------------------------+
663 | /api/jobs/run/ POST request |
664 +-------------------+---------+-----------------------------------------------+
665 | Name | Type | Description |
666 +-------------------+---------+-----------------------------------------------+
667 | create[id] * | integer | job id to get job name to run |
668 | | | (used instead job name) |
669 +-------------------+---------+-----------------------------------------------+
670 | create[name] * | string | job name to run (used instead of jobid) |
672 +-------------------+---------+-----------------------------------------------+
673 | create[level] * | string | Job level in short form. |
674 | | | One case sensitive letter: |
676 | | | I => Incremental |
677 | | | D => Differential |
679 | | | f => VirtualFull |
680 | | | V => InitCatalog |
682 | | | O => VolumeToCatalog |
683 | | | d => DiskToCatalog |
684 +-------------------+---------+-----------------------------------------------+
685 | create[fileset] * | string | FileSet resource name |
687 +-------------------+---------+-----------------------------------------------+
688 | create[clientid] *| integer | Client identifier |
689 | | | (used instead of client name) |
690 +-------------------+---------+-----------------------------------------------+
691 | create[client] * | string | Client name (used instead of client id) |
693 +-------------------+---------+-----------------------------------------------+
694 | create[storageid]*| integer | Storage identifier |
695 | | | (used instead of storage name) |
696 +-------------------+---------+-----------------------------------------------+
697 | create[storage] * | string | Storage name (used instead of storage id) |
699 +-------------------+---------+-----------------------------------------------+
700 | create[poolid] * | integer | Pool identifier (used instead of pool name) |
702 +-------------------+---------+-----------------------------------------------+
703 | create[pool] * | string | Pool name (used instead of pool id) |
705 +-------------------+---------+-----------------------------------------------+
706 | create[priority] | integer | Job priority to run |
708 +-------------------+---------+-----------------------------------------------+
709 | create[jobid] | integer | Job identifier for verify job |
711 +-------------------+---------+-----------------------------------------------+
712 | create[verifyjob] | string | Verify job name |
714 +-------------------+---------+-----------------------------------------------+
719 POST /jobs/restore/ - call restore action.
722 +-----------------------------------------------------------------------------+
723 | /api/jobs/restore/ POST request |
724 +-------------------+---------+-----------------------------------------------+
725 | Name | Type | Description |
726 +-------------------+---------+-----------------------------------------------+
727 | create[rpath] * | string | Bvfs temporary table name for restore purpose |
728 | | | in form: b2[0-9]+ |
729 +-------------------+---------+-----------------------------------------------+
730 | create[fileset] * | string | FileSet resource name |
732 +-------------------+---------+-----------------------------------------------+
733 | create[clientid] *| integer | Client identifier |
734 | | | (used instead of client name) |
735 +-------------------+---------+-----------------------------------------------+
736 | create[client] * | string | Client name (used instead of client id) |
738 +-------------------+---------+-----------------------------------------------+
739 | create[priority] | integer | Job priority to run |
741 +-------------------+---------+-----------------------------------------------+
742 | create[where] * | string | Destination directory for restored files |
744 +-------------------+---------+-----------------------------------------------+
745 | create[replace] * | string | Replace files in destination directory for |
746 | | | restored files. Available options: |
751 +-------------------+---------+-----------------------------------------------+
756 DELETE /jobs/8 - delete by bconsole job with jobid equal 8.\\
764 2 - Problem with connection to database.
766 3 - Database access is not supported by this API instance.
768 4 - Problem with connection to bconsole.
770 5 - Invalid director.
772 6 - Problem with authorization to Baculum API.
774 7 - Access attempt to not allowed resource. Permission denied.
776 50 - Job with inputted jobid does not exist.
778 51 - Inputed job level is invalid.
780 52 - Fileset resource does not exist.
782 53 - Client does not exist.
784 54 - Storage does not exist.
786 55 - Pool does not exist.
788 56 - [restore only] inputted rpath for restore is invalid. Proper format
791 57 - [restore only] inputted "where" option is invalid.
793 58 - [restore only] inputted "replace" option is invalid.
795 1000 - internal error.\\
799 GET /api/bvfs/lsdirs/9/?path=\%2Fhome\%2F - listing from Bvfs cache directories
800 for jobid equal 9 and path equal /home/. URL-encoded path with ending slash
803 GET /api/bvfs/lsdirs/9/limit/250/?path=\%2Fhome\%2f - listing from Bvfs cache
804 directories limited to 250 elements for jobid equal 9 and path equal /home/.
805 URL-encoded path with ending slash is necessary.
807 GET /api/bvfs/lsdirs/9/limit/250/100/?path=\%2fhome\%2f - listing from Bvfs
808 cache directories limited to 250 elements with offset equal 100 for jobid
809 equal 9 and path equal /home/. URL-encoded path with ending slash is necessary.
811 GET /api/bvfs/lsfiles/9/?path=\%2fhome\%2f - listing from Bvfs cache files for
812 jobid equal 9 and path equal /home/. URL-encoded path with ending slash is
815 GET /api/bvfs/lsfiles/9/limit/60/?path=\%2fhome\%2f - listing from Bvfs cache
816 files limited to 60 elements for jobid equal 9 and path equal /home/.
817 URL-encoded path with ending slash is necessary.
819 GET /api/bvfs/lsfiles/9/limit/120/60/?path=\%2fhome\%2f - listing from Bvfs
820 cache files limited to 120 elements with offset equal 60 for jobid equal
821 9 and path equal /home/. URL-encoded path with ending slash is necessary.
823 GET /api/bvfs/versions/abc-fd/123/456/789/ - listing from Bvfs cache all
824 files versions for client named abc-fd, for jobid equal 123, for pathid
825 equal 456 and for filenameid equal 789. URL-encoded client name is necessary.
827 GET /api/bvfs/getjobids/9/ - listing from Bvfs cache all elementary jobids which
828 are necessary for restore all files from job with jobid equal 9 (eg. if jobid 9
829 is job type incremental or differential).
831 PUT /api/bvfs/update/9 - updating Bvfs cache for jobid equal 9.
833 PUT /api/bvfs/update/9,10,22 - updating Bvfs cache for jobids equal 9, 10 and 22.
835 POST /api/bvfs/restore/ - preparing Bvfs paths for restore command.
838 +-----------------------------------------------------------------------------+
839 | /api/bvfs/restore/ POST request |
840 +-------------------+---------+-----------------------------------------------+
841 | Name | Type | Description |
842 +-------------------+---------+-----------------------------------------------+
843 | create[jobids] * | string | job identifiers comma separated |
845 +-------------------+---------+-----------------------------------------------+
846 | create[dirid] | string | directory identifiers comma separated |
848 +-------------------+---------+-----------------------------------------------+
849 | create[fileid] | string | file identifiers comma separated |
851 +-------------------+---------+-----------------------------------------------+
852 | create[path] * | string | temporary Bvfs table table name |
853 | | | in form b2[0-9]+ |
854 +-------------------+---------+-----------------------------------------------+
859 PUT /api/bvfs/clear/ - call '.bvfs\_clear\_cache yes' bconsole command.\\
868 2 - Problem with connection to database.
870 3 - Database access is not supported by this API instance.
872 4 - Problem with connection to bconsole.
874 5 - Invalid director.
876 6 - Problem with authorization to Baculum API.
878 7 - Access attempt to not allowed resource. Permission denied.
880 70 - Job with inputted jobid does not exist.
882 71 - Inputted path for restore is invalid. Proper format is b2[0-9]+.
884 1000 - Internal error.
886 \section{Installation from the Source Tar File}
888 You may also install Baculum from the source bacula-gui tar archive.
890 To prepare Baculum runtime files one uses the Makefile file.
891 To do this, after unpacking bacula-gui archive please go to Baculum main
898 Then please run (depending on used distribution):
900 For rpm-based distributions (example with /tmp/baculum-runtime destination
904 make build DESTDIR=/tmp/baculum-runtime
907 For deb-based distributions (example with /tmp/baculum-runtime destination
911 make build DESTDIR=/tmp/baculum-release SAMPLETYPE=deb-template \
912 HTTPDNAME=apache2 HTTPDSITECONF=sites-available
915 After execution above command, in path /tmp/baculum-runtime should
916 contain all required runtime files.
918 The Base Baculum source files will be located in:
921 /tmp/baculum-runtime/usr/share/baculum/htdocs/
924 These are the files that should be placed in web server's document root (or
925 Virtual Host document root) directory.
927 Please note that for language files (including English)
928 symbolic links must be created as shown below:
931 /usr/share/locale/en/LC_MESSAGES/baculum.mo
932 => /tmp/baculum-runtime/usr/share/baculum/htdocs/protected/Lang/en/baculum.mo
934 /usr/share/locale/pl/LC_MESSAGES/baculum.mo
935 => /tmp/baculum-runtime/usr/share/baculum/htdocs/protected/Lang/pl/baculum.mo
937 /usr/share/locale/pt/LC_MESSAGES/baculum.mo
938 => /tmp/baculum-runtime/usr/share/baculum/htdocs/protected/Lang/pt/baculum.mo
940 /usr/share/locale/ja/LC_MESSAGES/baculum.mo
941 => /tmp/baculum-runtime/usr/share/baculum/htdocs/protected/Lang/ja/baculum.mo
944 Please also update the symbolic link to the Baculum settings directory in
948 /tmp/baculum-runtime/usr/share/baculum/htdocs/protected/API/Config
949 /tmp/baculum-runtime/usr/share/baculum/htdocs/protected/Web/Config
952 Other files are: web servers configuration files, systemd units, SELinux
953 policy module and others. Please select and copy appropriate files to your
954 system environment and edit their content if needed.
956 You must set read/write privileges for the Web server user
957 to the files and directories listed below:
961 ./baculum/protected/Web/Config
962 ./baculum/protected/API/Config
963 ./baculum/protected/Web/baculum.users
964 ./baculum/protected/API/baculum.users
965 ./baculum/protected/runtime/
968 \section{OAuth2 authorization}
970 Baculum API can use OAuth2 for authorization and authentication.
972 To obtain tokens there is used {\bf Authorization Code Grant} flow.
973 Authorization and access token URLs are as follows:
976 Authorization URL: /api/auth/
977 Access Token URL: /api/token/
980 Baculum API doesn't use refresh tokens. After expiration token the client
981 application has to re-authorize again.
983 Default expiration time for authorization code is 7 seconds, for access
984 token 60 seconds. These values are changed in:
987 /usr/share/baculum/htdocs/protected/Common/Class/OAuth2.php
990 in constants AUTHORIZATION\_ID\_EXPIRES\_TIME and ACCESS\_TOKEN\_EXPIRES\_TIME.
992 Default OAuth2 callback URL in Baculum Web is following:
995 https://baculumgui:9095/web/redirect
998 \subsection{Before running OAuth2}
1000 {\bf Important note before using OAuth2}
1002 When you decide to use OAuth2, you must change default HTTP Basic authorization
1003 setting. Otherwise OAuth2 will not work. It is for enabling OAuth2 acces for
1004 /api/ endpoints but still keep HTTP Basic protection for the Baculum API panel
1007 For Apache the change is about switching in Baculum API Apache config
1008 the Location tag from / to /api/page.
1011 # NOTE: When you use OAuth2 then change this location section
1012 # From: <Location />
1013 # To: <Location /api/page>
1017 AuthName "Baculum Auth"
1018 AuthUserFile /usr/share/baculum/htdocs/protected/API/Config/baculum.users
1024 For Lighttpd the change is about uncommenting in API Lighttpd config lines as
1025 described in comment below.
1029 # Uncomment this line and closing braces below when you use OAuth2
1031 # $HTTP["url"] =~ "^/web/page/.*$" {
1032 auth.backend = "htpasswd"
1033 auth.backend.htpasswd.userfile = "/usr/share/baculum/htdocs/protected/API/Config/baculum.users"
1034 auth.require = ( "/" => (
1035 "method" => "basic",
1036 "realm" => "Baculum Auth",
1037 "require" => "valid-user"
1044 \section{Screenshots}
1046 \includegraphics[width=\linewidth]{baculum01.png}
1050 \includegraphics[width=\linewidth]{baculum02.png}
1054 \includegraphics[width=\linewidth]{baculum03.png}
1058 \includegraphics[width=\linewidth]{baculum04.png}
1062 \includegraphics[width=\linewidth]{baculum05.png}
1066 \includegraphics[width=\linewidth]{baculum06.png}
1070 \includegraphics[width=\linewidth]{baculum07.png}