Convert configuration documentation.

This commit is contained in:
Jordan Bancino 2023-09-09 17:43:43 -04:00
parent 6dcfa7dc02
commit 0b820b80f7
2 changed files with 246 additions and 218 deletions

246
docs/user/config.md Normal file
View file

@ -0,0 +1,246 @@
# Configuration
Telodendria is designed to be configurable. It is configured using
JSON, which is intended to be submitted to the [Administrator
API](admin/README.md). This document details Telodendria's configuration
JSON format, which is used in both the administrator API and on-disk
in the database. The configuration file on the disk in the databsae
is `config.json`, though that file should not be edited by hand.
Use the API described in
[Administrator API → Configuration](admin/config.md).
## JSON Format
Telodendria's configuration is just a JSON object in the standard
key-value form:
```json
{
"serverName": "telodendria.io",
"listen": [
{
"port": 8008,
"tls": false
}
]
/* ... */
}
```
Some keys, called *directives* in this document, have values that are
objects themselves.
## Directives
Here are the top-level directives:
- **listen:** `Array`
An array of listener description objects. Telodendria supports
listening on multiple ports, and each port is configured
independently of the others. A listener object looks like this:
- **port:** `integer`
The port to listen on. Telodendria will bind to all interfaces,
so it is recommended to configure your firewall to only allow
access on the desired interfaces. Note that Telodendria offers all
APIs over each port, including the administrator APIs; there is no
way to control which APIs are made available over which ports. If
this is a concern, a reverse-proxy such as `relayd` can be placed
in front of Telodendria to block access to undesired APIs.
- **tls:** `Object|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:
- **cert:** `String`
The full path—or path relative to the data
directory—of the certificate file to load. The certificate
file should be in the format expected by the platform's TLS
library.
- **key:** `String`
Same as **cert**, but this should be the private key that matches
the certificate being used.
- **threads:** `Integer`
How many worker threads to spin up to handle requests for this
listener. 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.
Note that this can be set as low as 0; in that case, the listener
will never respond to requests. Each listener needs to have at
least one thread to be useful. Also note that Telodendria may spin
up additional threads for background work, so the actual total
thread count at any given time may exceed the sum of threads
specified in the configuration.
This directive is optional. The default value is `4` in the upstream
code, but your software distribution may have patched this to be
different.
- **maxConnections:** `Integer`
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 is optional, defaults to `32`, and typically
does not need to be adjusted.
- **serverName:** `String`
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. **serverName** should be a DNS name that
can be publicly resolved. This directive is required.
- **baseUrl:** `String`
Set the server's base URL. **baseUrl** 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 unspecified, it is automatically
deduced from the server name.
- **identityServer:** `String`
The identity server that clients should use to perform identity
lookups. **identityServer** folows the same rules as **baseUrl**.
It also is optional, and is set to be the same as the **baseUrl**
if left unspecified.
- **runAs:** `Object`
The effective Unix user and group to drop to after binding to the
socket and completing any setup that may potentially require
elevated privileges. This directive only takes effect if
Telodendria is started as the root user, and is used as a security
mechanism. If this option is set and Telodendria is started as a
non-privileged user, then a warning is printed to the log if that
user and group do not match what's specified here. This directive
is optional, but should be used as a sanity check even if not
running as `root`, just to make sure you have your permissions
working properly.
This directive takes an object with the following directives:
- **uid:** `String`
The Unix username to switch to. If **runAs** is specified, this
directive is required.
- **gid:** `String`
The Unix group to switch to. This directive is optional; if left
unspecified, then the value of **uid** is copied.
- **federation:** `Boolean`
Whether or not to enable federation with other Matrix homeservers.
Matrix by its very nature is a federated protocol, but if you just
want to rn 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.
- **registration:** `Boolean`
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 allow only certain users to be registered using
registration tokens, which can be managed via the administrator API.
This directive is required.
In an ideal world, everyone would run their own Matrix 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 IPv4 addresses are becoming increasingly
hard to come by. If you would like to provide a service to those
that are unable to run their homeserver, then set this to `true`,
thereby allowing anyone to create an account.
Telodendria *should* be capable of handling a large amount of users
without difficulty, but it is targetted at smaller deployments.
- **log:** `Object`
The logging 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:
- **output:** `Enum`
The log output destination. This can either be `stdout`, `file`,
or `syslog`. If set to `file`, Telodendria will log to
`telodendria.log` inside the data directory.
- **level:** `Enum`
The level of messages to log. Each level shows all the levels above
it. The levels are as follows:
- `error`
- `warning`
- `notice`
- `message`
- `debug`
For example, setting the level to `error` will show only errors,
while setting the level to `warning` will show both warnings
*and* errors. The `debug` level shows all messages.
- **timestampFormat:** `Enum`
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()` documentation. This option only
applies if **log** is `stdout` or `file`.
- **color:** `Boolean`
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.
- **maxCache:** `Integer`
The maximum size of the cache. Telodendria relies heavily on caching
for performance reasons. 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 with a lot of memory
to spare, you'll get better performance if this option is set higher.
Otherwise, this value should be lowered on systems that have a
minimal amount of memory available.
## Examples
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 from a package, it is possible that the example
configurations were placed in the default locations for such files on
your operating system.

View file

@ -1,218 +0,0 @@
.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