forked from Telodendria/Telodendria
210 lines
8.2 KiB
Groff
210 lines
8.2 KiB
Groff
.Dd $Mdocdate: February 15 2023 $
|
|
.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
|