.TH HERBARIUM 1 herbarium\-VERSION
.SH NAME
herbarium \- mailing list archive web interface
.SH SYNOPSIS
.B herbarium
.RB [ \-v ]
.SH DESCRIPTION
.B herbarium
is a CGI program that shows the archives
.BR pollen (1)
keeps in
.IR root / list /archive.
Only lists whose name matches
.B ^[a-z0-9][a-z0-9-]*$
and that contain a
.B public
file are shown.
.P
Each request reads the headers of the newest
.B maxmsgs
messages, by file modification time, from the
.B new
and
.B cur
directories of the archive.
Messages are threaded by
.B In-Reply-To
and then
.BR References .
If several messages share a
.BR Message-ID ,
the oldest one is kept.
A missing or implausible
.B Date
is replaced by the file modification time.
.P
Pages are selected by
.BR PATH_INFO ,
where
.I id
is a
.B Message-ID
without angle brackets:
.TP
.B /
Index of all public lists with description, address, number of threads
and age of the last message.
.TP
.IB /list /
Threads, most recently active first,
.B perpage
per page; older pages are reached with
.BI ?ofs= n .
.TP
.IB /list / id /
The thread started by
.IR id .
Any other message redirects to its thread.
Plain text and patch parts are shown, decoded to UTF-8, up to
.B maxbody
bytes per message; HTML parts and attachments are only named.
Multipart nesting is followed up to
.B maxdepth
levels.
.TP
.IB /list / id /raw
The message as archived, served as
.BR text/plain .
.TP
.IB /list / id /t.mbox.gz
The whole thread as a gzipped mboxrd file, as fetched by
.BR b4 (1).
.P
Every response carries a Content-Security-Policy that allows only the
stylesheet and icon from the same origin.
.SH OPTIONS
.TP
.B \-v
prints version information to stderr, then exits.
.SH ENVIRONMENT
.TP
.B PATH_INFO
The page.
.TP
.B SCRIPT_NAME
URL prefix for links.
.TP
.B QUERY_STRING
.BI ofs= n
for the thread list.
.SH FILES
.TP
.IR root / list /public
Present if the archive is public.
.TP
.IR root / list /description
One line describing the list.
.TP
.IR root / list /archive/
Maildir written by
.BR pollen (1).
.B herbarium
only needs read access, for example through pollen's group.
.TP
.IR PREFIX /share/herbarium/style.css ", " icon.svg
Stylesheet and icon, to be served at
.B css
and
.BR icon .
.SH EXAMPLES
.B herbarium
sets no resource limits itself.
Run it through a wrapper:
.P
.nf
#!/bin/sh
ulimit -t 10
exec /usr/local/bin/herbarium
.fi
.P
.BR nginx :
.P
.nf
location = /style.css { alias /usr/local/share/herbarium/style.css; }
location = /icon.svg { alias /usr/local/share/herbarium/icon.svg; }
location / {
	include fastcgi_params;
	fastcgi_param SCRIPT_FILENAME /usr/local/bin/herbarium-cgi;
	fastcgi_param SCRIPT_NAME "";
	fastcgi_param PATH_INFO $uri;
	fastcgi_pass unix:/run/fcgiwrap.sock;
}
.fi
.SH CUSTOMIZATION
.B herbarium
is configured by editing
.I config.h
and recompiling.
.SH SEE ALSO
.BR pollen (1),
.BR petal (1)