describe dbconfig (Debian/Ubuntu)

manuals/en/main/catmaintenance.tex

@@ -17,10 +17,50 @@ \section{Catalog Database}
 \end{itemize}
 
 What database will be used, can be configured in \file{/etc/bareos/bareos-dir.conf}, see the \nameref{DirectorResourceCatalog}.
+
 The database often runs on the same server as the Bareos Director.
 However, it is also possible to run it on a different system.
 This might require some more manual configuration.
 
+
+
+\subsection{dbconfig-common (Debian)}
+\index[general]{Platform!Debian!dbconfig-common}
+\index[general]{Platform!Ubuntu!dbconfig-common}
+\label{sec:dbconfig}
+
+Since Bareos \sinceVersion{dir}{dbconfig-common (Debian)}{14.2.0} the Debian (and Ubuntu) based packages support the \package{dbconfig-common} mechanism to create and update the Bareos database.
+If this is properly configured, there is no need to manual create and update the Bareos database. 
+Instead, this will be done automatically during package installation and update, according to the user choices.
+
+The first choice is, if \package{dbconfig-common} should be used at all.
+If you decide against it, the database must be configured manually, see \nameref{CatMaintenanceManualConfiguration}.
+
+If you decided to use \package{dbconfig-common}, the next question will only be asked, if more than one
+Bareos database backend (\package{bareos-database-*}) is installed.
+If this is the case, select the database backend you want to use.
+
+\begin{center}
+\includegraphics[width=0.45\textwidth]{\idir dbconfig-1-enable}
+\includegraphics[width=0.45\textwidth]{\idir dbconfig-2-select-database-type}
+\end{center}
+
+Depending on the selected database backend,
+more questions about how to access the database will be asked.
+Often, the default values are suitable.
+
+The \package{dbconfig-common} configuration (and credentials) is done by the \package{bareos-database-common} package.
+Settings are stored in the file \file{/etc/dbconfig-common/bareos-database-common.conf}.
+
+The Bareos database backend will get automatically configured in \file{/etc/bareos/bareos-dir.conf}.
+A later reconfiguration might require manual adapt changes.
+
+
+
+
+\subsection{Manual Configuration}
+    \label{CatMaintenanceManualConfiguration}
+
 Bareos comes with a number of scripts to prepare and update the databases. All these scripts are located in the Bareos script directory, normally at \scriptPathUnix.
 
 \begin{center}
@@ -124,7 +164,7 @@ \section{Catalog Database}
 
 
 
-\subsection{PostgreSQL}
+\subsubsection{PostgreSQL}
 
 On most distributions, PostgreSQL uses ident to allow access to the database system.
 The database administrator account is the Unix user \user{postgres}.
@@ -247,8 +287,8 @@ \subsection{PostgreSQL}
 \end{commands}
 
 
-\subsection{MySQL}
-\label{catalog-maintenance-mysql}
+\subsubsection{MySQL}
+    \label{catalog-maintenance-mysql}
 
 MySQL user authentication is username, password and host-based.
 The database administrator is the user \user{root}.
@@ -372,7 +412,7 @@ \subsection{MySQL}
 \end{commands}
 
 
-\subsubsection{Modify database credentials}
+\paragraph{Modify database credentials}
 
 If you want to change the Bareos database credentials, do the following:
 
@@ -446,7 +486,7 @@ \subsubsection{Modify database credentials}
 
 
 
-\subsection{Sqlite}
+\subsubsection{Sqlite}
 
 There are different versions of Sqlite available. When we use the term Sqlite, we will always refer to Sqlite3.
 

manuals/en/main/install.tex

@@ -49,7 +49,7 @@ \section{Choose a Database Backend}
     \item PostgreSQL by package \package{bareos-database-postgresql}
     \item MySQL by package \package{bareos-database-mysql}
     \item Sqlite by package \package{bareos-database-sqlite3} \\
-        \warning{The Sqlite backend only intended for testing, not for productive use.}
+        \warning{The Sqlite backend is only intended for testing, not for productive use.}
 \end{itemize}
 
 The PostgreSQL backend is the default.
