greenhousegreenhouse / herbarium / herbarium.1136 lines · 2754B · 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.gz
70The whole thread as a gzipped mboxrd file, as fetched by
71.BR b4 (1).
72.P
73Every response carries a Content-Security-Policy that allows only the
74stylesheet and icon from the same origin.
75.SH ENVIRONMENT
76.TP
77.B PATH_INFO
78The page.
79.TP
80.B SCRIPT_NAME
81URL prefix for links.
82.TP
83.B QUERY_STRING
84.BI ofs= n
85for the thread list.
86.SH FILES
87.TP
88.IR root / list /public
89Present if the archive is public.
90.TP
91.IR root / list /description
92One line describing the list.
93.TP
94.IR root / list /archive/
95Maildir written by
96.BR pollen (1).
97.B herbarium
98only needs read access, for example through pollen's group.
99.TP
100.IR PREFIX /share/herbarium/style.css ", " icon.svg
101Stylesheet and icon, to be served at
102.B css
103and
104.BR icon .
105.SH EXAMPLES
106.B herbarium
107sets no resource limits itself.
108Run it through a wrapper:
109.P
110.nf
111#!/bin/sh
112ulimit -t 10
113exec /usr/local/bin/herbarium
114.fi
115.P
116.BR nginx :
117.P
118.nf
119location = /style.css { alias /usr/local/share/herbarium/style.css; }
120location = /icon.svg { alias /usr/local/share/herbarium/icon.svg; }
121location / {
122 include fastcgi_params;
123 fastcgi_param SCRIPT_FILENAME /usr/local/bin/herbarium-cgi;
124 fastcgi_param SCRIPT_NAME "";
125 fastcgi_param PATH_INFO $uri;
126 fastcgi_pass unix:/run/fcgiwrap.sock;
127}
128.fi
129.SH CUSTOMIZATION
130.B herbarium
131is configured by editing
132.I config.h
133and recompiling.
134.SH SEE ALSO
135.BR pollen (1),
136.BR petal (1)