From 3f69954ca790adc4375dcb6b0bd7e3e03285c06e Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Sat, 9 Sep 2023 17:43:43 -0400 Subject: [PATCH] Convert configuration documentation. --- docs/user/config.md | 246 ++++++++++++++++++++++++++++++++++ man/man7/telodendria-config.7 | 218 ------------------------------ 2 files changed, 246 insertions(+), 218 deletions(-) create mode 100644 docs/user/config.md delete mode 100644 man/man7/telodendria-config.7 diff --git a/docs/user/config.md b/docs/user/config.md new file mode 100644 index 0000000..f021633 --- /dev/null +++ b/docs/user/config.md @@ -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. + diff --git a/man/man7/telodendria-config.7 b/man/man7/telodendria-config.7 deleted file mode 100644 index af02990..0000000 --- a/man/man7/telodendria-config.7 +++ /dev/null @@ -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