man: Update controller.conf docs for new per-node options

doc/man/bluechi-controller.conf.5.md

@@ -13,11 +13,14 @@ The basic file definition used to bootstrap bluechi-controller.
 The bluechi-controller configuration file is using the
 [systemd configuration file format](https://www.freedesktop.org/software/systemd/man/systemd.syntax.html). Contrary to this, there is no need for the `\` symbol at the end of a line to continue a value on the next line. A value continued on multiple lines will just be concatenated by bluechi. The maximum line length supported is 500 characters. If the value exceeds this limitation, use multiple, indented lines.
 
-### **bluechi-controller** section
+Global options for the bluechi controller are contained in the
+**[bluechi-controller]** section. In addition, sections named **[node
+NODENAME]** allow setting options that are specific to the a
+particular node.
 
-All fields to bootstrap the bluechi controller are contained in the **bluechi-controller** section. The following keys are understood by `bluechi-controller`.
+## Global options
 
-#### **UseTCP** (string)
+### **UseTCP** (string)
 
 If this flag is set to `true`, it enables the connection handler for agents to connect
 remotely via TCP/IP to the controller. If disabled, all other TCP options such as the
@@ -26,33 +29,35 @@ The TCP handler can run alongside the handler for local connections (Unix Domain
 as well as the systemd socket activated handler.
 Default: true.
 
-#### **UseUDS** (string)
+### **UseUDS** (string)
 
 If this flag is set to `true`, it enables the connection handler for agents to connect
 locally via Unix Domain Socket (UDS) to the controller.
 The UDS handler can run alongside the handler for remote connections (TCP/IP) as well as
 the systemd socket activated handler.
 Default: true.
 
-#### **ControllerPort** (uint16_t)
+### **ControllerPort** (uint16_t)
 
 The port the bluechi-controller listens on to establish connections with the `bluechi-agent`. By default port `842` is used.
 
-#### **AllowedNodeNames** (string)
+### **AllowedNodeNames** (string)
 
-A comma separated list of unique bluechi-agent names. It's mandatory to set the option, only nodes with names mentioned
-in the list can connect to `bluechi-controller`. These names are defined in the agent's configuration file under `NodeName`
-option (see `bluechi-agent.conf(5)`).
+A comma separated list of unique bluechi-agent names. Only nodes with
+names mentioned in the list, or nodes with **Allowed=true** in a
+separate node section can connect to `bluechi-controller`.
 
-#### **HeartbeatInterval** (long)
+These names are defined in the agent's configuration file under `NodeName` option (see `bluechi-agent.conf(5)`).
+
+### **HeartbeatInterval** (long)
 
 The interval to periodically check node's connectivity based on heartbeat signals sent to bluechi, in milliseconds. A value of 0 disables it.
 
-#### **NodeHeartbeatThreshold** (long)
+### **NodeHeartbeatThreshold** (long)
 
 The threshold in milliseconds to determine whether a node is disconnected. If the node's last heartbeat signal was received before this threshold, bluechi assumes that the node is down or the connection was cut off and performs a disconnect.
 
-#### **LogLevel** (string)
+### **LogLevel** (string)
 
 The level used for logging. Supported values are:
 
@@ -63,7 +68,7 @@ The level used for logging. Supported values are:
 
 By default `INFO` level is used for logging.
 
-#### **LogTarget** (string)
+### **LogTarget** (string)
 
 The target where logs are written to. Supported values are:
 
@@ -73,11 +78,11 @@ The target where logs are written to. Supported values are:
 
 By default `journald` is used as the target.
 
-#### **LogIsQuiet** (string)
+### **LogIsQuiet** (string)
 
 If this flag is set to `true`, no logs are written by bluechi. By default the flag is set to `false`.
 
-#### **IPReceiveErrors** (string)
+### **IPReceiveErrors** (string)
 
 If this flag is set to `true`, it enables extended, reliable error message passing for
 the peer connection with all agents. This results in BlueChi receiving errors such as
@@ -86,25 +91,40 @@ useful to detect disconnects faster, but should be used with care as this might
 unnecessary disconnects in less robut networks.
 Default: true.
 
-#### **TCPKeepAliveTime** (long)
+### **TCPKeepAliveTime** (long)
 
 The number of seconds the individual TCP connection with an agent needs to be idle
 before keepalive packets are sent. When `TCPKeepAliveTime` is set to 0, the system
 default will be used.
 Default: 1s.
 
-#### **TCPKeepAliveInterval** (long)
+### **TCPKeepAliveInterval** (long)
 
 The number of seconds between each keepalive packet. When `TCPKeepAliveInterval` is set to 0,
 the system default will be used.
 Default: 1s.
 
-#### **TCPKeepAliveCount** (long)
+### **TCPKeepAliveCount** (long)
 
 The number of keepalive packets without ACK from an agent till the individual connection is dropped.
 When `TCPKeepAliveCount` is set to 0, the system default will be used.
 Default: 6.
 
+## Per-node options
+
+### **Allowed** (boolean)
+
+If true, the node with the section name is allowed to connect. See **AllowedNodeNames** above.
+
+### **RequiredSelinuxContext** (string)
+
+If set, the connecting node process must have the specified SELinux
+type label. Typically for local connections these would be
+bluechi_agent_t or haproxy_t.
+
+Note: this option only works when the agent connects using unix domain
+sockets.
+
 ## Example
 
 A basic example of a configuration file for `bluechi`:
@@ -116,9 +136,13 @@ AllowedNodeNames=agent-007,agent-123
 LogLevel=DEBUG
 LogTarget=journald
 LogIsQuiet=false
+
+[node agent-009]
+Allowed=true
+RequiredSelinuxContext=haproxy_t
 ```
 
-Using a value that is continued on multiple lines:
+Example using a value that is continued on multiple lines:
 
 ```
 [bluechi-controller]
@@ -137,6 +161,8 @@ LogIsQuiet=false
 Distributions provide the **/usr/share/bluechi/config/controller.conf** file which defines bluechi configuration defaults. Administrators can copy this file to **/etc/bluechi/controller.conf** and specify their own configuration.
 
 Administrators can also use a "drop-in" directory **/etc/bluechi/controller.conf.d** to drop their configuration changes.
+Such drop-ins are especially useful for per-node configuration as they can extend the list of available nodes without
+modifying the base configuration file.
 
 ## SEE ALSO