plate/telodendria
1
0
Fork 0
forked from lda/telodendria
Code Pull requests Activity Actions

Write man page for configuration file.

Browse source
This commit is contained in:
Jordan Bancino 2022-09-22 09:47:52 -04:00
parent a0dbe31d42
commit bbf8f26889
6 changed files with 172 additions and 227 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
README.txt
View file

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

2
docs/td.8
View file

@ -1,4 +1,4 @@
.Dd September 21, 2022
.Dd $Mdocdate: September 22 2022 $
.Dt TD 8
.Os Telodendria Project
.Sh NAME

2
docs/telodendria.7
View file

@ -1,4 +1,4 @@
.Dd September 21, 2022
.Dd $Mdocdate: September 22 2022 $
.Dt TELODENDRIA 7
.Os Telodendria Project
.Sh NAME

2
docs/telodendria.8
View file

@ -1,4 +1,4 @@
.Dd September 21, 2022
.Dd $Mdocdate: September 22 2022 $
.Dt TELODENDRIA 8
.Os Telodendria Project
.Sh NAME

165
docs/telodendria.conf.5 Normal file
View file

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

220
site/index.html
View file

@ -112,52 +112,6 @@ Submit code patches to the <b>Telodendria</b> project.
</td>
</tr>
</table>
<h2 id="table-of-contents">Table of Contents</h2>
<ul>
<li>
<a href="#telodendria">Telodendria</a>
<ul>
<li><a href="#table-of-contents">Table of Contents</a></li>
<li><a href="#download">Download</a></li>
<li><a href="#building-the-source">Building The Source</a></li>
</li>
<li><a href="#configure">Configure Telodendria</a></li>
</li>
<li>
<a href="#project-status">Project Status</a>
<ul>
<li><a href="#phase-1">Phase 1: Getting Off The Ground</a></li>
<li><a href="#phase-2">Phase 2: Building A Foundation</a></li>
<li><a href="#phase-3">Phase 3: Welcome To Matrix</a></li>
<li><a href="#phase-4">Phase 4: A Real Homeserver</a></li>
</ul>
</li>
<li><a href="#documentation-status">Documentation Status</a></li>
<li><a href="#rationale">Rationale</a></li>
<li><a href="#project-goals">Project Goals</a></li>
<li><a href="#getting-support">Getting Support</a></li>
<li>
<a href="#contributing">Contributing</a>
<ul>
<li><a href="#reporting-issues">Reporting Issues</a></li>
<li>
<a href="#Developing">Developing</a>
<ul>
<li><a href="#getting-the-code">Getting The Code</a></li>
<li><a href="#code-style">Code Style</a></li>
<li><a href="#the-build-script">The Build Script</a></li>
<li><a href="#submitting-patches">Submitting Patches</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#license">License</a></li>
<li><a href="#contributors">Contributors</a></li>
<li><a href="#change-log">Change Log</a></li>
<li><a href="#resources">Resources</a></li>
</ul>
</li>
</ul>
<h2 id="download">Download</h2>
<p>
<b>Telodendria</b> is distributed as source tarballs, in true Unix
@ -227,180 +181,6 @@ for convenience:
<li><a href="telodendria.conf.5.html">telodendria.conf(5)</a> - Configuration</li>
<li><a href="td.8.html">td(8)</a> - Build script and patch instructions</li>
</ul>
<h2 id="configure">Configure Telodendria</h3>
<p>
<b>Telodendria</b> is designed to be extremely configurable. As such, it has
a fairly extensive configuration file. The configuration file is passed to
the <b>Telodendria</b> binary with the <code>-c</code> option, and is
typically called <code>/etc/telodendria.conf</code>. It uses OpenBSD-style
syntax, and consists of the following options.
</p>
<p>
There are example configuration files in the <code>contrib</code> folder of
every source tarball, and in the CVS repository.
</p>
<ul>
<li>
<code><b>listen</b> [port]</code>
<p>
The port to listen on. <b>Telodendria</b> will bind to all interfaces, but
It is recommended to configure your firewall so that it only listens on
<code>localhost</code>, and then configure a reverse proxy such as
<code>relayd(8)</code> in front of it, because <b>Telodendria</b> does
not implement TLS. Note that <b>Telodendria</b> doesn't provide multiple
ports for the various services it offers. All APIs are made available over
the same port.
</p>
<p>
<code>[port]</code> should be a decimal port number or a service name.
</p>
<p>
The <code>listen</code> directive is entirely optional; if it is omitted,
then <b>Telodendria</b> will listen on <code>localhost</code>, port
<code>8008</code> by default.
</p>
</li>
<li>
<code><b>server-name</b> [name]</code>
<p>
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.
</p>
<p>
<code>[name]</code> should be a DNS name that everyone on the network
can resolve. This directive is required.
</p>
</li>
<li>
<code><b>chroot</b> [directory]</code>
<p>
Change the root to the specified directory as soon as possible. Note that
all other paths and files specified in the configuration file must be
accessible from this directory. This only works if <b>Telodendria</b> is
running as <code>root</code>. If it isn't, then a warning is printed to the
log, and no <code>chroot</code> call is made. In that case, <b>Telodendria</b>
will still change into the specified directory, so that other paths can be
made relative to this one.
</p>
<p>
This directive is required. It is expected that the server data and logs
will live here.
</p>
</li>
<li>
<code><b>id</b> [uid] [gid]</code>
<p>
The effective UNIX user and group to drop to after binding to the socket and
changing the filesystem root. This only works if <b>Telodendria</b> is running as
<code>root</code>, and is used as a security mechanism. If <b>Telodendria</b> is
started as a non-privileged user, then a warning is printed to the log if that
user does not match what's specified here.
</p>
<p>
This directive is required, even if <b>Telodendria</b> is unable to switch to
this user. It can be used as a sanity check to make sure the permissions are
working properly.
</p>
</li>
<li>
<code><b>data-dir</b> [directory]</code>
<p>
The data directory in which <b>Telodendria</b> will write all user and event
information. <b>Telodendria</b> 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.
</p>
<p>
This directive is required. <code>[directory]</code> should be a path relative
to the <code>chroot</code> directory. Don't depend on the <code>chroot</code>
option working, because there are many legitimate cases when <b>Telodendria</b>
will not be started as <code>root</code>, thus causing the chroot to fail.
</p>
</li>
<li>
<code><b>federation</b> [true|false]</code>
<p>
Whether to enable federation with other Matrix homeservers or not. Matrix by
its very nature is a federated protocol, but if you just want 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 <code>true</code>,
however, if you wish to be able to communicate with users on other Matrix
servers.
</p>
<p>
This directive is required, though it may be made optional at some point in
the future.
</p>
</li>
<li>
<code><b>registration</b> [true|false]</code>
<p>
Whether or not to enable new user registration or not. For security and anti-spam
reasons, you can set this to <code>false</code>. If you do, you can still add users
via the administrator API.
</p>
<p>
In an ideal world, everyone would run their own homeserver, so no public
registration would ever be required. But 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
for those that are unable to run their own homeserver, you can set this to <code>true</code>,
which will allow anyone to create an account.
</p>
<p>
<b>Telodendria</b> should be capable of handling a large amount of users without
difficulty or security issues. This directive is required.
</p>
</li>
<li>
<code><b>log</b> [file|stdout]</code>
<p>
The log configuration. <b>Telodendria</b> 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:
</p>
<ul>
<li>
<code><b>level</b> [error|warning|task|message|debug]</code>
<p>
The level of messages to log at. Each level shows all the levels above it. For
example, setting the level to <code>error</code> will show only errors, while
setting the level to <code>warning</code> will show warnings <i>and</i> errors.
<code>task</code> shows tasks, warnings, and errors, and so on.
</p>
</li>
<li>
<code><b>timestampFormat</b> [format|none|default]</code>
<p>
If you want to custom ize the timestamp format shown in the log, or disable
the timestamp functionality altogether, you do so via this option. Acceptable
values are <code>none</code>, <code>default</code>, or a formatter string as
described by your system's <code>strftime()</code> manual.
</li>
<li>
<code><b>color</b> [true|false]</code>
<p>
Whether or not to enable colored output on TTYs. Note that ANSI color sequences
will <i>not</i> 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.
</p>
</li>
</ul>
</li>
<li>
<code><b>threads</b> [count]</code>
<p>
How many worker threads to sping 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 <b>Telodendria</b>, so you may just have to play around with different
values here to see which gives the best performance.
</p>
</li>
</ul>
<h2 id="project-status">Project Status</h2>
<p>
<b>Telodendria</b> is a very ambitious project. There's a lot that needs