forked from Telodendria/Telodendria
218 lines
8.5 KiB
Groff
218 lines
8.5 KiB
Groff
.Dd $Mdocdate: April 20 2023 $
|
|
.Dt TELODENDRIA-CONFIG 7
|
|
.Os Telodendria Project
|
|
.Sh NAME
|
|
.Nm telodendria-config
|
|
.Nd Telodendria configuration.
|
|
.Sh DESCRIPTION
|
|
.Pp
|
|
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
|
|
.Pa config.json ,
|
|
though that file should not be edited directly. Use the API described
|
|
in
|
|
.Xr telodendria-admin 7
|
|
instead.
|
|
.Sh DIRECTIVES
|
|
Here are the top-level directives:
|
|
.Bl -tag -width Ds
|
|
.It Ic listen Ar 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:
|
|
.Bl -tag -width Ds
|
|
.It Ic port Ar 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.
|
|
.Pp
|
|
.Ar port
|
|
should be a decimal port number. This directive is required. Common
|
|
port numbers are 8008 for non-TLS, and 8448 for TLS.
|
|
.It Ic tls Ar 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
|
|
.Ic tls
|
|
is not
|
|
.Ar null
|
|
or
|
|
.Ar false ,
|
|
then it can be an object with the following directives:
|
|
.Bl -tag -width Ds
|
|
.It Ic cert Ar 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.
|
|
.It Ic key Ar file
|
|
A key file in the format native to the platform's TLS library.
|
|
It follows the same rules as the certificate file.
|
|
.El
|
|
.El
|
|
.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
|
|
.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 set 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 data directory.
|
|
.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 event 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 config.json
|
|
The configuration file stored on the filesystem in the data
|
|
directory. It is not recommended to edit this directly.
|
|
.It Pa /var/telodendria
|
|
The recommended data directory.
|
|
.El
|
|
.Sh EXAMPLES
|
|
.Pp
|
|
A number of example configuration files are shipped with
|
|
Telodendria's source code. They can be found in the
|
|
.Pa 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.
|
|
.Sh SEE ALSO
|
|
.Xr telodendria-setup 7 ,
|
|
.Xr telodendria-admin 7
|
|
.Xr telodendria 8
|