From 96e33a0777a49eb2797dd502ed0c5db8ec6e9c54 Mon Sep 17 00:00:00 2001
From: Conrad Hoffmann <ch@bitfehler.net>
Date: Mon, 5 Feb 2024 21:44:34 +0100
Subject: [PATCH] Add tokidoki(8) man page

---
 doc/tokidoki.8.scd | 111 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 doc/tokidoki.8.scd

diff --git a/doc/tokidoki.8.scd b/doc/tokidoki.8.scd
new file mode 100644
index 0000000..528c6d8
--- /dev/null
+++ b/doc/tokidoki.8.scd
@@ -0,0 +1,111 @@
+tokidoki(8)
+
+# NAME
+
+tokidoki - a CalDAV/CardDAV server
+
+# SYNOPSIS
+
+*tokidoki* [OPTIONS]
+
+# DESCRIPTION
+
+*tokidoki* runs a multi-user CalDAV/CardDAV server.
+
+Currently, by default only a single address book and calendar per user are
+supported, as users cannot create new ones. If additional resources are created
+manually in the storage backend, *tokidoki* will however serve them just fine.
+
+*tokidoki* supports calendar and address book auto-discovery via
+*/.well-known/caldav* and */.well-known/carddav* respectively, as defined in RFC
+6764, section 6. Hence, most clients should be able to discover available
+resources by just pointing them at the server root.
+
+Regular logs are sent to stderr, HTTP logs are sent to stdout.
+
+# OPTIONS
+
+*-addr* _addr_
+	Bind to the specified address/port. Default: ":8080" (port 8080 on all
+	interfaces.
+
+*-auth.url* _url_
+	Auth backend URL (required). See AUTH BACKENDS below.
+
+*-cert* _filename_
+	Enable TLS and load certificate from _filename_. Requires *-key*.
+
+*-key* _filename_
+	Enable TLS and load key from _filename_. Requires *-cert*.
+
+*-log.debug*
+	Enable debug logs.
+
+*-log.json*
+	Enable structured logs.
+
+# AUTH BACKENDS
+
+Currently, all requests to tokidoki must be authenticated. To validate
+usernames and passwords, tokidoki supports a number of auth backends. The
+following authentication backends are available:
+
+## IMAP
+
+The IMAP auth backend defers authentication to the provided IMAP server.
+Convenient for large-scale deployments in conjunction with email services, or
+self-hosted email setups. Do not use this unless you control the specified IMAP
+server. Deferring authentication to e.g. Gmail would allow any Gmail user to
+authenticate.
+
+URL: *imaps://*_server_*:*_port_
+
+_Note:_ for development, *imap://* is also supported (plain IMAP without
+encryption). This is not recommended for production use.
+
+## PAM
+
+The PAM auth backed defers authentication to the local *PAM*(8) subsystem. This
+allows e.g. authentication as system user(s). Convenient for (mostly)
+single-user self-hosted setups.
+
+URL: *pam://* (no parameters)
+
+_Note:_ The PAM auth backend must be enabled at build time, as PAM may not be
+available on all platforms.
+
+## Static file (htpasswd)
+
+The static file auth backend relies on the file format popularized by Apache and
+other web servers for basic authentication. Such files are often created and edited
+using *htpasswd*(1). Convenient for small setups where virtual users (i.e. users
+that are not system users) are required or desired.
+
+URL: *file://*_path_ (both absolute and relative paths are supported)
+
+_Note:_ This backend has the significant limitation that it only supports
+bcrypt-hashed passwords (recognizable by the hash starting with *$2y$*). To
+create a file, use e.g. the following command:
+
+```
+htpasswd -c -B -C 17 <filename> <user>
+```
+
+# STORAGE BACKENDS
+
+To store users calendars and address books, tokidoki requires a storage backend.
+Currently, the following storage backends are available:
+
+## Filesystem
+
+The filesystem storage backend stores every event and every contact as
+individual file, in folders organized by user and resource, underneath the
+provided base path. The filesystem backend is relatively simple, with good
+performance.
+
+URL: *file://*_path_ (absolute path required)
+
+# SEE ALSO
+
+Links to the source code and mailing lists for discussion and development of
+*tokidoki* can be found at https://sr.ht/~sircmpwn/tokidoki.