greenhousegreenhouse / herbarium / herbarium.1135 lines · 2718B · raw
1.TH HERBARIUM 1 herbarium
2.SH NAME
3herbarium \- mailing list archive web interface
4.SH SYNOPSIS
5.B herbarium
6.SH DESCRIPTION
7.B herbarium
8is a CGI program that shows the archives
9.BR pollen (1)
10keeps in
11.IR root / list /archive.
12Only lists whose name matches
13.B ^[a-z0-9][a-z0-9-]*$
14and that contain a
15.B public
16file are shown.
17.P
18Each request reads the headers of the newest
19.B maxmsgs
20messages, by file modification time, from the
21.B new
22and
23.B cur
24directories of the archive.
25Messages are threaded by
26.B In-Reply-To
27and then
28.BR References .
29If several messages share a
30.BR Message-ID ,
31the oldest one is kept.
32A missing or implausible
33.B Date
34is replaced by the file modification time.
35.P
36Pages are selected by
37.BR PATH_INFO ,
38where
39.I id
40is a
41.B Message-ID
42without angle brackets:
43.TP
44.B /
45Index of all public lists with description, address, number of threads
46and age of the last message.
47.TP
48.IB /list /
49Threads, most recently active first,
50.B perpage
51per page; older pages are reached with
52.BI ?ofs= n .
53.TP
54.IB /list / id /
55The thread started by
56.IR id .
57Any other message redirects to its thread.
58Plain text and patch parts are shown, decoded to UTF-8, up to
59.B maxbody
60bytes per message; HTML parts and attachments are only named.
61Multipart nesting is followed up to
62.B maxdepth
63levels.
64.TP
65.IB /list / id /raw
66The message as archived, served as
67.BR text/plain .
68.TP
69.IB /list / id /t.mbox
70The whole thread as an mboxrd file.
71.P
72Every response carries a Content-Security-Policy that allows only the
73stylesheet and icon from the same origin.
74.SH ENVIRONMENT
75.TP
76.B PATH_INFO
77The page.
78.TP
79.B SCRIPT_NAME
80URL prefix for links.
81.TP
82.B QUERY_STRING
83.BI ofs= n
84for the thread list.
85.SH FILES
86.TP
87.IR root / list /public
88Present if the archive is public.
89.TP
90.IR root / list /description
91One line describing the list.
92.TP
93.IR root / list /archive/
94Maildir written by
95.BR pollen (1).
96.B herbarium
97only needs read access, for example through pollen's group.
98.TP
99.IR PREFIX /share/herbarium/style.css ", " icon.svg
100Stylesheet and icon, to be served at
101.B css
102and
103.BR icon .
104.SH EXAMPLES
105.B herbarium
106sets no resource limits itself.
107Run it through a wrapper:
108.P
109.nf
110#!/bin/sh
111ulimit -t 10
112exec /usr/local/bin/herbarium
113.fi
114.P
115.BR nginx :
116.P
117.nf
118location = /style.css { alias /usr/local/share/herbarium/style.css; }
119location = /icon.svg { alias /usr/local/share/herbarium/icon.svg; }
120location / {
121 include fastcgi_params;
122 fastcgi_param SCRIPT_FILENAME /usr/local/bin/herbarium-cgi;
123 fastcgi_param SCRIPT_NAME "";
124 fastcgi_param PATH_INFO $uri;
125 fastcgi_pass unix:/run/fcgiwrap.sock;
126}
127.fi
128.SH CUSTOMIZATION
129.B herbarium
130is configured by editing
131.I config.h
132and recompiling.
133.SH SEE ALSO
134.BR pollen (1),
135.BR petal (1)