forked from lda/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