telodendria/docs/user/config.md

Configuration

Telodendria is designed to be configurable. It is configured using JSON, which is intended to be submitted to the Administrator API. This document details Telodendria's configuration JSON format, which is used in both the administrator API and on-disk in the database. The configuration file on the disk in the databsae is config.json, though that file should not be edited by hand. Use the API described in Administrator API → Configuration.

JSON Format

Telodendria's configuration is just a JSON object in the standard key-value form:

{
    "serverName": "telodendria.io",
    "listen": [
        {
            "port": 8008,
            "tls": false
        }
    ]

    /* ... */
}

Some keys, called directives in this document, have values that are objects themselves.

Directives

Here are the top-level directives:

• listen: Array

  An array of listener description objects. Telodendria supports listening on multiple ports, and each port is configured independently of the others. A listener object looks like this:

  • port: integer

    The port to listen on. Telodendria will bind to all interfaces, so it is recommended to configure your firewall to only allow access on the desired interfaces. Note that Telodendria offers all APIs over each port, including the administrator APIs; there is no way to control which APIs are made available over which ports. If this is a concern, a reverse-proxy such as relayd can be placed in front of Telodendria to block access to undesired APIs.

  • tls: Object|null|false

    Telodendria can be compiled with TLS support. If it is, then a particular listener can be set to use TLS for connections. If tls is not null or false, then it can be an object with the following directives:

    • cert: String

      The full path—or path relative to the data directory—of the certificate file to load. The certificate file should be in the format expected by the platform's TLS library.

    • key: String

      Same as cert, but this should be the private key that matches the certificate being used.

  • threads: Integer

    How many worker threads to spin up to handle requests for this listener. This should generally be less than the total CPU core count, to prevent overloading the system. The most efficient number of threads ultimately depends on the configuration of the machine running Telodendria, so you may just have to play around with different values here to see which gives the best performance.

    Note that this can be set as low as 0; in that case, the listener will never respond to requests. Each listener needs to have at least one thread to be useful. Also note that Telodendria may spin up additional threads for background work, so the actual total thread count at any given time may exceed the sum of threads specified in the configuration.

    This directive is optional. The default value is 4 in the upstream code, but your software distribution may have patched this to be different.

  • maxConnections: Integer

    The maximum number of simultanious connections to allow to the daemon. This option prevents the daemon from allocating large amounts of memory in the event that it undergoes a denial of service attack. It is optional, defaults to 32, and typically does not need to be adjusted.

• serverName: String

  Configure the domain name of your homeserver. Note that Matrix servers cannot be migrated to other domains, so once this is set, it should never change unless you want unexpected things to happen or you want to start over. serverName should be a DNS name that can be publicly resolved. This directive is required.

• pid: String Configure the file Telodendria writes its PID to.

• baseUrl: String

  Set the server's base URL. baseUrl should be a valid URL, complete with the protocol. It does not need to be the same as the server name; in fact, it is common for a subdomain of the server name to be the base URL for the Matrix homeserver.

  This URL is the URL at which Matrix clients will connect to the server, and is thus served as a part of the .well-known manifest.

  This directive is optional. If unspecified, it is automatically deduced from the server name.

• identityServer: String

  The identity server that clients should use to perform identity lookups. identityServer folows the same rules as baseUrl. It also is optional, and is set to be the same as the baseUrl if left unspecified.

• runAs: Object

  The effective Unix user and group to drop to after binding to the socket and completing any setup that may potentially require elevated privileges. This directive only takes effect if Telodendria is started as the root user, and is used as a security mechanism. If this option is set and Telodendria is started as a non-privileged user, then a warning is printed to the log if that user and group do not match what's specified here. This directive is optional, but should be used as a sanity check even if not running as root, just to make sure you have your permissions working properly.

  This directive takes an object with the following directives:

  • uid: String

    The Unix username to switch to. If runAs is specified, this directive is required.

  • gid: String

    The Unix group to switch to. This directive is optional; if left unspecified, then the value of uid is copied.

• federation: Boolean

  Whether or not to enable federation with other Matrix homeservers. Matrix by its very nature is a federated protocol, but if you just want to rn your own internal chat server with no contact with the outside, then you can use this option to disable federation. It is highly recommended to set this to true, however, if you wish to be able to communicate with users on other Matrix servers. This directive is required.

• registration: Boolean

  Whether or not to enable new user registration or not. For security and anti-spam reasons, you can set this to false. If you do, you can still allow only certain users to be registered using registration tokens, which can be managed via the administrator API. This directive is required.

  In an ideal world, everyone would run their own Matrix homeserver, so no public registration would ever be required. Unfortunately, not everyone has the means to run their own homeserver, especially because of the fact that IPv4 addresses are becoming increasingly hard to come by. If you would like to provide a service to those that are unable to run their homeserver, then set this to true, thereby allowing anyone to create an account.

  Telodendria should be capable of handling a large amount of users without difficulty, but it is targetted at smaller deployments.

• log: Object

  The logging configuration. Telodendria uses its own logging facility, which can output logs to standard output, a file, or the syslog. This directive is required, and it takes an object with the following directives:

  • output: Enum

    The log output destination. This can either be stdout, file, or syslog. If set to file, Telodendria will log to telodendria.log inside the data directory.

  • level: Enum

    The level of messages to log. Each level shows all the levels above it. The levels are as follows:

    • error
    • warning
    • notice
    • message
    • debug

    For example, setting the level to error will show only errors, while setting the level to warning will show both warnings and errors. The debug level shows all messages.

  • timestampFormat: Enum

    If you want to customize the timestamp format shown in the log, or disable it altogether, you can do so via this option. Acceptable values are none, default, or a formatter string as described by your system's strftime() documentation. This option only applies if log is stdout or file.

  • color: Boolean

    Whether or not to enable colored output on TTYs. Note that ANSI color sequences will not be written to a log file, only a real terminal, so this option only applies if the log is being written to a standard output which is connected to a terminal.

• maxCache: Integer

  The maximum size of the cache. Telodendria relies heavily on caching for performance reasons. The cache grows as data is loaded from the data directory. All cache is stored in memory. This option limits the size of the memory cache. If you have a system with a lot of memory to spare, you'll get better performance if this option is set higher. Otherwise, this value should be lowered on systems that have a minimal amount of memory available.

Examples

A number of example configuration files are shipped with Telodendria's source code. They can be found in the contrib/ directory if you are viewing the source code directly. Otherwise, if you installed Telodendria from a package, it is possible that the example configurations were placed in the default locations for such files on your operating system.