From 2d6b80a26e650a31f1448cd0197d3a7274aab6e2 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Fri, 30 Sep 2022 19:11:44 -0400 Subject: [PATCH] Move man pages into a proper man directory --- TODO.txt | 20 ++- man/.cvsignore | 1 + man/man3/Array.3 | 114 ++++++++++++++++ man/man3/Base64.3 | 81 ++++++++++++ man/man5/telodendria.conf.5 | 190 +++++++++++++++++++++++++++ man/man7/contributing.7 | 252 ++++++++++++++++++++++++++++++++++++ man/man7/telodendria.7 | 248 +++++++++++++++++++++++++++++++++++ man/man8/td.8 | 238 ++++++++++++++++++++++++++++++++++ man/man8/telodendria.8 | 57 ++++++++ site/index.html | 40 +++--- tools/bin/td | 10 +- tools/env.sh | 7 +- 12 files changed, 1231 insertions(+), 27 deletions(-) create mode 100644 man/.cvsignore create mode 100644 man/man3/Array.3 create mode 100644 man/man3/Base64.3 create mode 100644 man/man5/telodendria.conf.5 create mode 100644 man/man7/contributing.7 create mode 100644 man/man7/telodendria.7 create mode 100644 man/man8/td.8 create mode 100644 man/man8/telodendria.8 diff --git a/TODO.txt b/TODO.txt index 4753469..d7c36a3 100644 --- a/TODO.txt +++ b/TODO.txt @@ -75,7 +75,6 @@ Phase 4: [ ] Create an OpenBSD package and get it submitted to ports [ ] Add relayd examples to contrib/ [ ] Create a command line tool to manage Telodendria - [ ] Configuration file generation [ ] User management [ ] Room management [ ] Migrate from Synapse or Dendrite, whichever is more mainstream by the time we get here @@ -100,7 +99,24 @@ Documentation [x] Convert documentation to man pages [x] Clean up dark mode in man page CSS (links) [x] Synopsis table should not be styled - [ ] Internal API docs + [x] Make available on MANPATH in tools/env.sh + [~] Internal API docs + [x] Array + [x] Base64 + [ ] CanonicalJson + [ ] Config + [ ] Constants + [ ] HashMap + [ ] Http + [ ] HttpServer + [ ] Json + [ ] Log + [ ] Matrix + [ ] NonPosix + [ ] Queue + [ ] Routes + [ ] TelodendriaConfig + [ ] Util [ ] Add onboarding documentation [ ] Building from source diff --git a/man/.cvsignore b/man/.cvsignore new file mode 100644 index 0000000..3be3f9a --- /dev/null +++ b/man/.cvsignore @@ -0,0 +1 @@ +mandoc.db diff --git a/man/man3/Array.3 b/man/man3/Array.3 new file mode 100644 index 0000000..e58f868 --- /dev/null +++ b/man/man3/Array.3 @@ -0,0 +1,114 @@ +.Dd $Mdocdate: September 30 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 diff --git a/man/man3/Base64.3 b/man/man3/Base64.3 new file mode 100644 index 0000000..a424532 --- /dev/null +++ b/man/man3/Base64.3 @@ -0,0 +1,81 @@ +.Dd $Mdocdate: September 30 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. diff --git a/man/man5/telodendria.conf.5 b/man/man5/telodendria.conf.5 new file mode 100644 index 0000000..23722a3 --- /dev/null +++ b/man/man5/telodendria.conf.5 @@ -0,0 +1,190 @@ +.Dd $Mdocdate: September 30 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 diff --git a/man/man7/contributing.7 b/man/man7/contributing.7 new file mode 100644 index 0000000..a123cfe --- /dev/null +++ b/man/man7/contributing.7 @@ -0,0 +1,252 @@ +.Dd $Mdocdate: September 30 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. diff --git a/man/man7/telodendria.7 b/man/man7/telodendria.7 new file mode 100644 index 0000000..95cb8de --- /dev/null +++ b/man/man7/telodendria.7 @@ -0,0 +1,248 @@ +.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. +.Pp +.Sy Note: +.Nm +is under +.Sy heavy +development. Please see +.Sx PROJECT STATUS . +.Pp +.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 +.Pp +.Nm +is on Matrix! Check out the official Matrix rooms: +.Pp +.TS +box tab(;); +l l. +#telodendria:bancino.net;The public "space" room. +#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 +.Nm +is designed to be fairly straightforward, but that doesn't mean there +won't be hiccups along the way. If you're struggling to get +.Nm +up and running, you're more than welcome to reach out for support. Just +hop into the appropriate Matrix rooms and talk to me! +.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. +.Pp +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. +.Pp +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. +.Pp +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 +.Pp +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. +.Pp +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 +.Pp +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. diff --git a/man/man8/td.8 b/man/man8/td.8 new file mode 100644 index 0000000..795f7d5 --- /dev/null +++ b/man/man8/td.8 @@ -0,0 +1,238 @@ +.Dd $Mdocdate: September 30 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 diff --git a/man/man8/telodendria.8 b/man/man8/telodendria.8 new file mode 100644 index 0000000..52cf2ab --- /dev/null +++ b/man/man8/telodendria.8 @@ -0,0 +1,57 @@ +.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 diff --git a/site/index.html b/site/index.html index 5b995ed..5de77a3 100644 --- a/site/index.html +++ b/site/index.html @@ -16,20 +16,20 @@ - + Telodendria | A Matrix Homeserver written in ANSI C. - +

Telodendria

Telodendria: The terminal branches of an axon.

Note: Telodendria is under heavy development. -Please see the Project Status. +Please see the Project Status.

Telodendria is an open source Matrix homeserver implementation written from @@ -159,7 +159,7 @@ Signify No downloads here yet. See the -Project Status for more +Project Status for more information. @@ -175,23 +175,23 @@ on what Telodendria is, what its goals are, how to build the source, configure it, as well as contribute to the project. The man pages are also available online for convenience:

- -

Getting Support

-Telodendria is designed to be fairly straightforward, but that -doesn't mean there won't be hiccups along the way. If you are struggling -to get Telodendria up and running, you're more than welcome to -reach out for support. Just join the -#telodendria-general:bancino.net Matrix channel. Before -you do though, make sure you're running the latest version of -Telodendria and you've thoroughly read through all the -relevant documentation. +

+User documentation:

+ +

+Developer documentation: +

+

Resources