forked from Telodendria/Telodendria
Remove old docs
This commit is contained in:
parent
2d6b80a26e
commit
c0ecff11cb
7 changed files with 0 additions and 1173 deletions
114
docs/Array.3
114
docs/Array.3
|
@ -1,114 +0,0 @@
|
||||||
.Dd $Mdocdate: September 27 2022 $
|
|
||||||
.Dt ARRAY 3
|
|
||||||
.Os Telodendria Project
|
|
||||||
.Sh NAME
|
|
||||||
.Nm Array
|
|
||||||
.Nd A simple dynamic array data structure.
|
|
||||||
.Sh SYNOPSIS
|
|
||||||
.In Array.h
|
|
||||||
.Ft Array *
|
|
||||||
.Fn ArrayCreate "void"
|
|
||||||
.Ft void
|
|
||||||
.Fn ArrayFree "Array *"
|
|
||||||
.Ft int
|
|
||||||
.Fn ArrayTrim "Array *"
|
|
||||||
.Ft size_t
|
|
||||||
.Fn ArraySize "Array *"
|
|
||||||
.Ft void *
|
|
||||||
.Fn ArrayGet "Array *" "size_t"
|
|
||||||
.Ft int
|
|
||||||
.Fn ArrayInsert "Array *" "void *" "size_t"
|
|
||||||
.Ft int
|
|
||||||
.Fn ArrayAdd "Array *" "void *"
|
|
||||||
.Ft void *
|
|
||||||
.Fn ArrayDelete "Array *" "size_t"
|
|
||||||
.Ft void
|
|
||||||
.Fn ArraySort "Array *" "int (*) (void *, void *)"
|
|
||||||
.Sh DESCRIPTION
|
|
||||||
These functions implement a simple array data structure that
|
|
||||||
is automatically resized as necessary when new values are added.
|
|
||||||
This implementation does not actually store the values of the
|
|
||||||
items in it; it only stores pointers to the data. As such, you will
|
|
||||||
still have to manually maintain all your data. The advantage of this
|
|
||||||
is that these functions don't have to copy data, and thus don't care
|
|
||||||
how big the data is. Furthermore, arbitrary data can be stored in the
|
|
||||||
array.
|
|
||||||
.Pp
|
|
||||||
This array implementation is optimized for storage space and appending.
|
|
||||||
Deletions are expensive in that all the items of the list above a deletion
|
|
||||||
are moved down to fill the hole where the deletion occurred. Insertions are
|
|
||||||
also expensive in that all the elements above the given index must be shifted
|
|
||||||
up to make room for the new element.
|
|
||||||
.Pp
|
|
||||||
Due to these design choices, this array implementation is best suited to
|
|
||||||
linear writing, and then linear or random reading.
|
|
||||||
.Pp
|
|
||||||
These functions operate on an array structure which is opaque to the
|
|
||||||
caller.
|
|
||||||
.Pp
|
|
||||||
.Fn ArrayCreate
|
|
||||||
and
|
|
||||||
.Fn ArrayFree
|
|
||||||
allocate and deallocate an array, respectively.
|
|
||||||
Note that
|
|
||||||
.Fn ArrayFree
|
|
||||||
does not free any of the values stored in the array; it is the caller's
|
|
||||||
job to manage the memory for each item. Typically, the caller would
|
|
||||||
iterate over all the items in the array and free them before freeing
|
|
||||||
the array.
|
|
||||||
.Fn ArrayTrim
|
|
||||||
reduces the amount of unused memory by calling
|
|
||||||
.Xr realloc 3
|
|
||||||
on the internal structure to perfectly fit the elements in the array. It
|
|
||||||
is intended to be used by functions that return relatively read-only arrays
|
|
||||||
that will be long-lived.
|
|
||||||
.Pp
|
|
||||||
.Fn ArrayInsert
|
|
||||||
and
|
|
||||||
.Fn ArrayDelete
|
|
||||||
are the main functions used to modify the array.
|
|
||||||
.Fn ArrayAdd
|
|
||||||
is a convenience method that simply appends a value to the end of the
|
|
||||||
array. It uses
|
|
||||||
.Fn ArrayInsert .
|
|
||||||
The array can also be sorted by using
|
|
||||||
.Fn ArraySort ,
|
|
||||||
which takes a pointer to a function that compares elements. The function
|
|
||||||
should take two
|
|
||||||
.Dv void
|
|
||||||
pointers as parameters, and return an integer. The return value indicates
|
|
||||||
to the algorithm how the elements relate to each other. A return value of
|
|
||||||
0 indicates the elements are identical. A return value greater than 0
|
|
||||||
indicates that the first item is "bigger" than the second item and should
|
|
||||||
thus appear after it in the array, and a value less than zero indicates
|
|
||||||
the opposite: the second element should appear after the first in the array.
|
|
||||||
.Pp
|
|
||||||
.Fn ArrayGet
|
|
||||||
is used to get the element at the specified index.
|
|
||||||
.Sh RETURN VALUES
|
|
||||||
.Fn ArrayCreate
|
|
||||||
returns a pointer on the heap to a newly allocated array structure, or
|
|
||||||
.Dv NULL
|
|
||||||
if the allocation fails.
|
|
||||||
.Pp
|
|
||||||
.Fn ArrayGet
|
|
||||||
and
|
|
||||||
.Fn ArrayDelete
|
|
||||||
return pointers to values that were put into the array, or
|
|
||||||
.Dv NULL
|
|
||||||
if the provided array is
|
|
||||||
.Dv NULL
|
|
||||||
or the provided index was out of bounds.
|
|
||||||
.Fn ArrayDelete
|
|
||||||
returns the element at the specified index after removing it so that
|
|
||||||
it can be properly handled by the caller.
|
|
||||||
.Pp
|
|
||||||
.Fn ArrayTrim ,
|
|
||||||
.Fn ArrayInsert ,
|
|
||||||
and
|
|
||||||
.Fn ArrayAdd
|
|
||||||
return a boolean value indicating their status. They return a value of zero
|
|
||||||
on failure, and a non-zero value on success.
|
|
||||||
.Sh SEE ALSO
|
|
||||||
.Xr HashMap 3 ,
|
|
||||||
.Xr Queue 3
|
|
|
@ -1,81 +0,0 @@
|
||||||
.Dd $Mdocdate: September 27 2022 $
|
|
||||||
.Dt BASE64 3
|
|
||||||
.Os Telodendria Project
|
|
||||||
.Sh NAME
|
|
||||||
.Nm Base64
|
|
||||||
.Nd A simple base64 encoder/decoder with "unpadded base64" support.
|
|
||||||
.Sh SYNOPSIS
|
|
||||||
.In Base64.h
|
|
||||||
.Ft size_t
|
|
||||||
.Fn Base64EncodedSize "size_t"
|
|
||||||
.Ft size_t
|
|
||||||
.Fn Base64DecodedSize "const char *" "size_t"
|
|
||||||
.Ft char *
|
|
||||||
.Fn Base64Encode "const char *" "size_t"
|
|
||||||
.Ft char *
|
|
||||||
.Fn Base64Decode "const char *" "size_t"
|
|
||||||
.Ft void
|
|
||||||
.Fn Base64Unpad "char *" "size_t"
|
|
||||||
.Ft int
|
|
||||||
.Fn Base64Pad "char **" "size_t"
|
|
||||||
.Sh DESCRIPTION
|
|
||||||
This is an efficient yet simple base64 encoding and decoding
|
|
||||||
library that supports regular base64, as well as the Matrix
|
|
||||||
specification's extension to base64, called "unpadded base64."
|
|
||||||
.Nm provides the ability to convert between the two, instead of
|
|
||||||
just implementing "unpadded base64."
|
|
||||||
.Pp
|
|
||||||
.Fn Base64EncodedSize
|
|
||||||
and
|
|
||||||
.Fn Base64DecodedSize
|
|
||||||
compute the amount of characters needed to store an encoded or
|
|
||||||
decoded message, respectively. Both functions take the size of
|
|
||||||
the message being encoded or decoded, but
|
|
||||||
.Fn Base64DecodedSize
|
|
||||||
also takes a pointer to an encoded string, because a few bytes of
|
|
||||||
the string need to be read in order to compute the size.
|
|
||||||
.Pp
|
|
||||||
.Fn Base64Encode
|
|
||||||
and
|
|
||||||
.Fn Base64Decode
|
|
||||||
do the actual work of encoding and decoding base64 data. They both
|
|
||||||
take a string and its length.
|
|
||||||
.Pp
|
|
||||||
.Fn Base64Unpad
|
|
||||||
and
|
|
||||||
.Fn Base64Pad
|
|
||||||
are used to implement Matrix unpadded base64.
|
|
||||||
.Fn Base64Unpad
|
|
||||||
takes a valid base64 string and strips off the trailing equal signs,
|
|
||||||
as per the specification.
|
|
||||||
.Fn Base64Pad
|
|
||||||
does the opposite; it takes an unpadded base64 input string, and pads
|
|
||||||
it with equal signs as necessary, so that it can be properly decoded
|
|
||||||
with
|
|
||||||
.Fn Base64Decode
|
|
||||||
if necessary. However, the Matrix specification envisons unpadded base64
|
|
||||||
as opaque; that is, once it's encoded, it never needs to be decoded.
|
|
||||||
In practice, a homeserver might need to decode an unpadded base64 string.
|
|
||||||
.Sh RETURN VALUES
|
|
||||||
.Fn Base64EncodedSize
|
|
||||||
and
|
|
||||||
.Fn Base64DecodedSize
|
|
||||||
simply return unsigned integers representing a number of bytes generated
|
|
||||||
from a simple computation.
|
|
||||||
.Pp
|
|
||||||
.Fn Base64Encode
|
|
||||||
and
|
|
||||||
.Fn Base64Decode
|
|
||||||
return pointers to new strings, allocated on the heap, or
|
|
||||||
.Dv NULL
|
|
||||||
if a heap allocation fails. These pointers must be
|
|
||||||
.Xr free 3 -ed
|
|
||||||
at some point when they are no longer needed.
|
|
||||||
.Pp
|
|
||||||
.Fn Base64Unpad
|
|
||||||
modifies the passed string in-place. It thus has no return value, because
|
|
||||||
it cannot fail. If the passed pointer is invalid, the behavior is undefined.
|
|
||||||
.Fn Base64Pad
|
|
||||||
returns a boolean value indicating whether the pad operation was successful.
|
|
||||||
In practice, this function will only fail if a bigger string is necessary, but
|
|
||||||
could not be automatically allocated on the heap.
|
|
|
@ -1,252 +0,0 @@
|
||||||
.Dd $Mdocdate: September 23 2022 $
|
|
||||||
.Dt CONTRIBUTING 7
|
|
||||||
.Os Telodendria Project
|
|
||||||
.Sh NAME
|
|
||||||
.Nm contributing
|
|
||||||
.Nd Guide to contributing to Telodendria
|
|
||||||
.Sh DESCRIPTION
|
|
||||||
Telodendria is an open source project. As such, it welcomes
|
|
||||||
contributions. There are many ways you can contribute, and any
|
|
||||||
way you can is greatly appreciated. This page contains some of
|
|
||||||
the ways you can help out.
|
|
||||||
.Sh REPORTING ISSUES
|
|
||||||
Please reach out to the Matrix rooms mentioned at the top of
|
|
||||||
.Xr telodendria 7 .
|
|
||||||
All issue tracking takes place in those rooms. Start by reaching
|
|
||||||
out to the general room, and if you think there's a legitimate
|
|
||||||
problem with Telodendria itself, then stick the issue in the
|
|
||||||
issues room, where it can be discussed further. Issues usually
|
|
||||||
remain in the Matrix rooms, but severe enough issues may be put
|
|
||||||
in a
|
|
||||||
.Pa TODO
|
|
||||||
file in the
|
|
||||||
.Xr cvs 1
|
|
||||||
repository so that they don't get lost.
|
|
||||||
.Sh DEVELOPING
|
|
||||||
The primary language used to write Telodendria code is ANSI C.
|
|
||||||
Other languages you'll find in the Telodendria repository include
|
|
||||||
shell scripts,
|
|
||||||
.Xr mdoc 7 ,
|
|
||||||
and a little bit of HTML and CSS. If you have any experience with
|
|
||||||
any of these languages, your contributions are valuable! Please follow
|
|
||||||
the guidelines on this page to ensure the contribution workflow goes
|
|
||||||
as smoothly as possible.
|
|
||||||
.Ss Getting the Code
|
|
||||||
If you'd like to hack on Telodendria, you'll need the following tools
|
|
||||||
in addition to a C compiler and POSIX shell:
|
|
||||||
.Bl -tag
|
|
||||||
.It Xr cvs 1
|
|
||||||
For checking out and updating your local copy of the source code.
|
|
||||||
.It Xr indent 1
|
|
||||||
For formatting your code before generating patches.
|
|
||||||
.It Xr patch 1
|
|
||||||
For applying patches to your local copy of the source code.
|
|
||||||
.El
|
|
||||||
.sp
|
|
||||||
All of these tools are built into OpenBSD. While you don't have to
|
|
||||||
use OpenBSD to develop Telodendria, it may make the process a bit
|
|
||||||
easier. In fact, these tools where chosen precisely because they
|
|
||||||
were built into my operating system of choice.
|
|
||||||
.sp
|
|
||||||
You can download an official release tarball from the website if
|
|
||||||
you would really like, but the preferred way to get the source
|
|
||||||
code for development is to check it out from CVS. This makes generating
|
|
||||||
patches a lot easier.
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
$ cvs -d anoncvs@bancino.net:/cvs checkout -P Telodendria
|
|
||||||
$ cd Telodendria
|
|
||||||
.Ed
|
|
||||||
.sp
|
|
||||||
If you already checked out the code previously, make sure you update
|
|
||||||
your local copy before you start developing:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
$ cvs -q update -dP
|
|
||||||
.Ed
|
|
||||||
.sp
|
|
||||||
You should now have the latest source code. Follow the
|
|
||||||
.Sx CODE STYLE
|
|
||||||
as you make your changes. If the
|
|
||||||
.Xr cvs 1
|
|
||||||
command fails with a "Connection refused" error message, try setting
|
|
||||||
the
|
|
||||||
.Ev CVS_RSH
|
|
||||||
environment variable to "ssh", like this:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
$ export CVS_RSH=ssh
|
|
||||||
.Ed
|
|
||||||
.sp
|
|
||||||
Then run the checkout command again. Some versions of CVS on some
|
|
||||||
systems don't use SSH to checkout by default, so if yours doesn't,
|
|
||||||
you might want to put the above line into your shell init script.
|
|
||||||
.Ss Submitting Patches
|
|
||||||
Telodendria aims at remaining as minimal as possible. This doesn't just
|
|
||||||
mean minimal code, it also means a minimal development process, which is
|
|
||||||
why Telodendria doesn't use GitHub, GitLab, or even SourceHut. Instead,
|
|
||||||
the contribution workflow operates on submitting patch files to a public
|
|
||||||
Matrix room, sort of like the OpenBSD project operates on patch files
|
|
||||||
sent to a public mailing list.
|
|
||||||
.sp
|
|
||||||
If you're not used to manually creating and submitting patches instead of
|
|
||||||
just opening a "pull request," you should be pleased to hear that submitting
|
|
||||||
patches is fairly easy to do if you've got the CVS sources checked out. In
|
|
||||||
fact, I find it easier than having to make a GitHub account, forking a
|
|
||||||
project's repository, and then making a pull request for it. Once you have
|
|
||||||
made your changes in your local copy of the code, and you've configured your
|
|
||||||
environment properly as noted in the manual for
|
|
||||||
.Xr td 8 ,
|
|
||||||
just run the patch recipe:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
$ td patch
|
|
||||||
.Ed
|
|
||||||
.sp
|
|
||||||
This will automatically generate a patch file for all your changes, and then
|
|
||||||
open it in your preferred editor. You can also generate a patch file for only
|
|
||||||
certain files and directories. To do that, set
|
|
||||||
.Ev PATCHSET ,
|
|
||||||
like this:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
# Only write a patch for README.txt and the files in docs/
|
|
||||||
$ PATCHSET="README.txt docs/" td patch
|
|
||||||
.Ed
|
|
||||||
.sp
|
|
||||||
As you'll notice, the top of the patch file should have some email-style
|
|
||||||
headers that look like this:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
From: Jordan Bancino <@jordan:bancino.net>
|
|
||||||
Date: Fri Jul 29 03:21:21 PM EDT 2022
|
|
||||||
Subject: Document Patch Procedure
|
|
||||||
.Ed
|
|
||||||
.sp
|
|
||||||
As much information should be filled out for you, such as the date. An
|
|
||||||
attempt to fill out the From header was also made by
|
|
||||||
.Xr td 8 ,
|
|
||||||
but the information there can be modifed as necessary. Consult the manual
|
|
||||||
for
|
|
||||||
.Xr td 8
|
|
||||||
for more details. The Subject should very briefly describe what the patch
|
|
||||||
is about.
|
|
||||||
.sp
|
|
||||||
You'll also notice these lines in the patch:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
[ ] I have read the Telodendria Project development certificate of
|
|
||||||
origin, and certify that I have permission to submit this patch
|
|
||||||
under the conditions specified in it.
|
|
||||||
.Ed
|
|
||||||
.sp
|
|
||||||
This is a checkbox that tells me whether or not you actually have the
|
|
||||||
rights to submit your patch, and that once you submit your patch, your
|
|
||||||
code is bound by the Telodendria project license, which you can and
|
|
||||||
should view in
|
|
||||||
.Xr telodendria 7 .
|
|
||||||
The full text of the developer certificate of origin is as follows:
|
|
||||||
.Bl -enum
|
|
||||||
.It
|
|
||||||
The contribution was created in whole or in part by me, and I have the right
|
|
||||||
to submit it under the open source licenses of the Telodendria project; or
|
|
||||||
.It
|
|
||||||
The contribution is based upon a previous work that, to the best of my knowledge,
|
|
||||||
is covered under an appropriate open source license and I have the right under
|
|
||||||
that license to submit that work with modifications, whether created in whole
|
|
||||||
or in part by me, under the Telodendria project license; or
|
|
||||||
.It
|
|
||||||
The contribution whas provided directly to me by some other person who certified
|
|
||||||
(1), (2), or (3), and I have not modifed it.
|
|
||||||
.It
|
|
||||||
I understand and agree that this project and the contribution are made public
|
|
||||||
and that a record of the contribution\(emincluding all personal information
|
|
||||||
I submit with it\(emis maintained indefinitely and may be redistributed
|
|
||||||
consistent with this project or the open source licenses involved.
|
|
||||||
.El
|
|
||||||
.sp
|
|
||||||
If you agree to the above, fill in the square brackets with an 'x', and then after
|
|
||||||
the headers, but before the checkbox, write a more thorough description of the
|
|
||||||
patch and why it was created. Then, send the resulting patch file to the public
|
|
||||||
Matrix room, as noted in
|
|
||||||
.Xr telodendria 7 ,
|
|
||||||
so it can be discussed and reviewed by the community.
|
|
||||||
.sp
|
|
||||||
Try to keep your patches on topic\(emmake one patch file per feature or bug fix
|
|
||||||
being implemented. It is okay if your patches depend on previous patches, just
|
|
||||||
indicate that in the patch description. Note that it may take a while for
|
|
||||||
patches to be committed, and some patches may not be comitted at all. In either
|
|
||||||
case, all sent patches are queued from the Matrix room into the public patch
|
|
||||||
directory, so they can be referenced easier in the future. If you want to
|
|
||||||
reference a submitted patch in a Matrix message, email, or other digital medium,
|
|
||||||
it might be a good idea to link to it in the public patch directory.
|
|
||||||
.sp
|
|
||||||
The public patch directory works as follows: when you send your patch to the
|
|
||||||
Matrix room, it is downloaded by Telodendria Bot and placed in the
|
|
||||||
.Pa ingress/
|
|
||||||
directory, named as the message ID. Then, it is assigned a patch ID and
|
|
||||||
copied to the
|
|
||||||
.Pa p/
|
|
||||||
directory as just "%d.patch", where "%d" is obviously the patch ID. This is
|
|
||||||
a permanent link that will always reference your patch. Then, your patch will
|
|
||||||
be symlinked into the
|
|
||||||
.Pa queue/
|
|
||||||
directory. I have a script that automatically ingresses patches and queues them
|
|
||||||
for me, and I use this to review patches. If your patch is accepted, the queue
|
|
||||||
symlink will be moved to
|
|
||||||
.Pa accepted/
|
|
||||||
and the submitted patch will be committed to the official CVS repository.
|
|
||||||
If your patch is rejected for some reason, its symlink will be moved to the
|
|
||||||
.Pa rejected/
|
|
||||||
directory. Regardless of the state of your patch, it will always remain
|
|
||||||
permalinked in the
|
|
||||||
.Pa p/
|
|
||||||
directory, and when it is accepted or rejected, Telodendria Bot will send a
|
|
||||||
message to the Matrix room.
|
|
||||||
.sp
|
|
||||||
You're always welcome to inquire about rejected patches, and request that they
|
|
||||||
be reviewed again, or you can use them as a starting point for future patches.
|
|
||||||
.sp
|
|
||||||
The public patch directory is located at
|
|
||||||
.Lk https://telodendria.io/patches/
|
|
||||||
.Sh CODE STYLE
|
|
||||||
In general, these are the conventions used by the code base. This guide
|
|
||||||
may be slightly outdated or subject to change, but it should be a good
|
|
||||||
start. The source code itself is always the absolute source of truth, so
|
|
||||||
as long as you make your code look like the code surrounding it, you should
|
|
||||||
be fine.
|
|
||||||
.Bl -bullet
|
|
||||||
.It
|
|
||||||
All function, enumeration, structure, and header names are CamelCase. This
|
|
||||||
is preferred to snake_case because it is more compact.
|
|
||||||
.It
|
|
||||||
All variable names are lowerCamelCase. This is preferred to snake_case
|
|
||||||
because it is more compact.
|
|
||||||
.It
|
|
||||||
enumerations and structures are always typedef-ed to their same name. The
|
|
||||||
typedef should occur in the public API header, and the actual declaration
|
|
||||||
should live in the implementation file.
|
|
||||||
.It
|
|
||||||
A feature of the code base lives in a single C source file that has a
|
|
||||||
matching header. The header file should only export public symbols;
|
|
||||||
everything else in the C source should be static.
|
|
||||||
.It
|
|
||||||
Except where absolutely necessary, global variables are forbidden to
|
|
||||||
prevent problems with threads and whatnot. Every variable a function
|
|
||||||
needs should be passed to it either through a structure, or as a
|
|
||||||
separate argument.
|
|
||||||
.It
|
|
||||||
Anywhere curly braces are optional, there still must be curly braces. This
|
|
||||||
makes it easier to add on to the code later, and just makes things a bit
|
|
||||||
less ambiguous.
|
|
||||||
.El
|
|
||||||
.sp
|
|
||||||
As far as actually formatting the code goes, such as where to put brackets,
|
|
||||||
and whether or not to use tabs or spaces, use
|
|
||||||
.Xr indent 1
|
|
||||||
to take care of all of that. The root of the CVS repository has a
|
|
||||||
.Pa .indent.pro
|
|
||||||
that should automatically be loaded by
|
|
||||||
.Xr indent 1
|
|
||||||
to set the correct rules. If you don't have a working
|
|
||||||
.Xr indent 1 ,
|
|
||||||
then just indicate in your patch that I should run my
|
|
||||||
.Xr indent 1
|
|
||||||
on the code after applying it. Although in reality, I'll likely
|
|
||||||
run my own
|
|
||||||
.Xr indent 1
|
|
||||||
on the code anyway, just to make sure the spacing is consistent, if nothing
|
|
||||||
else.
|
|
238
docs/td.8
238
docs/td.8
|
@ -1,238 +0,0 @@
|
||||||
.Dd $Mdocdate: September 23 2022 $
|
|
||||||
.Dt TD 8
|
|
||||||
.Os Telodendria Project
|
|
||||||
.Sh NAME
|
|
||||||
.Nm td
|
|
||||||
.Nd Telodendria build script
|
|
||||||
.Sh SYNOPSIS
|
|
||||||
.Nm
|
|
||||||
.Op recipe
|
|
||||||
.Sh DESCRIPTION
|
|
||||||
Telodendria uses a custom build script called
|
|
||||||
.Nm .
|
|
||||||
The
|
|
||||||
.Nm
|
|
||||||
script is not only a build script, however. It does all kinds of
|
|
||||||
cool things like format the source code, and generate patch files.
|
|
||||||
.Nm
|
|
||||||
is the only supported way to develop Telodendria.
|
|
||||||
.sp
|
|
||||||
I opted to write a custom build script instead of just writing a
|
|
||||||
.Pa Makefile
|
|
||||||
because I felt that there is really no way to make a truly portable
|
|
||||||
.Pa Makefile
|
|
||||||
that could do everything I wanted, with the flexibility I wanted. I
|
|
||||||
was doing a lot of research on the differences between the GNU and BSD
|
|
||||||
versions, and I felt it just wasn't worth trying to reconsile the two
|
|
||||||
when I could write a small and relatively robust POSIX shell script that
|
|
||||||
would run on both GNU and BSD systems without any problems. I also
|
|
||||||
think that shell scripts are a lot easier to read than complex
|
|
||||||
.Pa Makefiles.
|
|
||||||
They're easier to follow because they're not so cryptic.
|
|
||||||
.sp
|
|
||||||
The
|
|
||||||
.Nm
|
|
||||||
script is fairly intuitive. It operates somewhat like
|
|
||||||
.Xr make 1
|
|
||||||
in that it has recipes that you specify on the command line. To start
|
|
||||||
using it, just run the following command in the Telodendria source
|
|
||||||
directory:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
$ . tools/env.sh
|
|
||||||
.Ed
|
|
||||||
.sp
|
|
||||||
.Sy Note:
|
|
||||||
You will have to run the above command every time you start a new
|
|
||||||
terminal session, as nothing is persisted to your system. I believe in
|
|
||||||
non-invasive, fully self-contained tooling, so it is up to you to hook the
|
|
||||||
Telodendria tools into your environment as you see fit if you want them to
|
|
||||||
persist.
|
|
||||||
.sp
|
|
||||||
If you're going to be submitting patches, you should also configure a
|
|
||||||
.Pa .env
|
|
||||||
file in the project directory root, which
|
|
||||||
.Nm
|
|
||||||
will include automatically for you. See
|
|
||||||
.Em FILES
|
|
||||||
and
|
|
||||||
.Em ENVIRONMENT .
|
|
||||||
.sp
|
|
||||||
Telodendria is designed to be light enough that it can be built from source
|
|
||||||
on just about any operating system. It only requires an ANSI C compiler and a
|
|
||||||
standard POSIX environment. To build the Telodendria binary, run
|
|
||||||
.Nm
|
|
||||||
with no arguments, or with the
|
|
||||||
.Pa build
|
|
||||||
recipe. This will produce
|
|
||||||
.Pa build/telodendria ,
|
|
||||||
which you can then install to your system and run as a daemon.
|
|
||||||
.sp
|
|
||||||
A complete list of recipes is below. Note that you can run multiple recipes
|
|
||||||
with a single invocation of
|
|
||||||
.Nm ,
|
|
||||||
but recipes are run unconditionally; that is, even if a recipe fails, all the
|
|
||||||
following recipes are still executed.
|
|
||||||
.Bl -tag
|
|
||||||
.It build
|
|
||||||
Build the source code and generate the output binary. This is the default recipe,
|
|
||||||
which means it runs if no other recipes are specified. This recipe is incremental;
|
|
||||||
it only rebuilds sources that have been modifed since the last build, making
|
|
||||||
subsequent builds faster.
|
|
||||||
.It run
|
|
||||||
Run the build binary with the development configuration in the
|
|
||||||
.Pa contrib/
|
|
||||||
directory. This recipe is used for quick testing during development. It is
|
|
||||||
.Sy not
|
|
||||||
the recommended way to run Telodendria in a production environment; it should only
|
|
||||||
be used for development.
|
|
||||||
.It clean
|
|
||||||
Remove the
|
|
||||||
.Pa build/
|
|
||||||
directory and any ephemeral files in the source tree, such as
|
|
||||||
.Pa .orig
|
|
||||||
files. The build recipe does not place anything outside of
|
|
||||||
.Pa build/ ,
|
|
||||||
so you can usually just delete that directory and get the same effect.
|
|
||||||
.It format
|
|
||||||
Make sure the source code copyright headers are up to date, and format the code
|
|
||||||
using the system's
|
|
||||||
.Xr indent 1 .
|
|
||||||
This should be run before generating patch files, to ensure that the code follows
|
|
||||||
the project conventions. Note that the provided
|
|
||||||
.Pa .indent.pro
|
|
||||||
assumes an OpenBSD indent, which may cause the GNU implementation to choke. In
|
|
||||||
that case, don't send patch files with totally different formatting; just submit
|
|
||||||
the patch as-is and they will get formatted before committing.
|
|
||||||
.It test
|
|
||||||
Run all of the unit tests and report the results. It is highly recommended to
|
|
||||||
ensure that all the tests pass before submitting a patch, because patches that
|
|
||||||
break the tests are likely to be rejected.
|
|
||||||
.It site
|
|
||||||
Deploy the Telodendria website by generating HTML files for the documentation,
|
|
||||||
and copying them along with the front page to the specified web root. This is
|
|
||||||
used to deploy the official website, but it could be used to deploy a local
|
|
||||||
development site as necessary. See
|
|
||||||
.Em ENVIRONMENT .
|
|
||||||
.It release
|
|
||||||
Generate a release tarball, checksum and sign it, and push it to the web root.
|
|
||||||
See the relevant environment variables below.
|
|
||||||
.It patch
|
|
||||||
Generate a formatted patch file. The Telodendria project isn't super picky about
|
|
||||||
how patches look as long as they apply cleanly, but this recipe generates patches
|
|
||||||
in the format we like them, and is therefore recommended. It makes patches easy
|
|
||||||
to read. This recipe will use your configured editor to open your formatted patch
|
|
||||||
so you can review and edit it as necessary before sending it off.
|
|
||||||
.It diff
|
|
||||||
Generate a temporary preview patch that is opened in the system pager. This can
|
|
||||||
be used for quickly quickly previewing your changes and the patch file you'll
|
|
||||||
be creating.
|
|
||||||
.El
|
|
||||||
.sp
|
|
||||||
.Sh ENVIRONMENT
|
|
||||||
Any of the following environment variables are used in the build recipes.
|
|
||||||
They can all be specified in your shell when invoking
|
|
||||||
.Nm ,
|
|
||||||
or they can be placed in a
|
|
||||||
.Pa .env
|
|
||||||
file. For most of these variables, if you would like to append or prepend
|
|
||||||
to the default values, do so in the
|
|
||||||
.Pa .env
|
|
||||||
file, which is sourced after the defaults are set, allowing you to reference
|
|
||||||
the default values in your new value.
|
|
||||||
.Bl -tag
|
|
||||||
.It Ev CC
|
|
||||||
The C compiler to use. This defaults to
|
|
||||||
.Pa cc,
|
|
||||||
which is usually a symlink to your system's preferred compiler. If for some
|
|
||||||
reason you want to use a diferent compiler, do so with this environment
|
|
||||||
variable.
|
|
||||||
.It Ev CFLAGS
|
|
||||||
The compiler flags used to generate object files.
|
|
||||||
.Nm
|
|
||||||
comes with reasonable defaults that shouldn't need to be changed in most
|
|
||||||
scenarios, but if you do need to change the compiler flags, you can do
|
|
||||||
so with this environment variable.
|
|
||||||
.It Ev LDFLAGS
|
|
||||||
The compiler flags used to link the object files to create an output
|
|
||||||
binary.
|
|
||||||
.Nm
|
|
||||||
comes with reasonable defaults that shouldn't need to be changed in most
|
|
||||||
scenarios, but if you need to change the linker flags, you do so with this
|
|
||||||
environment variable.
|
|
||||||
.It Ev PROG
|
|
||||||
The name of the output binary. This defaults to
|
|
||||||
.Pa build/telodendria.
|
|
||||||
.It Ev DEFINES
|
|
||||||
Global preprocessor definitions to append to
|
|
||||||
.Ev CFLAGS.
|
|
||||||
This is just kept separate to keep things organized.
|
|
||||||
.It Ev INCLUDES
|
|
||||||
Header directories to make available. This is appended to
|
|
||||||
.Ev CFLAGS,
|
|
||||||
it is just kept separate to keep things organized.
|
|
||||||
.It Ev DEBUG
|
|
||||||
If set to "1", append some debug flags to
|
|
||||||
.Ev CFLAGS
|
|
||||||
and whipe out any
|
|
||||||
.Ev LDFLAGS
|
|
||||||
that awould cause the output binary to be optimized in any way. This also
|
|
||||||
depends "-debug" to
|
|
||||||
.Ev PROG .
|
|
||||||
.It Ev TELODENDRIA_VERSION
|
|
||||||
This variable does make its way into the output binary, but it is primarily
|
|
||||||
used for generating and publishing releases. This variable affects the
|
|
||||||
.Sy release
|
|
||||||
recipe.
|
|
||||||
.It Ev TELODENDRIA_PUB
|
|
||||||
The web root where the Telodendria website lives. This is where the site
|
|
||||||
is pushed to, and where generated releases go.
|
|
||||||
.It Ev PATCHSET
|
|
||||||
This variable restricts the files that
|
|
||||||
.Nm
|
|
||||||
operates on when generating patches or diffs. If you only want to generate
|
|
||||||
a diff or patch for a certain file, directory, or collection of files and
|
|
||||||
directories, set this variable to those files and directories, separated
|
|
||||||
by a space. You can mix files and directories as necessary.
|
|
||||||
.It Ev MXID
|
|
||||||
Your Matrix ID in standard format. This is used when generating patches,
|
|
||||||
so that you can be assigned credit for your patches, as well as be contacted
|
|
||||||
about your patches.
|
|
||||||
.Nm
|
|
||||||
will automatically deduce this from your system, but it will most
|
|
||||||
likely get it wrong. Please make sure you are reachable at this ID.
|
|
||||||
.It Ev DISPLAY_NAME
|
|
||||||
The display name you want to appear on your patches. This should probably
|
|
||||||
match your Matrix display name, although it doesn't necessarily have to.
|
|
||||||
.Nm
|
|
||||||
will deduce this from your system, and if you set it up properly, you may
|
|
||||||
not even have to set this variable. If
|
|
||||||
.Nm
|
|
||||||
gets it wrong, this allows you to override your display name.
|
|
||||||
.It Ev EDITOR
|
|
||||||
Your preferred editor for writing patch file descriptions. This can be a
|
|
||||||
GUI or terminal editor. If unset, this defaults to the system's
|
|
||||||
.Xr vi 1
|
|
||||||
editor.
|
|
||||||
.It Ev PAGER
|
|
||||||
Your preferred pager for previewing patches. If left unset, this defaults
|
|
||||||
to
|
|
||||||
.Xr less 1 .
|
|
||||||
.Sh FILES
|
|
||||||
.Bl -tag
|
|
||||||
.It Pa .env
|
|
||||||
An environment file that contains lines in the form of
|
|
||||||
.Pa VARIABLE=value
|
|
||||||
with environment variables to set in the
|
|
||||||
.Nm
|
|
||||||
script. See
|
|
||||||
.Em ENVIRONMENT .
|
|
||||||
Note that
|
|
||||||
.Nm
|
|
||||||
simply sources this file, which means that any shell code in it will be
|
|
||||||
executed each time
|
|
||||||
.Nm
|
|
||||||
is invoked.
|
|
||||||
.Sh EXIT STATUS
|
|
||||||
.Sh HISTORY
|
|
||||||
.Sh CAVEATS
|
|
||||||
.Sh BUGS
|
|
|
@ -1,241 +0,0 @@
|
||||||
.Dd $Mdocdate: September 30 2022 $
|
|
||||||
.Dt TELODENDRIA 7
|
|
||||||
.Os Telodendria Project
|
|
||||||
.Sh NAME
|
|
||||||
.Nm Telodendria
|
|
||||||
.Nd The terminal branches of an axon.
|
|
||||||
.Sh DESCRIPTION
|
|
||||||
.Nm
|
|
||||||
is an open source Matrix homeserver written entirely from scratch in ANSI C.
|
|
||||||
It is designed to be lightweight and simple, yet functional.
|
|
||||||
.sp
|
|
||||||
.Sy Note:
|
|
||||||
.Nm
|
|
||||||
is under
|
|
||||||
.Sy heavy
|
|
||||||
development. Please see
|
|
||||||
.Sx PROJECT STATUS .
|
|
||||||
.sp
|
|
||||||
.Nm
|
|
||||||
differentiates itself from the other Matrix homeserver
|
|
||||||
implementations because it:
|
|
||||||
.Bl -bullet
|
|
||||||
.It
|
|
||||||
Is written in C, a stable, low-level programming language with a
|
|
||||||
long history, low build and runtime overhead, and wide compatibility.
|
|
||||||
.It
|
|
||||||
Is written with minimalism as a primary design goal. Whenever possible
|
|
||||||
and practical, no third-party libraries are pulled into the source code.
|
|
||||||
Everything
|
|
||||||
.Nm
|
|
||||||
needs is custom written. As a result,
|
|
||||||
.Nm
|
|
||||||
depends only on a standard C compiler and a POSIX C library to be built,
|
|
||||||
both of which should come with any good Unix-style operating system already,
|
|
||||||
which means you shouldn't have to install anything extra.
|
|
||||||
.It
|
|
||||||
Uses a flat-file directory structure to store data instead of a database.
|
|
||||||
This has a number of advantages:
|
|
||||||
.Bl -bullet
|
|
||||||
.It
|
|
||||||
It makes setup and maintenance much easier.
|
|
||||||
.It
|
|
||||||
It allows
|
|
||||||
.Nm
|
|
||||||
to run on systems with fewer resources.
|
|
||||||
.El
|
|
||||||
.It
|
|
||||||
Is packaged as a single small, statically-linked and highly-optimized binary
|
|
||||||
that can be run just about anywhere. It is designed to be extremely easy to
|
|
||||||
set up and consume as few resources as possible.
|
|
||||||
.It
|
|
||||||
Is permissively licensed.
|
|
||||||
.Nm
|
|
||||||
is licensed under a modified MIT license, which imposes very few restrictions
|
|
||||||
on what you can do with it.
|
|
||||||
.El
|
|
||||||
.sp
|
|
||||||
.Nm
|
|
||||||
is on Matrix! Check out the official Matrix rooms:
|
|
||||||
.sp
|
|
||||||
.TS
|
|
||||||
box tab(;);
|
|
||||||
l l.
|
|
||||||
#telodendria-releases:bancino.net;Get notified of new releases.
|
|
||||||
#telodendria-general:bancino.net;General discussion and support.
|
|
||||||
#telodendria-issues:bancino.net;Report bugs and issues.
|
|
||||||
#telodendria-patches:bancino.net;Submit code patches to the project.
|
|
||||||
.TE
|
|
||||||
.Sh RATIONALE
|
|
||||||
I want a lightweight Matrix homeserver designed specifically for OpenBSD,
|
|
||||||
and other Unix-like operating systems. I want a homeserver that can be
|
|
||||||
developed and compiled with built-in tools. I want it to function entirely
|
|
||||||
on a base OS install without having to install any packages whatsoever. I've
|
|
||||||
found that as far as these goals are concerned, the existing homeserver
|
|
||||||
implementations fall short. This project aims to prove that Matrix homeservers
|
|
||||||
can be lightweight and written in such a way that very few, if any, third-party
|
|
||||||
libraries need to be pulled in.
|
|
||||||
.sp
|
|
||||||
I also want to learn how Matrix works, and I want to understand the code I'm
|
|
||||||
running on my server, which is why I'm writing every component from scratch,
|
|
||||||
even the HTTP server and router.
|
|
||||||
.sp
|
|
||||||
The advantage of using a flat-file database instead of a real database is that
|
|
||||||
your data remains in a format that is incredibly easy to digest. Backups are
|
|
||||||
incredibly easy as well\(emjust
|
|
||||||
.Xr tar 1
|
|
||||||
up the data directory and you're good to go.
|
|
||||||
.Sh PROJECT GOALS
|
|
||||||
The goals of this project are generally divided into user goals and developer
|
|
||||||
goals, depending on who they impact the most. This isn't an exaustive list
|
|
||||||
of the project's goals, but it is a list of things that I want to prioritize,
|
|
||||||
because other server implementations lack them.
|
|
||||||
.sp
|
|
||||||
The user goals are as follows:
|
|
||||||
.Bl -bullet
|
|
||||||
.It
|
|
||||||
To implement the latest Matrix specification as fully and completely as possible.
|
|
||||||
All features defined by the specification should eventually be present in
|
|
||||||
.Nm .
|
|
||||||
.It
|
|
||||||
To be as privacy-friendly as possible.
|
|
||||||
.Nm
|
|
||||||
should not store any information it does not absolutely need to function as a
|
|
||||||
Matrix homeserver. While
|
|
||||||
.Nm
|
|
||||||
strives to be feature-complete, it should not implement anything not explicitly
|
|
||||||
defined in the Matrix specification.
|
|
||||||
.It
|
|
||||||
To be a production-ready Matrix server capable of working in constrained environments,
|
|
||||||
such as embedded devices, cheap VPSs, or a peer-to-peer device.
|
|
||||||
.Nm
|
|
||||||
should also work on traditional setups as well, and be able to handle a decent
|
|
||||||
amount of users. It should work well for personal Matrix homeservers that also
|
|
||||||
host a few friends and/or family members.
|
|
||||||
.It
|
|
||||||
To be easier to get up and running, and yet also be more configurable than other
|
|
||||||
Matrix homeserver implementations. The configuration file should be flexible,
|
|
||||||
well-documented, and easy to understand and modify. An intuitive command-line
|
|
||||||
tool for administrative tasks should also be available.
|
|
||||||
.El
|
|
||||||
.sp
|
|
||||||
The developer goals are as follows:
|
|
||||||
.Bl -bullet
|
|
||||||
.It
|
|
||||||
To have as few build and runtime dependencies as possible. It should be possible
|
|
||||||
to compile and run
|
|
||||||
.Nm
|
|
||||||
on any POSIX operating system right out of the box.
|
|
||||||
.Nm
|
|
||||||
should be fully statically-linked, so it can run under a
|
|
||||||
.Xr chroot 3 .
|
|
||||||
Furthermore, it should be possible to read all the documentation offline, and
|
|
||||||
without any overly complicated tools. You'll notice that this documentation is
|
|
||||||
a collection of
|
|
||||||
.Xr man 1
|
|
||||||
pages, not HTML or Markdown, to remove the dependency on a browser or Markdown
|
|
||||||
parser. Any Unix-like system has a manual page viewer, which makes the
|
|
||||||
documentation more accessible, even on remote systems that have no graphical
|
|
||||||
interface to read the documentation. This ensures that you can read the
|
|
||||||
documentation for the installed version of
|
|
||||||
.Nm
|
|
||||||
without having to go online.
|
|
||||||
.It
|
|
||||||
To have a simple yet elegant workflow, and not depend on any large or complex
|
|
||||||
development tools such as code forges. The entire development workflow should
|
|
||||||
be able to be successfully and efficiently completed on a base OpenBSD install.
|
|
||||||
Of course, you don't have to use OpenBSD for development, but the point is that
|
|
||||||
the workflow should require fairly standardized and simple tools.
|
|
||||||
.It
|
|
||||||
To write clean, elegant, well-tested, and well-documented code. The goal is to build
|
|
||||||
a Matrix homeserver from the ground up, not just because I don't like the way existing
|
|
||||||
homeservers are implemented, but also because I want to learn how Matrix works,
|
|
||||||
make it more accessible, and potentially teach others a little bit along the way.
|
|
||||||
.It
|
|
||||||
To foster a welcoming community. Many big communities such as Linux and OpenBSD
|
|
||||||
have hostile leaders.
|
|
||||||
.Nm
|
|
||||||
shouldn't have a hostile leader. I want to be as understanding as I can, and talk
|
|
||||||
through issues politely and in a civil manner. If I'm failing in this way, don't
|
|
||||||
be afraid to call me out!
|
|
||||||
.El
|
|
||||||
.Sh PROJECT STATUS
|
|
||||||
Telodendria is a very ambitious project. There's a lot that needs to happen yet
|
|
||||||
before it is usable. At the moment, there's nothing here that even remotely resembles
|
|
||||||
a Matrix homeserver. I'm still getting off the ground and building a foundation.
|
|
||||||
.sp
|
|
||||||
But just because there's nothing here yet doesn't mean you should go away! I could
|
|
||||||
always use help, so you are more than welcome to help out if you want things to go
|
|
||||||
quicker. Please see the
|
|
||||||
.Xr contributing 7
|
|
||||||
page for details on how you can get involved. The CVS repository has a file called
|
|
||||||
.Pa TODO.txt ,
|
|
||||||
which contains a checklist of what has been done so far, and what's on the radar
|
|
||||||
to be done. You can take a look at it once you've checked out the source code.
|
|
||||||
If you'd like to help out, feel free to grab an item on the list that's not done
|
|
||||||
yet and start getting patches written. When you're done, enjoy the satisfaction
|
|
||||||
of crossing the item off the list yourself.
|
|
||||||
.Sh SEE ALSO
|
|
||||||
.Xr telodendria 8 ,
|
|
||||||
.Xr telodendria.conf 5 ,
|
|
||||||
.Xr td 8
|
|
||||||
.Sh STANDARDS
|
|
||||||
The installed version of
|
|
||||||
.Nm
|
|
||||||
conforms to the latest Matrix specification available at the time
|
|
||||||
of its release.
|
|
||||||
.Sh HISTORY
|
|
||||||
At this time,
|
|
||||||
.Nm
|
|
||||||
does not have any tagged releases because it is not yet functional
|
|
||||||
as a Matrix homeserver. Please checkout out
|
|
||||||
.Sx PROJECT STATUS
|
|
||||||
to see where things are currently at. When
|
|
||||||
.Nm
|
|
||||||
is mature enough to have a change log, it will go in this section.
|
|
||||||
.Sh AUTHORS
|
|
||||||
.Nm
|
|
||||||
was started by Jordan Bancino <@jordan:bancino.net>.
|
|
||||||
Contributions to the code, website, documentation, or other
|
|
||||||
components of
|
|
||||||
.Nm
|
|
||||||
were made by the following people:
|
|
||||||
.Bl -bullet
|
|
||||||
.It
|
|
||||||
Jonah Evans <@jonah:bancino.net>
|
|
||||||
.El
|
|
||||||
.Sh LICENSE
|
|
||||||
All of the code and documentation for
|
|
||||||
.Nm
|
|
||||||
is licensed under a modified MIT license. Please consult the
|
|
||||||
.Pa LICENSE.txt
|
|
||||||
file for the actual license text. The
|
|
||||||
.Nm
|
|
||||||
license text differs from the MIT license in the following ways:
|
|
||||||
.Bl -bullet
|
|
||||||
.It
|
|
||||||
Where the MIT license states that the copyright notice and permission
|
|
||||||
notice shall be included in all copies or
|
|
||||||
.Pa substantial
|
|
||||||
portions of the software, the
|
|
||||||
.Nm
|
|
||||||
license requires the copyright notice and permission notice be included
|
|
||||||
with
|
|
||||||
.Pa all
|
|
||||||
portions, regardless of the size, of the software by omitting the word
|
|
||||||
.Pa substantial .
|
|
||||||
.El
|
|
||||||
.sp
|
|
||||||
The
|
|
||||||
.Nm
|
|
||||||
logo, however, belongs solely to the
|
|
||||||
.Nm
|
|
||||||
project. It must only be used to represent the official
|
|
||||||
.Nm
|
|
||||||
project, and may only appear in official
|
|
||||||
.Nm
|
|
||||||
media. If
|
|
||||||
.Nm
|
|
||||||
is forked, the logo must be removed completely from the project, and
|
|
||||||
optionally replaced with a different one. The logo may not be modified
|
|
||||||
in any way or for any purpose.
|
|
|
@ -1,57 +0,0 @@
|
||||||
.Dd $Mdocdate: September 30 2022 $
|
|
||||||
.Dt TELODENDRIA 8
|
|
||||||
.Os Telodendria Project
|
|
||||||
.Sh NAME
|
|
||||||
.Nm telodendria
|
|
||||||
.Nd Matrix homeserver daemon
|
|
||||||
.Sh SYNOPSIS
|
|
||||||
.Nm
|
|
||||||
.Op Fl nVv
|
|
||||||
.Op Fl f Ar file
|
|
||||||
.Sh DESCRIPTION
|
|
||||||
.Nm
|
|
||||||
is a Matrix homeserver written entirely from scratch in ANSI C.
|
|
||||||
It is designed to be lightweight and simple, yet functional.
|
|
||||||
.sp
|
|
||||||
The options are as follows:
|
|
||||||
.Bl -tag -width Ds
|
|
||||||
.It Fl f Ar file
|
|
||||||
Specify an alternate configuration file. The default is
|
|
||||||
.Pa /etc/telodendria.conf .
|
|
||||||
.It Fl n
|
|
||||||
Configtest mode. Only check the configuration file for validity.
|
|
||||||
.It Fl V
|
|
||||||
Only print the version information header.
|
|
||||||
.It Fl v
|
|
||||||
Verbose mode. This overrides the configuration file and sets the
|
|
||||||
log level to
|
|
||||||
.Em LOG_DEBUG
|
|
||||||
.El
|
|
||||||
.Sh ENVIRONMENT
|
|
||||||
.Nm
|
|
||||||
does not read any environment variables. All configuration should
|
|
||||||
be done via the configuration file.
|
|
||||||
.Sh FILES
|
|
||||||
Just the configuration file and the data directory; see
|
|
||||||
.Xr telodendria.conf 5
|
|
||||||
for more details.
|
|
||||||
.El
|
|
||||||
.Sh EXIT STATUS
|
|
||||||
.Nm
|
|
||||||
exits with a non-0 exit code if the configuration file is invalid, or
|
|
||||||
one or more required paths is inaccessible.
|
|
||||||
.Nm
|
|
||||||
will print an error to the log and then terminate abnormally.
|
|
||||||
.Pp
|
|
||||||
.Nm
|
|
||||||
exits with a code of 0 if the configuration file is valid, all
|
|
||||||
paths and files required are accessible, and the HTTP listener starts
|
|
||||||
as intended. If
|
|
||||||
.Nm
|
|
||||||
is sent a signal that it catches after it begins servicing requests, it
|
|
||||||
will still exit with a code of 0 after it safely shuts down, because
|
|
||||||
the bootstrap process completed successfully, and by all accounts,
|
|
||||||
it ran normally and exitted normally.
|
|
||||||
.Sh SEE ALSO
|
|
||||||
.Xr telodendria 7 ,
|
|
||||||
.Xr telodendria.conf 5
|
|
|
@ -1,190 +0,0 @@
|
||||||
.Dd $Mdocdate: September 29 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:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
macro1 = "value1";
|
|
||||||
directive $macro1;
|
|
||||||
.Ed
|
|
||||||
.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 base-url 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 identity-server Ar url
|
|
||||||
The identity server that clients should use to perform identity lookups.
|
|
||||||
.Pp
|
|
||||||
.Ar url
|
|
||||||
follows the same rules as
|
|
||||||
.Ic base-url .
|
|
||||||
.Pp
|
|
||||||
This directive is optional. If it is not specified, it is automatically
|
|
||||||
set to be the same as the base URL.
|
|
||||||
.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
|
|
Loading…
Reference in a new issue