From bbf8f26889728e8f7b38bee2f7ab07491d525ecf Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Thu, 22 Sep 2022 09:47:52 -0400 Subject: [PATCH] Write man page for configuration file. --- README.txt | 8 +- docs/td.8 | 2 +- docs/telodendria.7 | 2 +- docs/telodendria.8 | 2 +- docs/telodendria.conf.5 | 165 ++++++++++++++++++++++++++++++ site/index.html | 220 ---------------------------------------- 6 files changed, 172 insertions(+), 227 deletions(-) create mode 100644 docs/telodendria.conf.5 diff --git a/README.txt b/README.txt index 04599c7..0459b35 100644 --- a/README.txt +++ b/README.txt @@ -7,9 +7,9 @@ Copyright (C) 2022 Jordan Bancino <@jordan:bancino.net> This is the source code for Telodendria, a Matrix homeserver written -in C. All of the documentation is available at https://telodendria.io, -or in site/index.html. +in C. All of the documentation is available as man pages in the +docs/ directory, or online at https://telodendria.io -If information is missing from those documents, please feel free to -reach out to #telodendria-general:bancino.net on Matrix. +If information is missing from the documentation, please feel free +to reach out to #telodendria-general:bancino.net on Matrix. diff --git a/docs/td.8 b/docs/td.8 index c55a150..c687189 100644 --- a/docs/td.8 +++ b/docs/td.8 @@ -1,4 +1,4 @@ -.Dd September 21, 2022 +.Dd $Mdocdate: September 22 2022 $ .Dt TD 8 .Os Telodendria Project .Sh NAME diff --git a/docs/telodendria.7 b/docs/telodendria.7 index 5caea39..b005abf 100644 --- a/docs/telodendria.7 +++ b/docs/telodendria.7 @@ -1,4 +1,4 @@ -.Dd September 21, 2022 +.Dd $Mdocdate: September 22 2022 $ .Dt TELODENDRIA 7 .Os Telodendria Project .Sh NAME diff --git a/docs/telodendria.8 b/docs/telodendria.8 index 541213b..bf48c2d 100644 --- a/docs/telodendria.8 +++ b/docs/telodendria.8 @@ -1,4 +1,4 @@ -.Dd September 21, 2022 +.Dd $Mdocdate: September 22 2022 $ .Dt TELODENDRIA 8 .Os Telodendria Project .Sh NAME diff --git a/docs/telodendria.conf.5 b/docs/telodendria.conf.5 new file mode 100644 index 0000000..df2fdad --- /dev/null +++ b/docs/telodendria.conf.5 @@ -0,0 +1,165 @@ +.Dd $Mdocdate: September 22 2022 $ +.Dt TELODENDRIA.CONF 5 +.Os Telodendria Project +.Sh NAME +.Nm telodendria.conf +.Nd Configuration file for Telodendria +.Sh DESCRIPTION +.Nm +is the configuration file for the Telodendria homeserver, +.Xr telodendria 8 . +Telodendria is designed to be extremely configurable. As such, +it has a fairly extensive configuration file. The configuration +file can be passed to the Telodendria binary with the +.Sy -f +option, and is typically located at +.Pa /etc/telodendria.conf +.sp +.Nm +uses OpenBSD-style syntax, though it is a little more rigid in its +parser. All values must be surrounded by quotes, and each directive +must be ended with a semicolon. +.Sh MACROS +Macros can be defined that will later be expanded in context. +Macro names must start with a letter, digit, or underscore, and may +contain only those characters. Macros are not expanded inside quotes. +.sp +For example: +.D1 macro1 = "value1"; +.D1 directive $macro1; +.Sh GLOBAL OPTIONS +Here are the settings that can be set globally: +.Bl -tag -width Ds +.It Ic listen Ar port +The port to listen on. Telodendria will bind to all interfaces, but it +is recommended to configure your firewall so that it only listens on +localhost, and then configure a reverse proxy such as +.Xr relayd 8 +in front of it, because Telodendria does not implement TLS. Note that +Telodendria doesn't provide multiple ports for the various services it +offers. ALl APIs are made available over the same port, so care should +be taken in +.Xr relayd.conf 5 +to ensure that only the public Matrix API paths are made available over +the internet. +.Ar port +should be a decimal port number. This directive is entirely optional. If +it is omitted, then Telodendria will listen on port 8008 by default. +.It Ic server-name 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 chroot Ar directory +Change the root directory to the specified directory as soon as possible. +Note that all other paths and files specified in +.Nm +must be accessible relative from this directory. This directive only +takes effect if Telodendria is running as root. If it isn't, then a +warning is printed to the log, and no +.Xr chroot 2 +call is made. In that case, Telodendria will still change into the +specified directory, so that the other paths referenced can be made +relative to this one. This directive is required. It is expected that +the homeserver data and logs will be stored in a subdirectory of this one. +.It Ic id Ar uid Ar gid +The effective UNIX user and group to drop to after binding to the socket +and changing the filesystem root. This only works if Telodendria is +running as the root user, and is used as a security mechanism. If 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 +required, even if Telodendria is unable to switch to the given user and +group. It should be used as a sanity check to make sure the permissions are +working properly. +.It Ic data-dir Ar directory +The data directory into which Telodendria will write all user and event +information. Telodendria doesn't use a database like other Matrix homeserver +implementations; it uses a flat-file directory structure, similar to how an +SMTP server uses Maildirs to deliver email. This directive is required. +.Ar directory +should be a path relative to the +.Ic chroot +directory. Don't depend on the +.Ic chroot +option working, because there may be legitimate cases when Telodendria will +not be started as root, thus causing the chroot to fail. +.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 aset 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 file|stdout +The log configuration. Telodendria uses its own logging facility, which can output to +either standard output or a file. A number of child directives can be added to this +directive to customize the log output: +.Bl -tag -width Ds +.It Ic level Ar error|warning|task|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 task +shows tasks, 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 . +.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. +.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. +.El +.Sh FILES +.Bl -tag -width Ds +.It Pa /etc/telodendria.conf +The default +.Xr telodendria 8 +configuration file. +.It Pa /var/telodendria +The recommended chroot directory. +.El +.Sh EXAMPLES +Please consult the default +.Nm +that ships with Telodendria for a complete example. If you installed Telodendria +as a package, then the example should be located at the default location. If you +are building from source, you can find the default config in the +.Pa contrib/ +directory. +.Sh SEE ALSO +.Xr telodendria 8 diff --git a/site/index.html b/site/index.html index 371dfe2..5ebb782 100644 --- a/site/index.html +++ b/site/index.html @@ -112,52 +112,6 @@ Submit code patches to the Telodendria project. -

Table of Contents

-

Download

Telodendria is distributed as source tarballs, in true Unix @@ -227,180 +181,6 @@ for convenience:

  • telodendria.conf(5) - Configuration
  • td(8) - Build script and patch instructions
    • -

    Configure Telodendria

    -

    -Telodendria is designed to be extremely configurable. As such, it has -a fairly extensive configuration file. The configuration file is passed to -the Telodendria binary with the -c option, and is -typically called /etc/telodendria.conf. It uses OpenBSD-style -syntax, and consists of the following options. -

    -

    -There are example configuration files in the contrib folder of -every source tarball, and in the CVS repository. -

    -

    Project Status

    Telodendria is a very ambitious project. There's a lot that needs