@@ -148,8 +148,9 @@ \subsubsection{SUSE Linux Enterprise Server (SLES), openSUSE}
 # define parameter
 #
 
-DIST=SLE_11_SP3
+DIST=SLE_12
 # or
+# DIST=SLE_11_SP3
 # DIST=openSUSE_13.1
 
 DATABASE=postgresql
@@ -212,9 +213,30 @@ \section{Prepare Bareos database}
 The easiest way to set up a database is using an system account that have passwordless local access to the database. 
 Often this is the user \user{root} for MySQL and the user \user{postgres} for PostgreSQL.
 
-For details, see chapter \ilink{Catalog Maintenance}{CatMaintenanceChapter}.
+For details, see chapter \nameref{CatMaintenanceChapter}.
 
-\subsection{PostgreSQL}
+\subsection{Debian based Linux Distributions}
+
+Since Bareos \sinceVersion{dir}{dbconfig-common (Debian)}{14.2.0} the Debian (and Ubuntu) based packages support the \package{dbconfig-common} mechanism to create and update the Bareos database.
+
+Follow the instructions during install to configure it according to your needs.
+
+\begin{center}
+\includegraphics[width=0.45\textwidth]{\idir dbconfig-1-enable}
+\includegraphics[width=0.45\textwidth]{\idir dbconfig-2-select-database-type}
+\end{center}
+
+If you decide not to use \package{dbconfig-common} (selecting \parameter{<No>} on the initial dialog), 
+follow the instructions for \nameref{sec:CreateDatabaseOtherDistributions}.
+
+The selectable database backends depend on the \package{bareos-database-*} packages installed.
+
+For details see \nameref{sec:dbconfig}.
+
+\subsection{Other Platforms}
+    \label{sec:CreateDatabaseOtherDistributions}
+
+\subsubsection{PostgreSQL}
 If your are using PostgreSQL and your PostgreSQL administration user is \user{postgres} (default), use following commands:
 
 \begin{commands}{Setup Bareos catalog with PostgreSQL}
@@ -224,7 +246,7 @@ \subsection{PostgreSQL}
 \end{commands}
 
 
-\subsection{MySQL}
+\subsubsection{MySQL}
 Make sure, that \user{root} has direct access to the local MySQL server. 
 Check if the command \command{mysql} connects to the database without defining the password.
 This is the default on RedHat and SUSE distributions. 
@@ -275,13 +297,30 @@ \chapter{Updating Bareos}
 \section{Updating the database schema}
 
 Sometimes improvements in Bareos make it neccessary to update the database scheme.
-This has to be done as database administrator and can therefore not be done by the Bareos packages itself, even if the database host runs on the same system as the Bareos Director.
 
 \warning{If the Bareos catalog database has not the current schema, the Bareos Director refuses to start.}
+
 Detailed information can than be found in the log file \logfileUnix.
 
 Take a look in the \ilink{Release Notes}{releasenotes} to see, what Bareos updates to require a database schema update.
 
+
+\subsection{Debian based Linux Distributions}
+
+Since Bareos \sinceVersion{dir}{dbconfig-common (Debian)}{14.2.0} the Debian (and Ubuntu) based packages support the \package{dbconfig-common} mechanism to create and update the Bareos database.
+If this is properly configured, the database schema will be automatically adapted by the Bareos packages.
+For details see \nameref{sec:dbconfig}.
+
+If you disabled the usage of \package{dbconfig-common}, 
+follow the instructions for \nameref{sec:UpdateDatabaseOtherDistributions}.
+
+\subsection{Other Platforms}
+    \label{sec:UpdateDatabaseOtherDistributions}
+
+This has to be done as database administrator.
+On most platforms Bareos knows only about the credentials to access the Bareos database,
+but not about the database administrator to modify the database schema.
+
 The task of updating the database schema is done by the script
 \command{/usr/lib/bareos/scripts/update_bareos_tables}.
 
