~sircmpwn/tokidoki

96e33a0777a49eb2797dd502ed0c5db8ec6e9c54 — Conrad Hoffmann 4 months ago a87520c
Add tokidoki(8) man page
1 files changed, 111 insertions(+), 0 deletions(-)

A doc/tokidoki.8.scd
A doc/tokidoki.8.scd => doc/tokidoki.8.scd +111 -0
@@ 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.