Add docs for passive mode

manuals/en/main/bareos-manual-main-reference.tex

@@ -142,10 +142,8 @@ \chapter{Accurate Mode}
 \include{win32}
 
 \chapter{Network setup}
-    \subsection{Passive Clients}
-        \label{PassiveClient}
-        \TODO{to be written}
 
+\include{passiveclient}
 \include{tls}
 \include{dataencryption}
 

manuals/en/main/bareos.sty

@@ -221,6 +221,8 @@
         %label=config:#1,
         caption=#1,
         captionpos=b,
+        moredelim=[is][\it]{<input>}{</input>},
+        moredelim=[is][\underline]{<strong>}{</strong>},
     }
 }{}
 

manuals/en/main/dirdconf.tex

@@ -2261,21 +2261,20 @@ \section{Client Resource}
 \index[dir]{Directive!Client (or FileDaemon)}
 Start of the Client directives.
 
-\item [Name = {\textless}name{\textgreater}] \hfill \\
-\index[dir]{Name}
-\index[dir]{Directive!Name}
+\xdirective{dir}{Name}{name}{required}{}{}{\\
 The client name which will be used in the  Job resource directive or in the
-console run command.  This directive is required.
+console run command.
+}
 
-\item [Protocol = {\textless}protocolname{\textgreater}] \hfill \\
-\index[dir]{Protocol}
-\index[dir]{Directive!Protocol}
-The backup protocol to use to run the Job. If not set it will default
-to {\bf Native} currently the director understand the following protocols:
+\xdirective{dir}{Protocol}{Native{\textbar}NDMP}{}{Native}{13.2}{\\
+The backup protocol to use to run the Job. 
+
+Currently the director understand the following protocols:
 \begin{enumerate}
 \item Native - The native Bareos protocol
 \item NDMP - The NDMP protocol
 \end{enumerate}
+}
 
 \item [Authtype = {\textless}Client-Authtype{\textgreater}] \hfill \\
 \index[dir]{Authtype}
@@ -2290,14 +2289,12 @@ \section{Client Resource}
 \item MD5 - Use MD5 hashing
 \end{enumerate}
 
-\item [Address = {\textless}address{\textgreater}] \hfill \\
-\index[dir]{Address}
-\index[dir]{Directive!FD Address}
-\index[dir]{File Daemon Address}
-\index[dir]{Client Address}
+\xdirective{dir}{Address}{address}{required}{}{}{\\
 Where the address is a host name, a fully qualified domain name, or a
 network address in dotted quad notation for a Bareos File server daemon.
 This directive is required.
+\index[dir]{Client Address}
+}
 
 \item [FD Port = {\textless}port-number{\textgreater}] \hfill \\
 \index[dir]{FD Port}
@@ -2452,6 +2449,15 @@ \section{Client Resource}
 \index[sd]{Directive!NDMP Blocksize}
 This directive sets the default NDMP blocksize for this client.
 
+\xdirective{dir}{Passive}{yes{\textbar}no}{}{no}{13.2}{\\
+The normal way of initializing the data channel (the channel where the backup data itself is transported)
+is done by the file daemon (client) that connects to the storage daemon.
+
+By using the client passive mode, the initialization of the datachannel is reversed, so that the storage daemon connects to the filedaemon.
+
+See chapter \ilink{Passive Client}{PassiveClient}.
+}
+
 \item [Priority = {\textless}number{\textgreater}] \hfill \\
 \index[dir]{Priority}
 \index[dir]{Directive!Priority}
@@ -2464,15 +2470,13 @@ \section{Client Resource}
 
 The following is an example of a valid Client resource definition:
 
-\footnotesize
-\begin{verbatim}
+\begin{bconfig}{Minimal client resource definition in bareos-dir.conf}
 Client {
-  Name = minimatou
-  FDAddress = minimatou.example.com
+  Name = client1-fd
+  Address = client1.example.com
   Password = "secret"
 }
-\end{verbatim}
-\normalsize
+\end{bconfig}
 
 \section{Storage Resource}
 \label{StorageResource2}

manuals/en/main/passiveclient.tex

@@ -0,0 +1,47 @@
+\section{Passive Clients}
+\label{PassiveClient}
+
+The normal way of initializing the data channel (the channel where the backup data itself is transported)
+is done by the file daemon (client) that connects to the storage daemon.
+
+In many setups, this can cause problems, as this means that:
+\begin{itemize}
+    \item The client must be able to resolve the name of the storage daemon (Often not true, you have to do tricks with the hosts file)
+    \item The client must be allowed to create a new connection.
+    \item The client must be able to connect to the storage daemon over the network (often difficult over NAT or Firewall)
+\end{itemize}
+
+By using Passive Client, the initialization of the datachannel is reversed, so that the storage daemon connects to the filedaemon.
+This solves almost every problem created by Firewalls, NAT-gateways and resolving issues, as
+
+\begin{itemize}
+    \item The storage daemon initiates the connection, and thus can pass thru the same or similar firewallrules that the director already has to access the fileadaemon.
+    \item The client never initiates any connection, thus can be completely firewalled.
+    \item The client never needs any name resolution and is totally independent from any resolving issues.
+\end{itemize}
+
+\subsection{Usage}
+
+To use this new feature, just configure  \textbf{passive=yes} in the client definition of the director daemon:
+\begin{bconfig}{Enable passive mode in bareos-dir.conf}
+Client {
+   Name = client1-fd
+   Password = "secretpassword"
+   <input>Passive = yes</input>
+   [...]
+}
+\end{bconfig}
+
+Also, you need to set \configdirective{compatible=no} in the \file{bareos-fd.conf} configuration file:
+\begin{bconfig}{Disable compatible mode for the Bareos filedaemon in bareos-fd.conf} 
+Director {
+  Name = bareos-dir
+  Password = "secretpassword"
+}
+
+FileDaemon {
+   Name = client1-fd
+   [...]
+   <input>Compatible = no</input>
+}
+\end{bconfig}