From 518ec351efeea9f8a39d930b258478080723bd1f Mon Sep 17 00:00:00 2001 From: Kern Sibbald Date: Mon, 1 Aug 2016 12:10:07 +0200 Subject: [PATCH] Update Baculum section of console manual --- docs/manuals/en/console/baculum.tex | 268 ++++++++++++++++------------ docs/upload | 2 +- 2 files changed, 159 insertions(+), 111 deletions(-) diff --git a/docs/manuals/en/console/baculum.tex b/docs/manuals/en/console/baculum.tex index d0cc33a6..e4a87c6f 100644 --- a/docs/manuals/en/console/baculum.tex +++ b/docs/manuals/en/console/baculum.tex @@ -1,37 +1,38 @@ %% %% -\chapter{Baculum WebGUI Tool} +\chapter{Baculum Web GUI Tool} \label{BaculumChapter} -This chapter presents the new Bacula web based interface that has been added to -the Bacula projects in version 7.0 and later. +This chapter presents the Bacula Web based interface that has been added to +the Bacula project for version 7.0 and later. \section{Base Features} -Baculum provides following base features: +Baculum provides the following base features: \begin{itemize} \item Running Bacula jobs (backup, restore, verify...). -\item Monitoring Bacula services status. -\item Bacula console available via web interface. -\item Multi-users interface. +\item Monitoring Bacula service status. +\item Bacula console available via a Web window. +\item Multi-user interface. \item Support for customized and restricted consoles (Console ACL function). -\item Volumes management. +\item Volume management. \item User friendly graphs and metrics. -\item Basic storage daemon operations (mount, umount, release actions). -\item Easy in use configuration and restore wizards. -\item Multiple Directors support. +\item Basic storage daemon operations (mount, umount, release, ...). +\item Easy to use configuration and restore wizards. +\item Multiple Director support. \item Live AJAX based statuses. \end{itemize} \section{General Requirements} -Environment for Baculum installation should have following components installed: +Environment for Baculum installation should have following components +installed: \begin{itemize} -\item Web Server - with mod\_rewrite module loaded. Baculum has been tested with -Apache, Nginx and Lighttpd web servers. +\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: \begin{itemize} \item PDO PHP support - depending on your catalog database: PDO PostgreSQL @@ -42,20 +43,20 @@ native driver. It is php-mysqlnd for PHP, not php-mysql. \item MB String PHP module. \item JSON PHP module. \end{itemize} -\item Bconsole - configured Bacula text based console -\item Access to Bacula Catalog database (local or remote) +\item A working Bacula bconsole - configured Bacula text based console +\item Direct access to the Bacula Catalog database (local or remote) \end{itemize} -All above requirements are validated during Baculum start. If in installation -environment there occurs lack some from these components then you will be -informed about this fact. +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. -In case installation from binary packages (deb, rpm) all requirements are -installed automatically as packages dependencies. +With installation from binary packages (deb, rpm) all requirements +will be automatically installed as packages dependencies. \section{Installation from rpm binary packages} -For rpm binary packages format there exist following packages: +For rpm binary there are the following packages: \begin{itemize} \item baculum - main package with application files @@ -64,22 +65,25 @@ For rpm binary packages format there exist following packages: \item baculum-lighttpd - Lighttpd web server configuration files \end{itemize} -\subsection{Add rpm repository} +You must install at a minimum the {\bf baculum} package and either +baculum-http or {\bf baculum-lighttpd}. -To add Baculum repository, first is required importing public key: +\subsection{Add the Bacula rpm repository} + +To add the Baculum repository, first you must import the Baculum public key: \begin{verbatim} rpm --import http://bacula.org/downloads/baculum/baculum.pub \end{verbatim} -Once importing the key is done, next step is adding repository definition to -newly created file: +Once the key is imported, the next step is to add the repository +definition. First you must create the following file: \begin{verbatim} /etc/yum.repos.d/baculum.repo \end{verbatim} -For CentOS 7 the definition is: +The for CentOS 7, put the following in the file just created: \begin{verbatim} [baculumrepo] @@ -89,7 +93,7 @@ gpgcheck=1 enabled=1 \end{verbatim} -For Fedora 23 the definition is: +For Fedora 23 the {\bf bacula.repo} file should have the following contents: \begin{verbatim} [baculumrepo] @@ -99,73 +103,121 @@ gpgcheck=1 enabled=1 \end{verbatim} -\subsection{Installation for Apache} +\subsection{Installation for the Apache Web server} -Example installation for access via Apache web server can look like below: +Install Baculum for the Apache Web server as follows: \begin{verbatim} yum install baculum baculum-httpd \end{verbatim} -Start Baculum as application available through Apache web server: +Restart your Apache Web server: \begin{verbatim} service httpd restart \end{verbatim} -Access from web browser: \textbf{http://localhost:9095} +\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): + +In case default user both for Apache and Lighttpd: + +\begin{verbatim} +Defaults:web-user !requiretty +web-user ALL=NOPASSWD: /usr/sbin/bconsole +\end{verbatim} + +Where {\bf web-user} must be replaced by the Linux +username under which your Web server is running. + +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}. + +\subsection{Running Baculum for the First Time} +Access Baculum from a Web browser: \textbf{http://localhost:9095} First time login: \textbf{admin} First time password: \textbf{admin} +\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: + +\begin{verbatim} +/var/log/apache2/error.log +\end{verbatim} + +In addition, special debug output is placed by Baculum in +the file: + +\begin{verbatim} +/etc/baculum/Data-apache/baculum.dbg +\end{verbatim} + +With the information in those two files, you can usually quickly +find and correct most problems. + + \subsection{Installation for Lighttpd} -Example installation on system with SELinux enabled access and access via -Lighttpd looks following: +Installation on system with SELinux enabled access and access via +Lighttpd is as follows \begin{verbatim} yum install baculum baculum-selinux baculum-lighttpd \end{verbatim} +You can skip installing baculum-selinux if you do not use SELinux. + Please note that in case CentOS distribution the Lighttpd web server is -available in distribution packages after enabling EPEL repository. +available in the distribution packages after enabling the EPEL repository. -Start Baculum as application available through Apache web server: +Start Baculum as application using the lighttpd Web server: \begin{verbatim} service baculum-lighttpd start \end{verbatim} -Access from web browser: \textbf{http://localhost:9095} - -First time login: \textbf{admin} - -First time password: \textbf{admin} \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): +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: -In case default Apache user: +In case default Apache user, the file contents must be: \begin{verbatim} Defaults:apache !requiretty -apache ALL= NOPASSWD: /usr/sbin/bconsole +apache ALL=NOPASSWD: /usr/sbin/bconsole \end{verbatim} -In case default Lighttpd user: +In case default Lighttpd user the file contents must be: \begin{verbatim} Defaults:lighttpd !requiretty -lighttpd ALL= NOPASSWD: /usr/sbin/bconsole +lighttpd ALL=NOPASSWD: /usr/sbin/bconsole \end{verbatim} +\subsection{Running Baculum for the First Time with Lighttpd} +Access Baculum from your Web browser: \textbf{http://localhost:9095} + +First time login: \textbf{admin} + +First time password: \textbf{admin} + \section{Installation from deb binary packages} -For deb binary packages format there exist following packages: +For deb binary packages format you will find the following packages: \begin{itemize} \item baculum - main package with application files @@ -175,73 +227,75 @@ For deb binary packages format there exist following packages: \subsection{Add deb repository} -To add Baculum repository, first is required importing public key: +To add the Baculum repository, first import the Baculum public key: \begin{verbatim} wget -qO - http://bacula.org/downloads/baculum/baculum.pub | apt-key add - \end{verbatim} -Once importing the key is done, next step is adding repository definition to -newly created file: +Once the key is imported, the next step is to create +a new baculum file: \begin{verbatim} /etc/apt/sources.list.d/baculum.list \end{verbatim} -For Debian 8 Jessie the definition is: +For Debian 8 Jessie the contents should be: \begin{verbatim} deb http://bacula.org/downloads/baculum/debian jessie main deb-src http://bacula.org/downloads/baculum/debian jessie main \end{verbatim} -For Ubuntu 15.04 Vivid the definition is: +For Ubuntu 15.04 Vivid the contents should be: \begin{verbatim} deb [ arch=amd64 ] http://bacula.org/downloads/baculum/ubuntu vivid main deb-src http://bacula.org/downloads/baculum/ubuntu vivid main \end{verbatim} -For Ubuntu 15.10 Wily the definition is: +For Ubuntu 15.10 Wily the contents should be: \begin{verbatim} deb [ arch=amd64 ] http://bacula.org/downloads/baculum/ubuntu wily main deb-src http://bacula.org/downloads/baculum/ubuntu wily main \end{verbatim} -After adding repository definition please refresh repository indexes: +After adding repository definition, please refresh repository indexes: \begin{verbatim} apt-get update \end{verbatim} \subsection{Installation for Apache} -Example installation for access via Apache web server by using apt packages -manager can look like below: +To install Baculum access via Apache Web server by using apt +packages manager use the command: \begin{verbatim} apt-get install baculum baculum-apache2 \end{verbatim} -Next is needed enable mod\_rewrite module for Apache: +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 \end{verbatim} -and include Baculum VirtualHost definition into Apache configuration: +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 \end{verbatim} -Start Baculum as application available through Apache web server: +The restart your Apache server with: \begin{verbatim} service apache2 restart \end{verbatim} -Access from web browser: \textbf{http://localhost:9095} +and access Baculum from you Web browser with: \textbf{http://localhost:9095} First time login: \textbf{admin} @@ -267,24 +321,12 @@ First time login: \textbf{admin} First time password: \textbf{admin} -\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): - -In case default user both for Apache and Lighttpd: - -\begin{verbatim} -Defaults:www-data !requiretty -www-data ALL= NOPASSWD: /usr/sbin/bconsole -\end{verbatim} -\section{Installation from source tar archive} +\section{Installation from the Source Tar File} -There is possible to install Baculum from source bacula-gui tar archive. +You may also install Baculum from the source bacula-gui tar archive. -To prepare Baculum runtime files there can be used Makefile file. +To prepare Baculum runtime files one uses the Makefile file. To do this, after unpacking bacula-gui archive please go to Baculum main directory: @@ -307,20 +349,20 @@ make build DESTDIR=/tmp/baculum-release SAMPLETYPE=deb-template \ HTTPDNAME=apache2 HTTPDSITECONF=sites-available \end{verbatim} -After execution above command, in path /tmp/baculum-runtime should already exist all -runtime files. +After execution above command, in path /tmp/baculum-runtime should +contain all required runtime files. -Base Baculum source files will be located in: +The Base Baculum source files will be located in: \begin{verbatim} /tmp/baculum-runtime/usr/share/baculum/htdocs/ \end{verbatim} -They are files that should be placed in web server's document root (or Virtual -Host document root) directory. +These are the files that should be placed in web server's document root (or +Virtual Host document root) directory. -Please note that for language files (including English) are created symbolic -links as below: +Please note that for language files (including English) +symbolic links must be created as shown below: \begin{verbatim} /usr/share/locale/en/LC_MESSAGES/baculum.mo @@ -333,19 +375,19 @@ links as below: => /tmp/baculum-runtime/usr/share/baculum/htdocs/protected/Lang/pt/baculum.mo \end{verbatim} -Please also update symbolic link to Baculum settings directory in following -path: +Please also update the symbolic link to the Baculum settings directory in +the following path: \begin{verbatim} /tmp/baculum-runtime/usr/share/baculum/htdocs/protected/Data \end{verbatim} -Rest of files are: web servers configuration files, systemd units, SELinux +Other files are: web servers configuration files, systemd units, SELinux policy module and others. Please select and copy appropriate files to your system environment and edit their content if needed. -At the end there is required to set read/write privileges for web server user -to listed below directories and files: +You must set read/write privileges for the Web server user +to the files and directories listed below: \begin{verbatim} ./baculum/assets/ @@ -359,24 +401,28 @@ to listed below directories and files: Baculum supports customized and restricted consoles for each logged in user. -General design allows to have one administrator and many users. For each -user there is possible to define own bconsole configuration file that will -allow the user to specific resources only. +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. -Resources limitation is realized by Bacula Restricted Consoles functionality. +Resources limitation is realized by using Bacula Restricted Consoles +functionality. Before using customized and restricted consoles with Baculum please check -location for bconsole configuration files for each user. To do it, there -is need to run configuration wizard and then to go to "Console" wizard step +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). -In "Console" wizard step there is field "Bconsole custom config file path". -In this field there is required to define location for restricted consoles. -In defined path exists keyword \textbf{\{user\}}. The keyword will be replaced -into currently logged in username. +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. -For example, if there is logged user named "john", keyword \{user\} will be -replaced into "john". +For example, if there the user named "john", is logging in, Baculum +will replace the keyword \{user\} with {\bf john}. Example: @@ -386,23 +432,25 @@ Example: /usr/local/bacula/etc/bconsole-{user}.conf \end{verbatim} -After login user "john" to Baculum webGUI, for each bconsole request will be -used file: +Thus for user "john", Baculum will use the following file for +each access to bconsole: \begin{verbatim} /usr/local/bacula/etc/bconsole-john.conf \end{verbatim} -It makes available to define some specific Console access (or restricted +The permits defining user specific Console access (or restricted access) for each Baculum user. -Note that users are possible to create from Baculum web interface but bconsole -configuration files are not. From this reason please prepare bconsole -configuration files for each regular (not administrator) user self and check -access by logging in to Baculum as the new user. +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 proper Baculum working some Bconsole commands are necessary. They are -commands: +For Baculum to work work correctly some Bconsole commands are necessary. +They are: \begin{itemize} \item show diff --git a/docs/upload b/docs/upload index 9b48e260..dce1c4f8 100755 --- a/docs/upload +++ b/docs/upload @@ -7,7 +7,7 @@ fi cwd=`pwd` lang=$1 src=$cwd/manuals/${lang}/pdf-and-html -ver=7.4.1 +ver=7.4.3 repo=release echo "ver=${ver}" -- 2.39.5