forked from Telodendria/Telodendria
Convert configuration documentation.
This commit is contained in:
parent
5067b5bcf0
commit
3f69954ca7
2 changed files with 246 additions and 218 deletions
246
docs/user/config.md
Normal file
246
docs/user/config.md
Normal 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.
|
||||||
|
|
||||||
|
|
@ -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
|
|
||||||
Loading…
Reference in a new issue