TELODENDRIA-CONFIG(7) Miscellaneous Information Manual TELODENDRIA-CONFIG(7)

telodendria-config — Telodendria configuration.

Telodendria is designed to be configurable. It is configured using JSON, which is intended to be submitted via the administrator API. This page documents Telodendria's configuration JSON format, which is used both in the administrator API, and on the disk in the database. The configuration file on the disk in the database is config.json, though that file should not be edited directly. Use the API described in telodendria-admin(7) instead.

Here are the top-level directives:

listenArr
An array of listener description objects. Telodendria supports listening on multiple ports, and each port is configured independently of the others. A listener description object looks like this:
port
The port to listen on. Telodendria will bind to all interfaces, so it is recommended to configure your firewall so you can control what is allowed to access the Telodendria ports. Note that Telodendria offers all APIs over each port; there is no way to control which APIs are available over which ports, although all APIs should be safe against attacks, so this should not be a major concern.

port should be a decimal port number. This directive is required. Common port numbers are 8008 for non-TLS, and 8448 for TLS.

tlsObj|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:
file
A certificate file in the format native to the platform's TLS library. This can be an absolute path, otherwise it is relative to the data directory.
file
A key file in the format native to the platform's TLS library. It follows the same rules as the certificate file.
name
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. name should be a DNS name that can be publically resolved. This directive is required.
url
Set the server's base URL. url 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 it is not specified, it is automatically deduced from the server name.

url
The identity server that clients should use to perform identity lookups.

url follows the same rules as baseUrl.

This directive is optional. If it is not specified, it is automatically set to be the same as the base URL.

uidObj
The effective UNIX user and group to drop to after binding to the socket and changing the filesystem root for the process. This only works if Telodendria is running as the root user, and is used as a security mechanism. If this option is set and Telodendria is started as a non-priviledged user, then a warning is printed to the log if that user does not match what's specified here. This directive is optional, but should be used as a sanity check, if nothing more, to make sure the permissions are working properly.

This directive takes an object with the following directives:

user
The UNIX username to drop to. If runAs is specified, this directive is required.
group
The UNIX group to drop to. This directive is optional; if it is not specified, then the value of uid is copied.
log directive is configured to write to a file, the log file will be written in the data directory. directory should be an absolute path, under which all Telodendria data will live.
true|false
Whether to enable federation with other Matrix homeservers or not. Matrix is by its very nature a federated protocol, but if you just want to run 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.
true|false
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 add users via the administrator API. In an ideal world, everyone would run their own 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 public IPv4 addresses are becoming increasingly harder to come by. If you would like to provide a service to those that are unable to run their own homeserver, you can set this to true, which will allow anyone to create an account. Telodendria should be capable of handling a large amount of users without difficulty or security issues. This directive is required.
logObj
The log file 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:
stdout|file|syslog
The lot output destination. If set to file, Telodendria will log to telodendria.log inside the data directory.
error|warning|notice|message|debug
The level of messages to log at. Each level shows all the levels above it. For example, setting the level to error will show only errors, while setting the level to warning will show warnings and errors. notice shows notices, warnings, and errors, and so on. The debug level shows all messages.
format|none|default
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(3). This option only applies if log is "stdout" or "file".
true|false
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.

This option only applies if log is "stdout".

count
How many worker threads to spin up to handle requests. 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.
count
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 typically does not need to be adjusted.
bytes
The maximum size of the cache. Telodendria relies heavily on caching to speed things up. 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 that has a lot of memory, you'll get better performance if this option is set higher. Otherwise, this value should be lowered on systems that have minimal memory available.

config.json
The configuration file stored on the filesystem in the data directory. It is not recommended to edit this directly.
/var/telodendria
The recommended data directory.

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 as a package, it is possible that the example configurations were placed in the default locations for such files on your operating system.

telodendria-setup(7), telodendria-admin(7) telodendria(8)

April 20, 2023 Telodendria Project