From 687b89a83a486fd3ff56b0de06e47052726d7166 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Thu, 20 Apr 2023 01:39:09 +0000 Subject: [PATCH] Add some more user documentation to clarify how configuration works. --- TODO.txt | 4 +- man/man7/telodendria-admin.7 | 4 +- .../telodendria-config.7} | 123 ++++++++++-------- man/man7/telodendria-setup.7 | 75 +++++++++++ 4 files changed, 145 insertions(+), 61 deletions(-) rename man/{man5/telodendria.conf.5 => man7/telodendria-config.7} (71%) create mode 100644 man/man7/telodendria-setup.7 diff --git a/TODO.txt b/TODO.txt index 10f5d17..6075e19 100644 --- a/TODO.txt +++ b/TODO.txt @@ -77,8 +77,8 @@ Milestone: v0.3.0 [ ] HttpRouter [ ] Str [x] telodendria-admin - [ ] telodendria-setup - [ ] telodendria-config + [x] telodendria-setup + [x] telodendria-config [ ] Refactor dev pages so function description and return value are in the same location. diff --git a/man/man7/telodendria-admin.7 b/man/man7/telodendria-admin.7 index 848e103..f38cd81 100644 --- a/man/man7/telodendria-admin.7 +++ b/man/man7/telodendria-admin.7 @@ -1,4 +1,4 @@ -.Dd $Mdocdate: April 19 2023 $ +.Dd $Mdocdate: April 20 2023 $ .Dt TELODENDRIA-ADMIN 7 .Os Telodendria Project .Sh NAME @@ -290,7 +290,7 @@ lfB lfB lfB l l l. Field;Type;Description restart_required;Boolean;T{ -Whether or not the process needs to be restart to finish applying the +Whether or not the process needs to be restarted to finish applying the configuration. If this is true, the restart endpoint may be used. T} .TE diff --git a/man/man5/telodendria.conf.5 b/man/man7/telodendria-config.7 similarity index 71% rename from man/man5/telodendria.conf.5 rename to man/man7/telodendria-config.7 index 0ff604c..af02990 100644 --- a/man/man5/telodendria.conf.5 +++ b/man/man7/telodendria-config.7 @@ -1,44 +1,61 @@ -.Dd $Mdocdate: February 15 2023 $ -.Dt TELODENDRIA.CONF 5 +.Dd $Mdocdate: April 20 2023 $ +.Dt TELODENDRIA-CONFIG 7 .Os Telodendria Project .Sh NAME -.Nm telodendria.conf -.Nd Configuration file for Telodendria. +.Nm telodendria-config +.Nd Telodendria configuration. .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 JSON for its configuration file syntax, which should be -familiar. Very early versions of -.Nm -used a custom OpenBSD-style configuration file, but this was -not as versatile or familiar as JSON. +.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 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. +.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 entirely optional. If -it is omitted, then Telodendria will listen on port 8008 by default. +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 @@ -91,15 +108,6 @@ specified, then the value of .Ic uid is copied. .El -.It Ic dataDir 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. -.Pp -Telodendria will -.Xr chroot 2 -into this directory as soon as possible for security reasons. If the .Ic log directive is configured to write to a file, the log file will be written in the data directory. @@ -122,7 +130,7 @@ 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 +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 @@ -137,8 +145,7 @@ The lot output destination. If set to .Ar file , Telodendria will log to .Pa telodendria.log -inside the -.Ic dataDir . +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 @@ -178,7 +185,7 @@ 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 even that it +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 @@ -190,20 +197,22 @@ minimal memory available. .El .Sh FILES .Bl -tag -width Ds -.It Pa /etc/telodendria.conf -The default -.Xr telodendria 8 -configuration file. +.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 -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 +.Pp +A number of example configuration files are shipped with +Telodendria's source code. They can be found in the .Pa contrib/ -directory. +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 diff --git a/man/man7/telodendria-setup.7 b/man/man7/telodendria-setup.7 new file mode 100644 index 0000000..e49456a --- /dev/null +++ b/man/man7/telodendria-setup.7 @@ -0,0 +1,75 @@ +.Dd $Mdocdate: April 20 2023 $ +.Dt TELODENDRIA-SETUP 7 +.Os Telodendria Project +.Sh NAME +.Nm telodendria-setup +.Nd First-time setup instructions for Telodendria. +.Sh DESCRIPTION +.Pp +While Telodendria strives to be extremely simple to deploy, in most +circumstances a few basic setup steps will be necessary. Telodendria +does not have a traditional configuration file like most daemons. +Instead, its configuration lives in its database; as such, all +configuration happens through the administrator API. This design +decision makes Telodendria extremely flexible, because it is possible +to re-configure Telodendria without having to manually edit files +on the filesystem. It is also why the setup instructions provided +here are in the order they are. Please follow them carefully for the +best results. +.Pp +This page assumes that you have installed Telodendria in the way +prescribed by your operating system. Immediately following installation, +perform these steps, in this order: +.Bl -enum -width Ds +.It +Start Telodendria. Consult your operating system's documentation. If +you are running Telodendria directly from the source code directory, +use +.Xr td 8 . +.It +Assuming Telodendria started properly, it will spin up and initialize +its database directory with a simple\(emand importantly, +safe\(emdefault configuration, and a randomly-generated, single-use +registration token that grants a user all privileges documented in +.Xr telodendria-admin 7. +Consult the log file for this administrator registration token. The +log file is located in the data directory, and is named +.Pa telodendria.log . +.It +Use the registration token to register the administrator account. You +can do this using the client of your choice, or using tools such as +.Xr curl 1 +or +.Xr http 1 . +The administrator account functions just like a normal local account, +except that it has all privileges granted to it, so it can make full +use of the administrator API. +.It +Using the access token for the administrator account, authenticate +with the administrator API and configure Telodendria as described +in +.Xr telodendria-config 7. +See +.Xr telodendria-admin 7 +for the configuration endpoint details. +.El +.Pp +This is the recommended way to set up Telodendria. However, if you +wish to bypass the account creation step, and want to configure +Telodendria by directly writing a configuration file instead of using +the administrator API, you can manually create the configuration file +in the database before starting Telodendria. Simply create +.Pa config.json +following the description in +.Xr telodendria-config 7 , +then start Telodnedria. +.Pp +While this alternative method may seem simpler and more convenient to +some administrators, it is only so in the short-term. Note that this +method is not supported, because it gives no access to the +administrator API whatsoever, unless you manually modify the database +to give a user admin privileges, which is error-prone and bypasses +some of Telodendria's safety mechanisms. +.Sh SEE ALSO +.Xr telodendria-admin 7 , +.Xr telodendria-config 7