.nh
.TH bluechi-agent.conf 5
.SH NAME
agent.conf \- Configuration file to bootstrap bluechi-agent

.SH DESCRIPTION
The basic file definition used to bootstrap bluechi-agent.

.SH Format
The bluechi-agent configuration file is using the
systemd configuration file format
\[la]https://www.freedesktop.org/software/systemd/man/systemd.syntax.html\[ra]\&. Contrary to this, there is no need for the \fB\\\fR 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.

.SS \fBbluechi-agent\fP section
All fields to bootstrap the bluechi-agent are contained in the \fBbluechi-agent\fP section. The following keys are understood
by \fBbluechi-agent\fR\&.

.SS \fBNodeName\fP (string)
The unique name of this agent. The option defaults to the system's hostname.

.SS \fBControllerAddress\fP (string)
SD Bus address used by \fBbluechi-agent\fR to connect to \fBbluechi\fR\&. See \fBman sd_bus_set_address\fR for its format.
Overrides any setting of \fBControllerHost\fR or \fBControllerPort\fR defined in the configuration file as well as the respective CLI
options. The option doesn't have a default value.

.SS \fBControllerHost\fP (string)
The host used by \fBbluechi-agent\fR to connect to \fBbluechi\fR\&. Must be a valid IPv4 or IPv6. ControllerHost defaults to localhost 127.0.0.1. It's mandatory to set this field if the bluechi agent is on a remote system.

.SS \fBControllerPort\fP (uint16_t)
The port on which \fBbluechi\fR is listening for connection request and the \fBbluechi-agent\fR is connecting to. By default port
\fB842\fR is used.

.SS \fBHeartbeatInterval\fP (long)
The interval between two heartbeat signals sent to bluechi in milliseconds. If an agent is not connected, it will retry to connect on each heartbeat. Setting this options to values smaller or equal to 0 disables it. This option will overwrite the heartbeat interval defined in the configuration file.

.SS \fBControllerHeartbeatThreshold\fP (long)
The threshold in milliseconds to determine whether a bluechi agent is disconnected. If the controller's last heartbeat signal was received before this threshold, bluechi agent assumes that the controller is down or the connection was cut off and performs a disconnect.

.SS \fBLogLevel\fP (string)
The level used for logging. Supported values are:
.IP \(bu 2
\fBDEBUG\fR
.IP \(bu 2
\fBINFO\fR
.IP \(bu 2
\fBWARN\fR
.IP \(bu 2
\fBERROR\fR

.PP
By default \fBINFO\fR level is used for logging.

.SS \fBLogTarget\fP (string)
The target where logs are written to. Supported values are:
.IP \(bu 2
\fBstderr\fR
.IP \(bu 2
\fBstderr-full\fR
.IP \(bu 2
\fBjournald\fR

.PP
By default \fBjournald\fR is used as the target.

.SS \fBLogIsQuiet\fP (string)
If this flag is set to \fBtrue\fR, no logs are written by bluechi. By default the flag is set to \fBfalse\fR\&.

.SS \fBIPReceiveErrors\fP (string)
If this flag is set to \fBtrue\fR, it enables extended, reliable error message passing for
the peer connection with the controller. This results in BlueChi receiving errors such as
host unreachable ICMP packets instantly and possibly dropping the connection. This is
useful to detect disconnects faster, but should be used with care as this might cause
unnecessary disconnects in less robut networks.
Default: true.

.SS \fBTCPKeepAliveTime\fP (long)
The number of seconds the TCP connection of the agent with the controller needs to be idle before
keepalive packets are sent. When \fBTCPKeepAliveTime\fR is set to 0, the system default will be used.
Default: 1s.

.SS \fBTCPKeepAliveInterval\fP (long)
The number of seconds between each keepalive packet. When \fBTCPKeepAliveInterval\fR is set to 0,
the system default will be used.
Default: 1s.

.SS \fBTCPKeepAliveCount\fP (long)
The number of keepalive packets without ACK from the controller till the connection is
dropped. When \fBTCPKeepAliveCount\fR is set to 0, the system default will be used.
Default: 6.

.SS \fBConnectionRetryCountUntilQuiet\fP (long)
The number of connection retries until the logs of bluechi-agent are silenced in order to not
perpetually produce logs. bluechi-agent will still keep trying to reconnect. After a successful
connection, the original setting of \fBLogIsQuiet\fP will be restored.
Default: 10.

.SH Example
Using \fBControllerHost\fR and \fBControllerPort\fR options:

.EX
[bluechi-agent]
NodeName=agent-007
ControllerHost=127.0.0.1
ControllerPort=842
LogLevel=DEBUG
LogTarget=journald
LogIsQuiet=false
.EE

.PP
Using \fBControllerAddress\fR option:

.EX
[bluechi-agent]
NodeName=agent-007
ControllerAddress=tcp:host=127.0.0.1,port=842
LogLevel=DEBUG
LogTarget=journald
LogIsQuiet=false
.EE

.PP
Using a value that is continued on multiple lines:

.EX
[bluechi-agent]
NodeName=agent-007
ControllerAddress=tcp:
  host=127.0.0.1,
  port=842
LogLevel=DEBUG
LogTarget=journald
LogIsQuiet=false
.EE

.SH FILES
Distributions provide the \fB/usr/share/bluechi/config/agent.conf\fP file which defines bluechi-agent configuration defaults. Administrators can copy this file to \fB/etc/bluechi/agent.conf\fP and specify their own configuration.

.PP
Administrators can also use a "drop-in" directory \fB/etc/bluechi/agent.conf.d\fP to drop their configuration changes.

.SH SEE ALSO
\fBbluechi-agent(1)
\[la]https://github.com/eclipse\-bluechi/bluechi/blob/main/doc/man/bluechi\-agent.1.md\[ra]\fP