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