telodendria/man/man5/telodendria.conf.5

.Dd $Mdocdate: December 9 2022 $
.Dt TELODENDRIA.CONF 5
.Os Telodendria Project
.Sh NAME
.Nm telodendria.conf
.Nd Configuration file for Telodendria
.Sh DESCRIPTION
.Nm
is the configuration file for the Telodendria homeserver,
.Xr telodendria 8 .
Telodendria is designed to be extremely configurable. As such,
it has a fairly extensive configuration file. The configuration
file can be passed to the Telodendria binary with the
.Sy -f
option, and is typically located at
.Pa /etc/telodendria.conf
.sp
.Nm
uses JSON for its configuration file syntax, which should be
familiar. Very early versions of
.Nm
used a  custom OpenBSD-style configuration file, but this was
not as versatile or familiar as JSON.
.Sh DIRECTIVES
Here are the top-level directives:
.Bl -tag -width Ds
.It Ic listen Ar port
The port to listen on. Telodendria will bind to all interfaces, but it
is recommended to configure your firewall so that it only listens on
localhost, and then configure a reverse proxy such as
.Xr relayd 8
in front of it, because Telodendria does not implement TLS. Note that
Telodendria doesn't provide multiple ports for the various services it
offers. ALl APIs are made available over the same port, so care should
be taken in
.Xr relayd.conf 5
to ensure that only the public Matrix API paths are made available over
the internet.
.Ar port
should be a decimal port number. This directive is entirely optional. If
it is omitted, then Telodendria will listen on port 8008 by default.
.It Ic serverName Ar 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.
.Ar name
should be a DNS name that can be publically resolved. This directive
is required.
.It Ic baseUrl Ar url
Set the server's base URL.
.Ar 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.
.Pp
This URL is the URL at which Matrix clients will connect to the server,
and is thus served as a part of the
.Pa .well-known
manifest.
.Pp
This directive is optional. If it is not specified, it is automatically
deduced from the server name.
.It Ic identityServer Ar url
The identity server that clients should use to perform identity lookups.
.Pp
.Ar url
follows the same rules as
.Ic baseUrl .
.Pp
This directive is optional. If it is not specified, it is automatically
set to be the same as the base URL.
.It Ic runAs Ar 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.
.Pp
This directive takes an object with the following directives:
.Bl -tag -width Ds
.It Ic uid Ar user
The UNIX username to drop to. If
.Ic runAs
is specified, this directive is required.
.It Ic gid Ar group
The UNIX group to drop to. This directive is optional; if it is not
specified, then the value of
.Ic uid
is copied.
.El
.It Ic dataDir Ar directory
The data directory into which Telodendria will write all user and event
information. Telodendria doesn't use a database like other Matrix homeserver
implementations; it uses a flat-file directory structure, similar to how an
SMTP server uses Maildirs to deliver email. This directive is required.
.Pp
Telodendria will
.Xr chroot 2
into this directory as soon as possible for security reasons. If the
.Ic log
directive is configured to write to a file, the log file will be written
in the data directory.
.Ar directory
should be an absolute path, under which all Telodendria data will live.
.It Ic federation Ar 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
.Ar true ,
however, if you wish to be able to communicate with users on other Matrix
servers. This directive is required.
.It Ic registration Ar true|false
Whether or not to enable new user registration or not. For security and anti-spam
reasons, you can set this to
.Ar 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 aset this to
.Ar 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.
.It Ic log Ar 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:
.Bl -tag -width Ds
.It Ic output Ar stdout|file|syslog
The lot output destination. If set to
.Ar file ,
Telodendria will log to
.Pa telodendria.log
inside the
.Ic dataDir .
.It Ic level Ar 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
.Ar error
will show only errors, while setting the level to
.Ar warning
will show warnings and errors.
.Ar notice
shows notices, warnings, and errors, and so on. The
.Ar debug
level shows all messages.
.It Ic timestampFormat Ar 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
.Ar none ,
.Ar default ,
or a formatter string as described by your system's
.Xr strftime 3 .
This option only applies if
.Ic log
is "stdout" or "file".
.It Ic color Ar 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.
.Pp
This option only applies if
.Ic log
is "stdout".
.El
.It Ic threads Ar 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.
.It Ic maxConnections Ar 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 even that it
undergoes a denial of service attack. It typically does not need to be adjusted.
.It Ic maxCache Ar 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.
.El
.Sh FILES
.Bl -tag -width Ds
.It Pa /etc/telodendria.conf
The default
.Xr telodendria 8
configuration file.
.It Pa /var/telodendria
The recommended data directory.
.El
.Sh EXAMPLES
Please consult the default
.Nm
that ships with Telodendria for a complete example. If you installed Telodendria
as a package, then the example should be located at the default location. If you
are building from source, you can find the default config in the
.Pa contrib/
directory.
.Sh SEE ALSO
.Xr telodendria 8