bluechi.conf(5)

💖 bluechi.conf — the manual page, but make it make sense 💖

okay bestie, gather round, because this is the config file that bootstraps bluechi-controller. it's bluechi.conf(5), it lives in the File Formats Manual (section 5, very demure, very official), and it's genuinely not that deep once you read it. let's go 🫶

---

✨ NAME ✨

bluechi-controller.conf — the configuration file you use to bootstrap bluechi-controller. that's it. that's the name. 💅

---

🌸 DESCRIPTION 🌸

This is the basic file definition used to bootstrap bluechi-controller. like, the starter pack. the foundation. the blueprint. 🎀

📝 Format 📝

The bluechi-controller config file uses the systemd configuration file format (https://www.freedesktop.org/software/systemd/man/systemd.syntax.html). iconic of it, honestly.

But — and this is the plot twist — you do not need the \ symbol at the end of a line to continue a value onto the next line. nope! A value continued over multiple lines just gets concatenated by bluechi. effortless. ✨

The maximum line length supported is 500 characters. If your value goes over that limit, use multiple, indented lines. don't fight it, just indent. 💜

Global options for the bluechi controller live in the [bluechi-controller] section. And on top of that, sections named [node NODENAME] let you set options that are specific to one particular node. per-node customization? we love to see it. 👑

---

🌈 Global options 🌈

• UseTCP (string) — if this flag is set to true, it turns on the connection handler so agents can connect remotely via TCP/IP to the controller. if it's disabled, all the other TCP options — like ControllerPort or TCPKeepAliveTime — just don't get used. the TCP handler can run alongside the handler for local connections (Unix Domain Socket) and the systemd socket activated handler. Default: true.
• UseUDS (string) — if this flag is set to true, it turns on the connection handler so agents can connect locally via Unix Domain Socket (UDS) to the controller. the UDS handler can run alongside the handler for remote connections (TCP/IP) and the systemd socket activated handler. Default: true.
• ControllerPort (uint16_t) — the port bluechi-controller listens on to establish connections with the bluechi-agent. by default, port 842 is used.
• AllowedNodeNames (string) — a comma separated list of unique bluechi-agent names. only nodes whose names show up in this list — or nodes with Allowed=true in their own separate node section — can connect to bluechi-controller. these names are defined in the agent's configuration file under the NodeName option (see bluechi-agent.conf(5)).
• HeartbeatInterval (long) — the interval for periodically checking a node's connectivity, based on heartbeat signals sent to bluechi, in milliseconds. a value of 0 disables it.
• NodeHeartbeatThreshold (long) — the threshold, in milliseconds, used to determine whether a node is disconnected. if the node's last heartbeat signal was received before this threshold, bluechi assumes the node is down or the connection was cut off, and it performs a disconnect. bye bestie 💀
• LogLevel (string) — the level used for logging. supported values are:
  • DEBUG
  • INFO
  • WARN
  • ERROR

by default, the 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. (so yeah, default = it talks. a lot. 😭)
• IPReceiveErrors (string) — if this flag is set to true, it enables extended, reliable error message passing for the peer connection with all agents. this means BlueChi receives errors like host unreachable ICMP packets instantly and possibly drops the connection. super useful for detecting disconnects faster, but use it with care — it might cause unnecessary disconnects in less robust networks. Default: true.
• TCPKeepAliveTime (long) — the number of seconds an 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) — 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 an ACK from an agent until 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 this 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. 🧚

• AllowDependenciesOn (string) — a comma separated list of bluechi-agent names on which the configured node can request services to be started with bluechi-proxy@.service. by default, this list is empty, and thus all proxies are denied. no cap. the names are defined in the agent's configuration file under the NodeName option (see bluechi-agent.conf(5)).

---

⭐ Example ⭐

A basic example of a configuration file for bluechi:

[bluechi-controller]
ControllerPort=842
AllowedNodeNames=agent-007,agent-123
LogLevel=DEBUG
LogTarget=journald
LogIsQuiet=false

Example with specific configuration for node agent-009:

[bluechi-controller]
AllowedNodeNames=agent-007,agent-123

[node agent-009]
Allowed=true
RequiredSelinuxContext=haproxy_t
AllowDependenciesOn=agent-007

Example using a value that is continued on multiple lines:

[bluechi-controller]
ControllerPort=842
AllowedNodeNames=agent-007,
   agent-123,
   agent-456,
   agent-789
LogLevel=DEBUG
LogTarget=journald
LogIsQuiet=false

see how clean that is?? no backslashes needed. main character formatting behavior. 💅✨

---

🎀 FILES 🎀

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. copy-paste and customize, the classic. 🫶

Administrators can also use a "drop-in" directory at /etc/bluechi/controller.conf.d to drop their configuration changes. such drop-ins are especially useful for per-node configuration, since they can extend the list of available nodes without modifying the base configuration file. chef's kiss. 👑

---

🔥 SEE ALSO 🔥

• bluechi-controller(1)
• https://github.com/eclipse-bluechi/bluechi/blob/main/doc/man/bluechi-controller.1.md

---

and that's the whole page bestie, you ate it 💖 this was bluechi.conf(5) from the File Formats Manual, section 5, brought to you by the bluechi project. now go write a config that slays. 🌈⭐🎀🦋