bluechi-agent.conf(5)

📦
version 1.3.0 · 2 versions
, in fedora 43, fedora 44

🦋 bluechi-agent.conf(5) — the manual, but make it a group chat 🦋

okay bestie, listen. this is the page for bluechi-agent.conf, and it's giving bootstrap energy. if you've ever wondered how bluechi-agent gets itself out of bed in the morning, it's this file. let's get into it 💅

✨ NAME ✨

agent.conf — the configuration file that bootstraps bluechi-agent. like, the whole glow-up starts here, no cap.

🌸 DESCRIPTION 🌸

The basic file definition used to bootstrap bluechi-agent. that's the vibe. it's the little file that tells the agent who it is and where it's going.

🎀 Format 🎀

The bluechi-agent configuration file is using the systemd configuration file format — yes, that one — at https://www.freedesktop.org/software/systemd/man/systemd.syntax.html.

but here's the plot twist, bestie: contrary to systemd, there is no need for the \ symbol at the end of a line to continue a value onto the next line. a value continued over multiple lines just gets concatenated by bluechi, effortlessly, main character behaviour ✨

the maximum line length supported is 500 characters. if your value exceeds that limit, use multiple, indented lines. periodt.

💜 bluechi-agent section 💜

All the fields you need to bootstrap the bluechi-agent live in the bluechi-agent section. Here's every key that bluechi-agent understands — yes, all of them, we're not skipping a single one 👑

⭐ NodeName (string)

The unique name of this agent. It defaults to the system's hostname. it's literally the agent's whole identity.

🦋 ControllerAddress (string)

The SD Bus address used by bluechi-agent to connect to bluechi. Peep man sd_bus_set_address for its format, iykyk.

heads up: this overrides any setting of ControllerHost or ControllerPort defined in the configuration file, as well as the respective CLI options. it wins, always.

The option doesn't have a default value.

🌈 ControllerHost (string)

The host used by bluechi-agent to connect to bluechi. 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. like, you literally have to, bestie.

💖 ControllerPort (uint16_t)

The port on which bluechi is listening for connection requests and the bluechi-agent is connecting to. By default, port 842 is used. iconic number, honestly.

💫 HeartbeatInterval (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 option to values smaller or equal to 0 disables it.

This option will overwrite the heartbeat interval defined in the configuration file.

🫶 ControllerHeartbeatThreshold (long)

The threshold, in milliseconds, used 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 that the connection was cut off — and it performs a disconnect. brutal but fair 💀

🎀 LogLevel (string)

The level used for logging. Supported values are:

  • DEBUG
  • INFO
  • WARN
  • ERROR

By default, INFO level is used for logging.

🌸 LogTarget (string)

The target where logs are written to. Supported values are:

  • stderr
  • stderr-full
  • journald

By default, journald is used as the target.

👑 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)

If this flag is set to true, 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.

so real: fast detection is great until it disconnects you for drama. use with care, bestie.

🧚 TCPKeepAliveTime (long)

The number of seconds the TCP connection of the agent with the controller 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)

The number of seconds between each keepalive packet. When TCPKeepAliveInterval is set to 0, the system default will be used.

Default: 1s.

💜 TCPKeepAliveCount (long)

The number of keepalive packets without ACK from the controller till the connection is dropped. When TCPKeepAliveCount is set to 0, the system default will be used.

Default: 6.

✨ ConnectionRetryCountUntilQuiet (long)

The number of connection retries until the logs of bluechi-agent are silenced, so it doesn't perpetually produce logs. bluechi-agent will still keep trying to reconnect though — it's persistent like that 🫶

After a successful connection, the original setting of LogIsQuiet will be restored.

Default: 10.

💅 Example 💅

Using ControllerHost and ControllerPort options:

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

Using ControllerAddress option:

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

Using a value that is continued on multiple lines:

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

🎀 FILES 🎀

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

Administrators can also use a "drop-in" directory /etc/bluechi/agent.conf.d to drop their configuration changes. drop-ins are the moment, fr fr ✨

🌈 SEE ALSO 🌈

and that's the whole page, bestie 🫶 this was bluechi-agent.conf(5) — shoutout to the File Formats Manual, and big love to the Eclipse BlueChi project for the source. go configure something gorgeous 💖

📦 where this page comes from