Synopsis

kcaldav is a simple, safe, and minimal CalDAV server running on the BCHS software stack.

This repository consists of bleeding-edge code between versions: to keep up to date with the current stable release of kcaldav, visit the website. The website also contains canonical installation, deployment, examples, and usage documentation.

What follows describes using the bleeding-edge version of the system.

Installation

To use the bleeding-edge version of kcaldav (instead of from your system's packages or a stable version), the process it the similar as for source releases.

Begin by cloning or downloading. Then configure with ./configure, compile with make (BSD make, so it may be bmake on your system), then make install (or use sudo or doas, if applicable).

If not done yet, optionally create a Makefile.local to override values in Makefile for your target file-system.

./configure
make install
make installcgi

The database hasn't updated in a long, long time, so there are no special commands for updating it. When updates do happen, I'll work out a process for doing so.

To create the database for initial use (or to manage it), follow kcaldav.passwd(1).

Regression and fuzzing

To contribute to kcaldav, write regression tests!

Right now, the regression suite only parses valid iCalendar files from ical4j, but in no way makes sure that the information has been properly parsed. Same with the CalDAV tests. To run these:

make regress

A major missing component is a series of regression tests that actually makes sure that parsed content is sane.

Most of the critical infrastructure can also be run through AFL. To do this, run:

make clean
make afl CC=afl-clang

Or use afl-gcc instead---it shouldn't matter. This installs AFL-built binaries into the afl directory. To run these on the iCalendar library:

cd ical
sh ./dict.sh # Generates dictionary files.
afl-fuzz -i in -x dict -o out -- ../test-ical @@

For CalDAV:

cd caldav
afl-fuzz -i in -o out -- ../test-caldav @@

I'd love for more tests on the server infrastructure itself, but am not sure how to effect this properly.

Sources

The source code is laid out fairly consistently and easily.

The centre of the system is in libkcaldav.a, which contains both the CalDAV and iCalendar functions in libkcaldav.h. It's implemented by ical.c and caldav.c.

The database interface is db.h, manipulating the schema in kcaldav.sql. This is used by server and by the built programs and manages users, collections, resources, proxies, etc. It internally uses the libkcaldav.h functions. It is implemented in db.c.

The built programs are the command-line utility kcaldav.passwd(1) and CGI server kcaldav(8).

The CGI server is described in server.h and implemented by the majority of the source code files with entry point kcaldav.c.

The command-line utility is the standalone kcaldav.passwd.c.

The portability glue throughout the system (e.g., HAVE_xxx macros, config.h, etc.) is managed by oconfigure.

License

All sources use the ISC (like OpenBSD) license. See the LICENSE.md file for details.