Extend ACL data type description

Cleanup Console configuration examples.

manuals/en/main/bareos.sty

@@ -212,7 +212,19 @@
 \newcommand{\pool}[1]{\resourcename{Dir}{Pool}{#1}}
 \newcommand{\argument}[1]{\textit{#1}}
 \newcommand{\resourcetype}[2]{\path|#2|$^{\mbox{\tiny #1}}$}
-\newcommand{\resourcename}[3]{\path|#3|$^{\mbox{\tiny #1}}_{\mbox{\tiny #2}}$}
+
+\makeatletter
+\newcommand{\resourcename}{%
+\@ifstar{%
+\resourcenameStar%
+}{%
+\resourcenameNostar%
+}%
+}
+\makeatother
+\newcommand{\resourcenameStar}[3]{\path|#3|}
+\newcommand{\resourcenameNostar}[3]{\path|#3|$^{\mbox{\tiny #1}}_{\mbox{\tiny #2}}$}
+
 \newcommand{\registrykey}[1]{\path|#1|}
 \newcommand{\variable}[1]{\path|#1|}
 \newcommand{\volume}[1]{\path|#1|}
@@ -514,7 +526,7 @@ Version $>=$ #3%
         breakatwhitespace=true,
         prebreak=\raisebox{0ex}[0ex][0ex]{ \ensuremath{\swarrow}},
         postbreak=\raisebox{0ex}[0ex][0ex]{\ensuremath{\hookrightarrow} },
-        caption=#1,
+        caption=\mbox{#1},
         %basicstyle=\ttfamily,
         basicstyle=\small,
         stringstyle=\ttfamily,
@@ -550,7 +562,7 @@ Version $>=$ #3%
         keepspaces=true,
         columns=fullflexible,
         %label=config:#1,
-        caption=#1,
+        caption=\mbox{#1},
         captionpos=b,
         moredelim=[is][\it]{<input>}{</input>},
         moredelim=[is][\underline]{<strong>}{</strong>},
@@ -576,7 +588,7 @@ Version $>=$ #3%
         keepspaces=true,
         columns=fullflexible,
         %label=config:#1,
-        caption=#1,
+        caption=\mbox{#1},
         captionpos=b,
         moredelim=[is][\it]{<input>}{</input>},
         moredelim=[is][\underline]{<strong>}{</strong>},

manuals/en/main/config/DirConsoleJobACL1.conf

@@ -1,2 +1,2 @@
-JobACL = "Backup client 1", "Backup client 2"
+JobACL = "backup-bareos-fd", "backup-www.example.com-fd"
 JobACL = "RestoreFiles"

manuals/en/main/configure.tex

@@ -509,12 +509,57 @@ \subsubsection{Data Types}
     \index[general]{Data Type!acl}
     \label{DataTypeAcl}
 This directive defines what is permitted to be accessed.
-It does this by using a list of strings, separated by commas (\parameter{,}).
-
+It does this by using a list of regular expressions, separated by commas (\argument{,})
+or using multiple directives.
+If \argument{!} is prepended, the expression is negated.
 The special keyword \parameter{*all*} allows unrestricted access.
 
-Depending on the type of the ACL, the strings can be either resource names, paths or bconsole commands.
+Depending on the type of the ACL, the regular expressions can be either resource names, paths or console commands.
+
+Since Bareos \sinceVersion{dir}{ACL: strict regular expression handling}{16.2.4} regular expression are handled more strictly. Before also substring matches has been accepted.
+
+\label{sec:CommandAclExample}
+For clarification, we demonstrate the usage of ACLs by some examples for \linkResourceDirective{Dir}{Console}{Command ACL}:
+\begin{bconfig}{Allow only the help command}
+Command ACL = help
+\end{bconfig}
+
+\begin{bconfig}{Allow the help and the list command}
+Command ACL = help, list
+\end{bconfig}
+
+\begin{bconfig}{Allow the help and the (not existing) iDoNotExist command}
+Command ACL = help, iDoNotExist
+\end{bconfig}
+
+\begin{bconfig}{Allow all commands (special keyword)}
+Command ACL = *all*
+\end{bconfig}
+
+\begin{bconfig}{Allow all commands except sqlquery and commands starting with u}
+Command ACL = !sqlquery, !u.*, *all*
+\end{bconfig}
+
+Same:
+\begin{bconfig}{Some as above. Specifying it in multiple lines doesn't change the meaning}
+Command ACL = !sqlquery, !u.*
+Command ACL = *all*
+\end{bconfig}
 
+\begin{bconfig}{Additional deny the setip and setdebug commands}
+Command ACL = !sqlquery
+Command ACL = !u.*
+Comamnd ACL = !set(ip|debug)
+Comamnd ACL = *all*
+\end{bconfig}
+
+\warning{
+ACL checking stops at the first match. So the following definition allows all commands, which might not be what you expected:
+}
+\begin{bconfig}{Wrong: Allows all commands}
+# WARNING: this configuration ignores !sqlquery, as *all* is matched before.
+Command ACL = *all*, !sqlquery
+\end{bconfig}
 
 \item [auth-type]
     \index[general]{Data Type!auth-type}

manuals/en/main/consoleconf.tex

@@ -99,10 +99,10 @@ \section{Console Resource}
 comprise three different security levels.
 
 \begin{itemize}
-\item The first console type is an {\bf anonymous} or {\bf default}
+\item The first console type is an \name{admin} or \name{anonymous} or \name{default}
 console, which has full privileges.  There is no console resource
 necessary for this type since the password is specified in the Director
-resource.  Typically you would use this {\bf anonymous} console
+resource.  Typically you would use this console
 only for administrators.
 
 \item The second type of console is a
@@ -159,58 +159,73 @@ \section{Console Resource}
 \section{Example Console Configuration File}
 \index[general]{Configuration!bconsole}
 
-The following configuration files were supplied by Phil Stracchino. For
-example, if we define the following in the user's bconsole.conf file:
+A Console configuration file might look like this:
 
-\begin{bconfig}{}
+\begin{bconfig}{bconsole configuration}
 Director {
-   Name = MyDirector
+  Name = "bareos.example.com-dir"
+  address = "bareos.example.com"
+  Password = "PASSWORD"
+}
+\end{bconfig}
+
+With this configuration, the console program (e.g. \command{bconsole}) will try to connect
+to a \bareosDir named \name{bareos.example.com-dir}
+at the network address \host{bareos.example.com} and authenticate to the admin console using the password \name{PASSWORD}.
+
+\subsection{Using Named Consoles}
+\label{sec:ConsoleAccessExample}
+The following configuration files were supplied by Phil Stracchino.
+
+To use named consoles from \command{bconsole}, use a \file{bconsole.conf} configuration file like this:
+\begin{bconfig}{bconsole: restricted-user}
+Director {
+   Name = bareos-dir
    Address = myserver
    Password = "XXXXXXXXXXX"
 }
 
 Console {
    Name = restricted-user
-   Password = "UntrustedUser"
+   Password = "RUPASSWORD"
 }
 \end{bconfig}
 
-Where the Password in the Director section is deliberately incorrect, and the
-Console resource is given a name, in this case {\bf restricted-user}. Then
-in the Director's bareos-dir.conf file (not directly accessible by the user),
-we define:
+Where the Password in the Director section is deliberately incorrect and the
+Console resource is given a name, in this case \argument{restricted-user}. Then
+in the Director configuration (not directly accessible by the user), we define:
 
-\begin{bconfig}{}
+\begin{bareosConfigResource}{bareos-dir}{console}{restricted-user}
 Console {
   Name = restricted-user
-  Password = "UntrustedUser"
+  Password = "RUPASSWORD"
   JobACL = "Restricted Client Save"
   ClientACL = restricted-client
   StorageACL = main-storage
   ScheduleACL = *all*
   PoolACL = *all*
   FileSetACL = "Restricted Client's FileSet"
-  CatalogACL = DefaultCatalog
+  CatalogACL = MyCatalog
   CommandACL = run
 }
-\end{bconfig}
-
-
-the user logging into the Director from his Console will get logged in as {\bf
-restricted-user}, and he will only be able to see or access a Job with the
-name {\bf Restricted Client Save} a Client with the name {\bf
-restricted-client}, a Storage device {\bf main-storage}, any Schedule or Pool,
-a FileSet named {\bf Restricted Client's FileSet}, a Catalog named {\bf
-DefaultCatalog}, and the only command he can use in the Console is the {\bf
-run} command. In other words, this user is rather limited in what he can see
+\end{bareosConfigResource}
+
+The user login into the Director from his Console will get logged in as \resourcename{Dir}{Console}{restricted-user}
+and he will only be able to see or access a Job with the
+name \resourcename*{Dir}{Job}{Restricted Client Save}, a Client with the name \resourcename*{Dir}{Client}{restricted-client},
+a storage device \resourcename*{Dir}{Storage}{main-storage}, any Schedule or Pool,
+a FileSet named \resourcename*{Dir}{FileSet}{Restricted Client's FileSet}, a Catalog named \resourcename*{Dir}{Catalog}{MyCatalog}
+and the only command he can use in the Console is the \bcommand{run}{} command.
+In other words, this user is rather limited in what he can see
 and do with Bareos.
+For details how to configure ACLs, see the \dt{Acl} data type description.
 
-The following is an example of a bconsole.conf file that can access
-several Directors and has different Consoles depending on the director:
+The following is an example of a  \file{bconsole.conf} file that can access
+several Directors and has different Consoles depending on the Director:
 
-\begin{bconfig}{}
+\begin{bconfig}{bconsole: multiple consoles}
 Director {
-   Name = MyDirector
+   Name = bareos-dir
    Address = myserver
    Password = "XXXXXXXXXXX"    # no, really.  this is not obfuscation.
 }
@@ -223,24 +238,24 @@ \section{Example Console Configuration File}
 
 Console {
    Name = restricted-user
-   Password = "UntrustedUser"
+   Password = "RUPASSWORD"
    Director = MyDirector
 }
 
 Console {
-   Name = restricted-user
-   Password = "A different UntrustedUser"
+   Name = restricted-user2
+   Password = "OTHERPASSWORD"
    Director = SecondDirector
 }
 \end{bconfig}
 
-The second Director referenced at "secondserver" might look
+The second Director referenced at \resourcename{Dir}{Director}{secondserver} might look
 like the following:
 
-\begin{bconfig}{}
+\begin{bareosConfigResource}{bareos-dir}{console}{restricted-user2}
 Console {
-  Name = restricted-user
-  Password = "A different UntrustedUser"
+  Name = restricted-user2
+  Password = "OTHERPASSWORD"
   JobACL = "Restricted Client Save"
   ClientACL = restricted-client
   StorageACL = second-storage
@@ -251,18 +266,4 @@ \section{Example Console Configuration File}
   CommandACL = run, restore
   WhereACL = "/"
 }
-\end{bconfig}
-
-
-An example Console configuration file might be the following:
-
-\begin{bconfig}{}
-#
-# Bareos Console Configuration File
-#
-Director {
-  Name = "bareos.example.com-dir"
-  address = "bareos.example.com"
-  Password = "PASSWORD"
-}
-\end{bconfig}
+\end{bareosConfigResource}

manuals/en/main/dirdconf.tex

@@ -620,18 +620,13 @@ \section{Console Resource}
 \end{description}
 
 The Console resource is optional and need not be specified. The following
-directives are permitted within the Director's configuration resource:
+directives are permitted within these resources:
 
 \input{autogenerated/bareos-dir-resource-console-table.tex}
 \input{director-resource-console-definitions.tex}
 \input{autogenerated/bareos-dir-resource-console-description.tex}
 
-
-Aside from Director resource names and console command names, the special
-keyword \parameter{*all*} can be specified in any of the above access control lists.
-When this keyword is present, any resource or command name (which ever is
-appropriate) will be accepted. For an example configuration file, please see
-the \nameref{ConsoleConfChapter} chapter of this manual.
+The example at \nameref{sec:ConsoleAccessExample} shows how to use a console resource for a connection from a client like \command{bconsole}.
 
 \section{Profile Resource}
 \label{DirectorResourceProfile}

manuals/en/main/director-resource-console-definitions.tex

@@ -10,6 +10,7 @@
 \defDirective{Dir}{Console}{Command ACL}{}{}{%
 This directive is used to specify a list of of console commands that can
 be executed by the console.
+See examples at \nameref{sec:CommandAclExample}.
 }
 
 \defDirective{Dir}{Console}{Description}{}{}{%
@@ -25,32 +26,25 @@
 be accessed by the console.  Without this directive, the console cannot
 access any of the Director's Job resources.  Multiple Job resource names
 may be specified by separating them with commas, and/or by specifying
-multiple JobACL directives.  For example, the directive may be specified
-as:
+multiple \configdirective{Job ACL} directives.
+For example, the directive may be specified as:
 \bconfigInput{config/DirConsoleJobACL1.conf}
 With the above specification, the console can access the Director's  resources
-for the four jobs named on the JobACL directives,  but for no others.
+for the jobs named on the \configdirective{Job ACL} directives,  but for no others.
 }
 
 \defDirective{Dir}{Console}{Name}{}{}{%
-The name of the console. This  name must match the name specified in the
-Console's configuration  resource (much as is the case with Client
-definitions).
+The name of the console. This  name must match the name specified at the
+Console client.
 }
 
 \defDirective{Dir}{Console}{Password}{}{}{%
 Specifies the password that must be supplied for a named Bareos Console
-to be authorized.  The same password must appear in the {\bf Console}
-resource of the Console configuration file.  For added security, the
-password is never actually passed across the network but rather a
-challenge response hash code created with the password.  This directive
-is required.
-
-The password is plain text.  It is preferable for security reasons to choose
-random text.
+to be authorized.
 }
 
 \defDirective{Dir}{Console}{Plugin Options ACL}{}{}{%
+Use this directive to specify the list of allowed Plugin Options.
 }
 
 \defDirective{Dir}{Console}{Pool ACL}{}{}{%
@@ -114,11 +108,10 @@
 This directive permits you to specify where a restricted console
 can restore files. If this directive is not specified, only the
 default restore location is permitted (normally \file{/tmp/bareos-restores}.
-If {\bf all} is specified any path the
-user enters will be accepted (not very secure), any other
-value specified (there may be multiple WhereACL directives) will
+If \argument{*all*} is specified any path the
+user enters will be accepted. Any other
+value specified (there may be multiple \configdirective{Where ACL} directives) will
 restrict the user to use that path. For example, on a Unix system,
 if you specify "/", the file will be restored to the original
-location.  This directive is untested.
+location.
 }
-