docs: added documentation for version 18.2

- added a table with all configuration directives for TLS
- reworked developer chapter "TLS"
- added developer chapter for PAM authentication
- added connection sequence diagram for passive file daemon connections before 18.2

docs/manuals/en/new_main_reference/source/bareos-18.2.rst

@@ -0,0 +1,174 @@
+TLS Configuration Reference
+===========================
+
+To be able to communicate via TLS, TLS need to be configured on both sides. In Bareos certain directives are used to set up TLS.
+
+The following table explains the location of the relevant TLS configuration directives for all possible Bareos TCP connections. Each resource is referred to as <component>-<resource> to identify the exact configuration location. Refer to chapter :ref:`ConfigureChapter` for more details about configuration.
+
+In Bareos Version 18.2 the relevant resources for some connections had to be changed. Affected directives are marked with the applicable version and the respective resource is written in bold letters.
+
+*Remark: TLS-PSK is not available on Bareos components before Version 18.2.*
+
+ .. csv-table:: TLS Configuration Reference
+    :file: Bareos_connection_modes_overview_1.csv
+    :widths: 20 35 10 35
+
+.. rubric:: Footnotes
+.. [#identity] From Version 18.2 onwards this is identical to the TLS-PSK Identitiy
+.. [#psk] From Version 18.2 onwards this is identical to the TLS-PSK Pre-Shared Key
+.. [#user_agent] The name of the default console is predefined and cannot be changed
+.. [#cert] Certificate directives are: TlsVerifyPeer, TlsCaCertificateFile, TlsCaCertificateDir, TlsCertificateRevocationList, TlsCertificate, TlsKey, TlsAllowedCn
+
+Compatibility with Bareos File Daemons before 18.2
+==================================================
+As from Bareos 18.2 all components establish a secure connection with encryption first, then the proprietary Bareos protocol will take place. Older components of Bareos did not establish a secure connection before doing anything else.
+
+When a Bareos Director Daemon with version 18.2 tries to connect to a passive Bareos File Daemon the version of the File Daemon has to be guessed. Therefore a special workflow had to be implemented in Bareos Director Daemon. This is as follows:
+
+.. uml::
+  :caption: Sequence diagram of a Bareos File Daemon connection
+
+  hide footbox
+
+  box "Director"
+  Actor user
+  participant "ConfigurationParser\nclass" as Config << C,#EEEEEE >>
+  participant "Some methods in\ndirectordaemon namespace" as Dir << N,#EEEEEE >>
+  participant "Client methods in\n directordaemon namespace" as F << N,#EEEEEE >>
+  participant "Client methods in\n filedaemon namespace" as FC << N,#EEEEEE >>
+
+  == Config Initialisation ==
+
+  user -> Config: reload config
+  activate Config
+  Config -> Config: ParseConfigFile()
+  Config -> Dir: ConfigReadyCallback()
+  activate Dir
+  Dir -> Config: ResetAllClientConnectionHandshakeModes
+  Dir <-- Config: All handshake modes reset to\nClientConnectionHandshakeMode::kUndefined
+  Config <-- Dir: ConfigReadyCallback() done
+  deactivate Dir
+  user <-- Config: config reloaded
+
+  ... try to connect to a client ...
+
+  == Client Connection to old unknown client ==
+
+  user -> Dir: run some client command
+  activate Dir
+  end box
+
+  box "Filedaemon"
+  Dir -> F: ConnectToFileDaemon()
+  activate F
+  note right of F: Possible modes:\nkTlsFirst (try TLS immediately),\nkCleartextFirst (old cleartext handshake)
+  F ->> FC: Try to connect to Filedaemon with immediate TLS\nconnection mode (kTlsFirst)
+  F ->> FC: If immediate TLS fails try cleartext handshake mode\n(kCleartextFirst, this will happen with old clients before 18.2)
+  F <- FC: Connection established
+  Config <- F: Save successful mode into configuration of client
+  Dir <-- F: ConnectToFileDaemon() done
+  ... do something with client ...
+  FC <--> F: close client connection
+  Dir <-- F:
+  user <-- Dir : finished some client command
+  deactivate F
+  deactivate Dir
+
+  ... connect to the same filedaemon again ...
+
+  == Client Connection to a known client ==
+
+  user -> Dir: run some client command
+  activate Dir
+  Dir -> F: ConnectToFileDaemon()
+  activate F
+  Config -> F: Load successful mode from configuration of client
+  F -> FC: Connect to Filedaemon with saved connection mode from config
+  F <- FC: Connection established without waiting or probing
+  Dir <-- F: ConnectToFileDaemon() done
+  ... do something with client ...
+  FC <--> F: close client connection
+  Dir <-- F:
+  user <-- Dir : finished some client command
+  deactivate F
+  deactivate Dir
+
+  end box
+
+  deactivate Config
+
+PAM
+===
+
+Introduction
+------------
+
+For a first overview the following diagram shows the connection sequence of a Bareos Console to a Bareos Director using PAM authentication.
+
+.. uml::
+  :caption: Initiation of a Bareos Console connection using PAM authentication
+
+  hide footbox
+
+  actor user
+  participant "B-Console" as console
+  participant "Director" as director
+  participant "PAM-Linux" as pam
+
+  user -> console: start a named bconsole
+  console <-> director: initiate TCP connection
+  console <-> director: initiate a secure TLS connection (cert/psk)
+  console <-> director: primary challenge/response authentication
+
+  == PAM user authentication ==
+  note left of pam: i.e. pam_unix.so\nconfigured in /etc/pam.d/bareos
+  autonumber
+  director -> pam: initialize pam module with user name
+  director <- pam: request password via callback
+  console <- director: send "Password:" request (encrypted via TLS)
+  user <- console: prompt "Password:"
+  user -> console: enter password (hidden)
+  console -> director: send password (encrypted via TLS)
+  director -> pam: give back password
+  director <- pam: return success of authentication
+  console <- director: send welcome message
+  user <- console: show welcome message
+  director -> pam: shutdown pam module
+
+  autonumber stop
+  == PAM user authentication end ==
+
+  ... do something with console ...
+
+  user -> console: quit session ('q'; Ctrl + D)
+  console <-> director: Shutdown TLS
+  console <-> director: Finish TCP connection
+
+Configuration
+-------------
+To enable PAM authentication two systems have to be configured. The PAM module in the operating system and the Bareos Console.
+
+PAM Module
+^^^^^^^^^^
+This is depending on the operating system (OS) and on the used pam module. For details see the manuals of your OS. The name of the service that has to be registered is "bareos".
+
+Linux example: :
+
+.. code-block:: ini
+  :caption: :file:`/etc/pam.d/bareos`
+
+  # check authorization
+  auth       required     pam_unix.so
+
+Bareos Console
+^^^^^^^^^^^^^^
+For PAM authentication a dedicated named console is used. Set the directive UsePamAuthentication=yes in the regarding Director-Console resource.
+
+.. code-block:: ini
+  :caption: :file:`bareos-dir.d/console/pam-console.conf`
+
+  Console {
+     Name = "PamConsole"
+     Password = "Secretpassword"
+     UsePamAuthentication = yes
+  }

docs/manuals/en/new_main_reference/source/developers/pam-techdoc.rst

@@ -0,0 +1,76 @@
+PAM
+===
+
+Introduction
+------------
+
+For a first overview the following diagram shows the connection sequence of a Bareos Console to a Bareos Director using PAM authentication. 
+
+.. uml::
+  :caption: Initiation of a Bareos Console connection using PAM authentication
+
+  hide footbox
+
+  actor user
+  participant "B-Console" as console
+  participant "Director" as director
+  participant "PAM-Linux" as pam
+
+  user -> console: start a named bconsole
+  console <-> director: initiate TCP connection
+  console <-> director: initiate a secure TLS connection (cert/psk)
+  console <-> director: primary challenge/response authentication
+
+  == PAM user authentication ==
+  note left of pam: i.e. pam_unix.so\nconfigured in /etc/pam.d/bareos
+  autonumber
+  director -> pam: initialize pam module with user name
+  director <- pam: request password via callback
+  console <- director: send "Password:" request (encrypted via TLS)
+  user <- console: prompt "Password:"
+  user -> console: enter password (hidden)
+  console -> director: send password (encrypted via TLS)
+  director -> pam: give back password
+  director <- pam: return success of authentication
+  console <- director: send welcome message
+  user <- console: show welcome message
+  director -> pam: shutdown pam module
+
+  autonumber stop
+  == PAM user authentication end ==
+
+  ... do something with console ...
+
+  user -> console: quit session ('q'; Ctrl + D)
+  console <-> director: Shutdown TLS
+  console <-> director: Finish TCP connection
+
+Configuration
+-------------
+To enable PAM authentication two systems have to be configured. The PAM module in the operating system and the Bareos Console.
+
+PAM Module
+^^^^^^^^^^
+This is depending on the operating system (OS) and on the used pam module. For details see the manuals of your OS. The name of the service that has to be registered is "bareos". 
+
+Linux example: : 
+
+.. code-block:: ini
+  :caption: :file:`/etc/pam.d/bareos`
+  
+  # check authorization
+  auth       required     pam_unix.so
+
+Bareos Console
+^^^^^^^^^^^^^^
+For PAM authentication a dedicated named console is used. Set the directive UsePamAuthentication=yes in the regarding Director-Console resource.
+
+.. code-block:: ini
+  :caption: :file:`bareos-dir.d/console/pam-console.conf`
+
+  Console {
+     Name = "PamConsole"
+     Password = "Secretpassword"
+     UsePamAuthentication = yes
+  }
+