@@ -291,7 +330,7 @@ \section{Updating the database schema}
 
 \warning{If you're updating to Bareos $<=$ 13.2.3 and had configured the Bareos database during install using Bareos environment variables (\variable{db_name}, \variable{db_user} or \variable{db_password}, see \ilink{Catalog Maintenance}{CatMaintenanceChapter}), make sure to have these variables definied in the same way when calling the update and grant scripts. Newer versions of Bareos read this variables from the Director configuration file \configFileDirUnix. However, make sure, the user running the database scripts has read access to this file (or set the environment variables). The \user{postgres} user normally does not have the required permissions.}
 
-\subsection{PostgreSQL}
+\subsubsection{PostgreSQL}
 If your are using PostgreSQL and your PostgreSQL administrator is \user{postgres} (default), use following commands:
 
 \begin{commands}{Update PostgreSQL database schema}
@@ -303,7 +342,7 @@ \subsection{PostgreSQL}
 
 After this, restart the Bareos Director and verify it starts without problems.
 
-\subsection{MySQL}
+\subsubsection{MySQL}
 Make sure, that \user{root} has direct access to the local MySQL server.
 Check if the command \command{mysql} without parameter connects to the database.
 If not, you may be required to adapt your local MySQL config file \file{~/.my.cnf}.

manuals/images/Makefile

@@ -13,7 +13,8 @@ CONV_PNG = $(patsubst %.eps,conv/%.png,$(ORIG_EPS))
 #CONV_FIG_EPS = $(patsubst %.fig,conv/%.eps,$(ORIG_FIG))
 
 
-all: $(CONV_EPS) $(CONV_PNG) conv/bareos-full-logo.png conv/bareos-full-logo.eps conv/autoxflate-functionblocks.png conv/autoxflate-functionblocks.eps
+all: $(CONV_EPS) $(CONV_PNG) conv/bareos-full-logo.png conv/bareos-full-logo.eps conv/autoxflate-functionblocks.png conv/autoxflate-functionblocks.eps conv/dbconfig-1-enable.png conv/dbconfig-1-enable.eps conv/dbconfig-2-select-database-type.png conv/dbconfig-2-select-database-type.eps conv/dbconfig-3-postgresql-password.png conv/dbconfig-3-postgresql-password.eps
+
 
 # bareos-full-logo: png is of better quality than eps, therefore take that as source
 conv/bareos-full-logo.eps: bareos-full-logo.png
@@ -32,6 +33,32 @@ conv/autoxflate-functionblocks.eps: autoxflate-functionblocks.png
 	@$(MKDIRCONV)
 	$(CONVERT) autoxflate-functionblocks.png conv/autoxflate-functionblocks.eps
 
+
+conv/dbconfig-1-enable.png: dbconfig-1-enable.png
+	@$(MKDIRCONV)
+	$(COPY) dbconfig-1-enable.png conv/
+
+conv/dbconfig-1-enable.eps: dbconfig-1-enable.png
+	@$(MKDIRCONV)
+	$(CONVERT) dbconfig-1-enable.png conv/dbconfig-1-enable.eps
+
+conv/dbconfig-2-select-database-type.png: dbconfig-2-select-database-type.png
+	@$(MKDIRCONV)
+	$(COPY) dbconfig-2-select-database-type.png conv/
+
+conv/dbconfig-2-select-database-type.eps: dbconfig-2-select-database-type.png
+	@$(MKDIRCONV)
+	$(CONVERT) dbconfig-2-select-database-type.png conv/dbconfig-2-select-database-type.eps
+
+conv/dbconfig-3-postgresql-password.png: dbconfig-3-postgresql-password.png
+	@$(MKDIRCONV)
+	$(COPY) dbconfig-3-postgresql-password.png conv/
+
+conv/dbconfig-3-postgresql-password.eps: dbconfig-3-postgresql-password.png
+	@$(MKDIRCONV)
+	$(CONVERT) dbconfig-3-postgresql-password.png conv/dbconfig-3-postgresql-password.eps
+
+
 conv/%.png: %.eps
 	@$(MKDIRCONV)
 	$(CONVERT) $< conv/`basename $< .eps`.png