Convert configuration documentation.

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.
+

man/man7/telodendria-config.7

@@ -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