pantalaimon/docs/man/pantalaimon.5

.Dd May 08, 2019
.Dt PANTALAIMON.CONF 5
.Os
.\" ---------------------------------------------------------------------------
.Sh NAME
.Nm pantalaimon.conf
.Nd pantalaimon configuration file
.\" ---------------------------------------------------------------------------
.Sh DESCRIPTION
.Xr pantalaimon 1 reads configuration data in the INI file format.
The configuration file is used to configure
.Nm pantalaimon
homeservers.
.Pp
The sections inside the configuration file represent a pantalaimon proxy
instance with the section name enclosed in square brackets representing an user
chosen instance name.
.Pp
The following keys are required in the proxy instance sections:
.Bl -tag -width 3n
.It Cm Homeserver
The URI of the homeserver that the pantalaimon proxy should forward requests to,
without the matrix API path but including the http(s) schema.
.El
.Pp
The following keys are optional in the proxy instance sections:
.Bl -tag -width 3n
.It Cm ListenAddress
The address where the daemon will listen to client connections for this
homeserver. Defaults to "localhost".
.It Cm ListenPort
The port where the daemon will listen to client connections for this
homeserver. Note that the listen address/port combination needs to be unique
between different homeservers. Defaults to "8009".
.It Cm Proxy
An URI of a HTTP proxy that the daemon should use when making requests to the
homeserver.
.Nm pantalaimon
only supports HTTP proxies. The default is to make a direct connection to the
homeserver.
.It Cm SSL
A boolean that decides if SSL verification should be enabled for outgoing
connections to the homeserver. Defaults to "True".
.It Cm 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".
.It Cm UseKeyring
This option configures if a proxy instance should use the OS keyring to store
its own access tokens. The access tokens are required for the daemon to resume
operation. If this is set to "No", access tokens are stored in the pantalaimon
database in plaintext. Defaults to "Yes".
.It Cm SearchRequests
This option configures if the proxy should make additional HTTP requests to the
server when clients use the search API endpoint. Some data that is required to
fill out a complete search response is only available 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"
.Nm pantalaimon
will make additional HTTP requests to fetch the unavailable data from the
Homeserver, note that this will make the search much slower. If this is set to
"Off"
.Nm pantalaimon
will not make any additional HTTP requests and will leave some data fields in
the search response empty. Defaults to "Off".
.It Cm IndexEncryptedOnly
A configuration option to decide if
.Nm pantalaimon
should fetch the history for
unencrytped rooms as well as for encrypted ones. If True, only the history for
encrypted rooms is fetched and indexed. Search requests for non-encrypted
rooms are forwarded to the Homeserver. Defaults to "True".
.It Cm 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.
.It Cm HistoryFetchDelay
The amount of time to wait between room message history requests to the
Homeserver in ms. Defaults to 3000.
.El
.Pp
Aditional to the homeserver section a special section with the name
.Cm Default
can be used to configure the following values for all homeservers:
.Cm ListenAddress ,
.Cm ListenPort ,
.Cm Proxy ,
.Cm SSL
.Cm IgnoreVerification
.Cm UseKeyring
.Pp
The
.Cm Default
section has the following keys that globally change the behaviour of the daemon:
.Bl -tag -width 3n
.It Cm LogLevel
Set the log level of the daemon, can be one of
.Ar error ,
.Ar warning ,
.Ar info ,
.Ar debug .
Defaults to
.Ar warning .
.It Cm 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
.Ar On ,
.Ar Off .
Defaults to
.Ar On .

.El
.\" ---------------------------------------------------------------------------
.Sh FILES
.Nm pantalaimon
supports the XDG Base Directory Specification, the default locations can be
overridden using appropriate environment variables.
.Pp
.Bl -tag -width 34 -compact
.It Pa ~/.config/pantalaimon/pantalaimon.conf
Default location of the configuration file.
.El
.\" ---------------------------------------------------------------------------
.Sh EXAMPLES
The following example shows a configured pantalaimon proxy with the name
.Em Clocktown ,
the homeserver URL is set to
.Em https://example.org ,
the pantalaimon proxy is listening for client connections on the address
.Em localhost ,
and port
.Em 8009 .
The pantalaimon proxy is making connections to the homeserver through the proxy
.Em http://localhost:8009 ,
finally, SSL verification is disabled.
.Pp
Additionally to the
.Em Clocktown
section the
.Em 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
.Em Debug .
.Bd -literal -offset indent
[Default]
LogLevel = Debug
SSL = True
Notifications = On

[Clocktown]
Homeserver = https://localhost:8448
ListenAddress = localhost
ListenPort = 8009
Proxy = http://localhost:8080
SSL = False
.Ed
.\" ---------------------------------------------------------------------------
.Sh SEE ALSO
.Xr pantalaimon 8
.\" ---------------------------------------------------------------------------
.Sh AUTHORS
.Nm
was written by
.An Damir Jelić Aq Mt poljar@termina.org.uk .