# Configuration Telodendria is designed to be configurable. It is configured using JSON, which is intended to be submitted to the [Administrator API](admin/README.md). 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](admin/config.md). ## JSON Format Telodendria's configuration is just a JSON object in the standard key-value form: ```json { "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.