forked from Telodendria/Telodendria
206 lines
8.1 KiB
Groff
206 lines
8.1 KiB
Groff
.Dd $Mdocdate: October 24 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 OpenBSD-style syntax, though it is a little more rigid in its
|
|
parser. All values must be surrounded by quotes, and each directive
|
|
must be ended with a semicolon.
|
|
.Sh MACROS
|
|
Macros can be defined that will later be expanded in context.
|
|
Macro names must start with a letter, digit, or underscore, and may
|
|
contain only those characters. Macros are not expanded inside quotes.
|
|
.sp
|
|
For example:
|
|
.Bd -literal -offset indent
|
|
macro1 = "value1";
|
|
directive $macro1;
|
|
.Ed
|
|
.Sh GLOBAL OPTIONS
|
|
Here are the settings that can be set globally:
|
|
.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 server-name 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 base-url 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 identity-server Ar url
|
|
The identity server that clients should use to perform identity lookups.
|
|
.Pp
|
|
.Ar url
|
|
follows the same rules as
|
|
.Ic base-url .
|
|
.Pp
|
|
This directive is optional. If it is not specified, it is automatically
|
|
set to be the same as the base URL.
|
|
.It Ic id Ar uid Ar gid
|
|
The effective UNIX user and group to drop to after binding to the socket
|
|
and changing the filesystem root. This only works if Telodendria is
|
|
running as the root user, and is used as a security mechanism. If 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
|
|
required, even if Telodendria is unable to switch to the given user and
|
|
group. It should be used as a sanity check to make sure the permissions are
|
|
working properly.
|
|
.It Ic data-dir 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 stdout|file|syslog
|
|
The log configuration. Telodendria uses its own logging facility, which can output
|
|
logs to standard output, a file, or the syslog. If set to
|
|
.Ar file ,
|
|
Telodendria will log to
|
|
.Pa telodendria.log
|
|
inside the
|
|
.Ic data-dir .
|
|
.Pp
|
|
A number of child directives can
|
|
be added to this directive to customize the log output:
|
|
.Bl -tag -width Ds
|
|
.It Ic level Ar error|warning|task|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 task
|
|
shows tasks, 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 max-connections 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 max-cache 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
|