NAME

     pantalaimon.conf — pantalaimon configuration file

DESCRIPTION

     pantalaimon(1) reads configuration data in the INI file format. The configuration file is
     used to configure pantalaimon homeservers.

     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.

     The following keys are required in the proxy instance sections:

     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.

     The following keys are optional in the proxy instance sections:

     ListenAddress
          The address where the daemon will listen to client connections for this homeserver.
          Defaults to "localhost".

     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".

     Proxy
          An URI of a HTTP proxy that the daemon should use when making requests to the
          homeserver.  pantalaimon only supports HTTP proxies. The default is to make a direct
          connection to the homeserver.

     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 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".

     DropOldKeys
          This option configures if a proxy instance should only keep the latest version of a
          room key from a certain user around. This effectively means that only newly incoming
          messages will be decryptable, the proxy will be unable to decrypt the room history.
          Defaults to "No".

     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" 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" pantalaimon will not make any additional HTTP requests
          and will leave some data fields in the search response empty. Defaults to "Off".

     IndexEncryptedOnly
          A configuration option to decide if 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".

     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.

     Aditional to the homeserver section a special section with the name Default can be used to
     configure the following values for all homeservers: ListenAddress, ListenPort, Proxy, SSL
     IgnoreVerification UseKeyring

     The Default section has the following keys that 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, the default locations can be
     overridden using appropriate environment variables.

     ~/.config/pantalaimon/pantalaimon.conf
         Default location of the configuration file.

EXAMPLES

     The following example shows a configured pantalaimon proxy with the name Clocktown, 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, 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>.