forked from lda/telodendria
Write man page for configuration file.
This commit is contained in:
parent
a0dbe31d42
commit
bbf8f26889
6 changed files with 172 additions and 227 deletions
|
@ -7,9 +7,9 @@
|
||||||
Copyright (C) 2022 Jordan Bancino <@jordan:bancino.net>
|
Copyright (C) 2022 Jordan Bancino <@jordan:bancino.net>
|
||||||
|
|
||||||
This is the source code for Telodendria, a Matrix homeserver written
|
This is the source code for Telodendria, a Matrix homeserver written
|
||||||
in C. All of the documentation is available at https://telodendria.io,
|
in C. All of the documentation is available as man pages in the
|
||||||
or in site/index.html.
|
docs/ directory, or online at https://telodendria.io
|
||||||
|
|
||||||
If information is missing from those documents, please feel free to
|
If information is missing from the documentation, please feel free
|
||||||
reach out to #telodendria-general:bancino.net on Matrix.
|
to reach out to #telodendria-general:bancino.net on Matrix.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.Dd September 21, 2022
|
.Dd $Mdocdate: September 22 2022 $
|
||||||
.Dt TD 8
|
.Dt TD 8
|
||||||
.Os Telodendria Project
|
.Os Telodendria Project
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.Dd September 21, 2022
|
.Dd $Mdocdate: September 22 2022 $
|
||||||
.Dt TELODENDRIA 7
|
.Dt TELODENDRIA 7
|
||||||
.Os Telodendria Project
|
.Os Telodendria Project
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.Dd September 21, 2022
|
.Dd $Mdocdate: September 22 2022 $
|
||||||
.Dt TELODENDRIA 8
|
.Dt TELODENDRIA 8
|
||||||
.Os Telodendria Project
|
.Os Telodendria Project
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
|
|
165
docs/telodendria.conf.5
Normal file
165
docs/telodendria.conf.5
Normal 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
220
site/index.html
|
@ -112,52 +112,6 @@ Submit code patches to the <b>Telodendria</b> project.
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
</table>
|
</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>
|
<h2 id="download">Download</h2>
|
||||||
<p>
|
<p>
|
||||||
<b>Telodendria</b> is distributed as source tarballs, in true Unix
|
<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="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>
|
<li><a href="td.8.html">td(8)</a> - Build script and patch instructions</li>
|
||||||
</ul>
|
</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>
|
<h2 id="project-status">Project Status</h2>
|
||||||
<p>
|
<p>
|
||||||
<b>Telodendria</b> is a very ambitious project. There's a lot that needs
|
<b>Telodendria</b> is a very ambitious project. There's a lot that needs
|
||||||
|
|
Loading…
Reference in a new issue