X-Git-Url: http://www.git.stargrave.org/?a=blobdiff_plain;f=Documentation%2Fpublic-inbox-config.pod;h=ed99b188beb198a470d52ba179f1f40448261e57;hb=d07ba9c30800225052d17ccca458afbfa05a8ff0;hp=f894eb3d7ff7d148fe275e86dd6027c6e7bc69aa;hpb=f1877b77595bd88cc74ef0ed58ca1f0ae5adc0e4;p=public-inbox.git diff --git a/Documentation/public-inbox-config.pod b/Documentation/public-inbox-config.pod index f894eb3d..ed99b188 100644 --- a/Documentation/public-inbox-config.pod +++ b/Documentation/public-inbox-config.pod @@ -17,13 +17,17 @@ all public-inboxes used by a particular user. =head2 EXAMPLE [publicinbox "test"] - mainrepo = /home/user/path/to/test.git + inboxdir = /home/user/path/to/test.git ; multiple addresses are supported address = test@example.com ; address = alternate@example.com url = http://example.com/test newsgroup = inbox.test + ; backwards compatibility with public-inbox pre-1.2.0, + ; "inboxdir" takes precedence over "mainrepo" + mainrepo = /home/user/path/to/test.git + =head2 VARIABLES =over 8 @@ -38,11 +42,14 @@ informational purposes. Default: none, required -=item publicinbox..mainrepo +=item publicinbox..inboxdir The absolute path to the directory which hosts the public-inbox. This must be specified once. +This was previously known as "mainrepo", which remains supported, +but "inboxdir" takes precedence. + Default: none, required =item publicinbox..url @@ -55,42 +62,90 @@ Default: none, optional =item publicinbox..newsgroup -The NNTP group name for use with L. This -may be any newsgroup name with hierarchies delimited by '.'. +The NNTP group name for use with L. This +may be any newsgroup name with hierarchies delimited by C<.>. For example, the newsgroup for L is: C -Omitting this for the given inbox will prevent the group from -being read by L +It also configures the folder hierarchy used by L +as well as L + +Omitting this for a given inbox will prevent the inbox from +being served by L, +L, and/or L Default: none, optional =item publicinbox..watch -A location for L to watch. Currently, -only C paths are supported: +See L - [publicinbox "test"] - watch = maildir:/path/to/maildirs/.INBOX.test/ +=item publicinbox..watchheader -Default: none; only for L users +See L -=item publicinbox..watchheader +=item publicinbox..listid - [publicinbox "test"] - watchheader = List-Id: +The L header without +angle brackets for L deliveries and +L. + +For public-inbox-watch users, this is a shortcut for specifying +Cfoo.example.comE> + +For public-inbox-mda users, this may be used to avoid recipient +matching via C environment variable. -Default: none; only for L users +This may be specified multiple times for merging multiple mailing +lists into a single public-inbox, only one C header +needs to match. + +Default: none + +=item publicinbox..imapmirror + +This may be the full IMAP URL of an independently-run IMAP mirror. + +Default: none =item publicinbox..nntpmirror This may be the full NNTP URL of an independently-run mirror. For example, the https://public-inbox.org/meta/ inbox is mirrored by Gmane at -C +C Default: none +=item publicinbox..indexlevel + +The indexing level for L + +C only requires L and provides all +NNTP functionality along with thread-awareness in the WWW +interface. + +C requires L to provide full-text +term search functionality in the WWW UI. + +C also includes positional information used by Xapian to +allow for searching for phrases using quoted text. +(e.g. C<"looking for a complete sentence">) + +Default: C + +=item publicinbox..boost + +Control indexing order for L, with ties +broken by config file order. This only affects indexing and does +not affect messages which are already indexed. + +Default: C<0> + +=item publicinbox..indexSequentialShard + +See L + =item publicinbox..httpbackendmax If a digit, the maximum number of parallel @@ -122,7 +177,7 @@ interface are displayed. A list of comma-delimited email addresses may be specified. This can be useful for dedicated inboxes for bot emails, but -discussion happens on a seperate mailing list/inbox. +discussion happens on a separate mailing list/inbox. Mirrors of existing centralized mailing lists may use ":list" here to redirect mail only to the configured inbox address. @@ -152,34 +207,31 @@ Default: spamc =item publicinboxwatch.spamcheck -This may be set to C to enable the use of SpamAssassin -L for filtering spam before it is imported into git -history. Other spam filtering backends may be supported in -the future. - -Default: none +See L =item publicinboxwatch.watchspam -This may be set to C to enable the use of SpamAssassin -L for filtering spam before it is imported into git -history. Other spam filtering backends may be supported in -the future. This requires L, but affects -all configured public-inboxes in PI_CONFIG. +See L + +=item publicinbox.imapserver + +Set this to point to the hostname(s) of the L +instance. This is used to advertise the existence of the IMAP +endpoint in the L HTML interface. Default: none =item publicinbox.nntpserver -Set this to point to the address of the L -instance. This is used to advertise the existence of the NNTP -presnce in the L HTML interface. - -Multiple values are allowed for servers with multiple -addresses or mirrors. +Same as C, but for the hostname(s) of the +L instance. Default: none +=item publicinbox.pop3state + +See L + =item publicinbox..feedmax The size of an Atom feed for the inbox. If specified more than @@ -188,6 +240,14 @@ be treated as the default value. Default: 25 +=item publicinbox..hide + +A comma-delimited list of listings to hide the inbox from. + +Valid values are currently C and C. + +Default: none + =item coderepo..dir The path to a git repository for "publicinbox..coderepo" @@ -217,6 +277,109 @@ directive is configured. Default: /var/www/htdocs/cgit/cgit.cgi or /usr/lib/cgit/cgit.cgi +=item publicinbox.cgitdata + +A path to the data directory used by cgit for storing static files. +Typically guessed based the location of C (from +C, but may be overridden. + +Default: basename of C, /var/www/htdocs/cgit/ +or /usr/share/cgit/ + +=item publicinbox.mailEditor + +See L + +=item publicinbox.indexMaxSize +=item publicinbox.indexBatchSize +=item publicinbox.indexSequentialShard + +See L + +=item publicinbox.wwwlisting + +Enable a HTML listing style when the root path of the URL '/' is accessed. +Valid values are: + +=over 8 + +=item * all +- Show all inboxes + +=item * 404 +- Return a 404 page. This is useful to allow customization with +L + +=item * match=domain +- Only show inboxes with URLs which belong to the domain of the HTTP request + +=for comment +TODO support showing cgit listing + +=back + +Default: C<404> + +=item publicinbox.grokmanifest + +Controls the generation of a grokmirror-compatible gzipped JSON file +at the top-level of the PSGI interface. You generally do not need to +change this from the default. + +Valid values are: + +=over 8 + +=item * match=domain +- Only include inboxes with URLs which belong to the domain of +the HTTP request. This is compatible with virtual hosting where +several domains come from the same host. + +=item * all +- All inboxes are present in C, regardless of domain. +Only use this if you're serving HTTP requests in a domain-agnostic manner. + +=item * 404 +- C will only contain an empty JSON array. +This does NOT affect C<$INBOX_URL/manifest.js.gz>, which will +always contain all git repos used by the inbox at C<$INBOX_URL> + +=back + +Default: C + +=item publicinbox..obfuscate + +Whether to obfuscate email addresses in the L HTML +interface. + +Default: false + +=item publicinbox.noObfuscate + +A space-delimited list of well-known addresses and domains that should +not be obfuscated when C is true (e.g., +C and C<@example.com>). This may be specified +more than once, in which case the values are merged. + +Default: none + +=item extindex..topdir + +The directory of an external index. See +L for more details. + +=item extindex..url + +Identical to LnameE.url>, but for +external indices + +=item extindex..coderepo + +Identical to LnameE.coderepo>, but for +external indices. Code repos may be freely associated with +any number of public inboxes and external indices. + =back =head2 NAMED LIMITER (PSGI) @@ -229,7 +392,7 @@ limiter with a low max value; while smaller inboxes can use the default limiter. C keys may be set to enforce resource limits for -a particular limiter. +a particular limiter (L is required). Default named-limiters are prefixed with "-". Currently, the "-cgit" named limiter is reserved for instances spawning @@ -261,20 +424,20 @@ RLIMIT_CPU, and RLIMIT_DATA for you operating system. ; big inboxes which require lots of memory to clone: [publicinbox "big1"] - mainrepo = /path/to/big1 + inboxdir = /path/to/big1 address = big1@example.com httpbackendmax = big [publicinbox "big2"] - mainrepo = /path/to/big2 + inboxdir = /path/to/big2 address = big2@example.com httpbackendmax = big ; tiny inboxes which are easily cloned: [publicinbox "tiny1"] - mainrepo = /path/to/tiny1 + inboxdir = /path/to/tiny1 address = tiny1@example.com [publicinbox "tiny2"] - mainrepo = /path/to/tiny2 + inboxdir = /path/to/tiny2 address = tiny2@example.com [publicinboxlimiter "big"] @@ -301,16 +464,17 @@ Used to override the default "~/.public-inbox/config" value. Feedback welcome via plain-text mail to L -The mail archives are hosted at L -and L +The mail archives are hosted at L and +L =head1 COPYRIGHT -Copyright 2016-2018 all contributors L +Copyright all contributors L License: AGPL-3.0+ L =head1 SEE ALSO L, L, L, -L, L +L, L, +L