PANTALAIMON.CONF(5)

🎀 pantalaimon.conf — the glow-up guide (section 5, file formats energy) 🎀

okay bestie, listen up 💖 this is the manual page for pantalaimon.conf, aka the config file for pantalaimon(1). She's a File Formats Manual girlie. Let's get into it.

---

✨ NAME ✨

pantalaimon.conf — the configuration file for pantalaimon 🦋

---

🌸 DESCRIPTION 🌸

So pantalaimon(1) reads its config data in the INI file format, no cap. This config file is literally what configures your pantalaimon homeservers. Periodt.

Every section in the config file = one pantalaimon proxy instance. The section name goes in square brackets, and you get to pick that instance name yourself. main character energy, you choose 💅

💖 Required keys (you literally cannot skip these) 💖

• Homeserver — the URI of the homeserver that the pantalaimon proxy should forward requests to. Heads up: no matrix API path, but yes include the http(s) schema. So like, the base URL only, bestie.

🫶 Optional keys (do them if you want, no pressure) 🫶

• ListenAddress — the address where the daemon will listen for client connections for this homeserver. Defaults to "localhost".
• ListenPort — the port where the daemon listens for client connections for this homeserver. ⚠️ Note that the listen address/port combo needs to be unique between different homeservers — do not be out here reusing ports, that's a vibe check fail. Defaults to "8009".
• Proxy — an URI of a HTTP proxy that the daemon should use when making requests to the homeserver. ngl pantalaimon only supports HTTP proxies, that's the limit. The default is to make a direct connection to the homeserver (no proxy at all).
• SSL — a boolean that decides if SSL verification should be enabled for outgoing connections to the homeserver. Defaults to "True". 🔒
• IgnoreVerification — a boolean that decides if device verification should be enabled. If this is True, devices will be marked as ignored automatically and encryption keys will be shared with them. If this is False, the user needs to verify, blacklist or ignore devices manually before messages can be sent to a room. Defaults to "False". 👀
• UseKeyring — this one configures if a proxy instance should use the OS keyring to store its own access tokens. Those access tokens are required for the daemon to resume operation, so they're kind of a big deal. If this is set to "No", access tokens are stored in the pantalaimon database in plaintext 😭 (yes, plaintext, be aware). Defaults to "Yes".
• DropOldKeys — configures if a proxy instance should only keep the latest version of a room key from a certain user around. Effectively this means only newly incoming messages will be decryptable, and the proxy will be unable to decrypt the room history. So like, the past is gone, bestie 💀. Defaults to "No".
• SearchRequests — configures if the proxy should make additional HTTP requests to the server when clients use the search API endpoint. Some data needed to fill out a complete search response only lives on the Homeserver (e.g. start/end tokens for the event context, or room state at a particular point in time).

If this option is set to "On", pantalaimon will make those additional HTTP requests to fetch the unavailable data from the Homeserver — ⚠️ note that this makes the search much slower. If this is set to "Off", pantalaimon makes no additional HTTP requests and will leave some data fields in the search response empty. Defaults to "Off".

• IndexEncryptedOnly — a config option to decide if pantalaimon should fetch the history for unencrypted rooms as well as for encrypted ones. If True, only the history for encrypted rooms is fetched and indexed, and search requests for non-encrypted rooms are forwarded to the Homeserver. Defaults to "True".
• IndexingBatchSize — the number of messages that should be requested from the Homeserver when we fetch and index messages from the room history. Defaults to 100.
• HistoryFetchDelay — the amount of time to wait between room message history requests to the Homeserver, in ms. Defaults to 3000. ⏳

---

👑 the special Default section 👑

Aditional to the homeserver sections, there's a special section named Default that you can use to configure these values for all homeservers at once:

ListenAddress, ListenPort, Proxy, SSL, IgnoreVerification, UseKeyring

and the Default section also has these keys, which globally change the behaviour of the daemon:

• LogLevel — set the log level of the daemon. Can be one of error, warning, info, debug. Defaults to warning.
• Notifications — the daemon sends out notifications for some actions that require users to interfere (unverified devices are in a room, interactive key verification events). This option enables or disables OS notifications. Can be one of On, Off. Defaults to On. 🔔

---

🌈 FILES 🌈

pantalaimon supports the XDG Base Directory Specification, and the default locations can be overridden using the appropriate environment variables. slay.

• ~/.config/pantalaimon/pantalaimon.conf — the default location of the configuration file. 💖

---

⭐ EXAMPLES ⭐

okay here's the moment. The example below shows a configured pantalaimon proxy named Clocktown, where the homeserver URL is set to https://localhost:8448, the pantalaimon proxy is listening for client connections on the address localhost, and port 8009. The pantalaimon proxy is making connections to the homeserver through the proxy http://localhost:8009, and finally, SSL verification is disabled.

Additionally to the Clocktown section, the Default section is also listed, and the default value for SSL verification is set to True, OS notifications are enabled, and the debug level is set to Debug.

[Default]
LogLevel = Debug
SSL = True
Notifications = On

[Clocktown]
Homeserver = https://localhost:8448
ListenAddress = localhost
ListenPort = 8009
Proxy = http://localhost:8080
SSL = False

---

💜 SEE ALSO 💜

• pantalaimon(8)

---

🧚 AUTHORS 🧚

pantalaimon.conf was written by Damir Jelić <poljar@termina.org.uk>. iconic of them honestly.

---

and that's the whole page, bestie 🫶 this one shipped as part of Debian, dated May 08, 2019, under the name PANTALAIMON.CONF(5). go forth and configure, you've got this 💅✨