tokidoki/doc/tokidoki.8.scd

119 lines
3.5 KiB
Plaintext
Raw Normal View History

2024-02-05 20:44:34 +00:00
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.
2024-02-19 17:19:32 +00:00
## OAuth 2.0
The OAuth 2.0 auth backend delegates authentication to the provided OAuth 2.0
server.
URL: *https://*_client_id_*:*_client_secret_*@*_host_
2024-02-05 20:44:34 +00:00
## 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.