| =head1 NAME |
| |
| public-inbox-config - public-inbox config file description |
| |
| =head1 SYNOPSIS |
| |
| ~/.public-inbox/config |
| |
| =head1 DESCRIPTION |
| |
| The public-inbox config file is parseable by L<git-config(1)>. |
| This is a global configuration file for mapping/discovering |
| all public-inboxes used by a particular user. |
| |
| =head1 CONFIGURATION FILE |
| |
| =head2 EXAMPLE |
| |
| [publicinbox "test"] |
| 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 |
| |
| =item publicinbox.<name>.address |
| |
| The email address of the public-inbox. May be specified |
| more than once for merging multiple mailing lists (or migrating |
| to new addresses). This must be specified at least once, |
| the first value will be considered the primary address for |
| informational purposes. |
| |
| Default: none, required |
| |
| =item publicinbox.<name>.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.<name>.url |
| |
| The primary URL for hosting the HTTP/HTTPS archives. |
| Additional HTTP/HTTPS URLs may be specified via |
| C<$GIT_DIR/cloneurl> as documented in L<gitweb(1)> |
| |
| Default: none, optional |
| |
| =item publicinbox.<name>.newsgroup |
| |
| The NNTP group name for use with L<public-inbox-nntpd(1)>. This |
| may be any newsgroup name with hierarchies delimited by C<.>. |
| For example, the newsgroup for L<mailto:meta@public-inbox.org> |
| is: C<inbox.comp.mail.public-inbox.meta> |
| |
| It also configures the folder hierarchy used by L<public-inbox-imapd(1)> |
| as well as L<public-inbox-pop3d(1)> |
| |
| Omitting this for a given inbox will prevent the inbox from |
| being served by L<public-inbox-nntpd(1)>, |
| L<public-inbox-imapd(1)>, and/or L<public-inbox-pop3d(1)> |
| |
| Newsgroup names should be all lowercase. Uppercase characters are |
| converted to lowercase for compatibility with IMAP, POP3, and our |
| L<public-inbox-extindex(1)> and L<public-inbox-cindex(1)> tools |
| starting with public-inbox 2.0+ (they were unusable before). |
| |
| Default: none, optional |
| |
| =item publicinbox.<name>.watch |
| |
| See L<public-inbox-watch(1)> |
| |
| =item publicinbox.<name>.watchheader |
| |
| See L<public-inbox-watch(1)> |
| |
| =item publicinbox.<name>.listid |
| |
| The L<rfc2919|https://tools.ietf.org/html/rfc2919> header without |
| angle brackets for L<public-inbox-mda(1)> deliveries and |
| L<public-inbox-watch(1)>. |
| |
| For public-inbox-watch users, this is a shortcut for specifying |
| C<publicinbox.$NAME.watchheader=List-Id:E<lt>foo.example.comE<gt>> |
| |
| For public-inbox-mda users, this may be used to avoid recipient |
| matching via C<ORIGINAL_RECIPIENT> environment variable. |
| |
| This may be specified multiple times for merging multiple mailing |
| lists into a single public-inbox, only one C<List-Id> header |
| needs to match. |
| |
| Default: none |
| |
| =item publicinbox.<name>.imapmirror |
| |
| This may be the full IMAP URL of an independently-run IMAP mirror. |
| |
| Default: none |
| |
| =item publicinbox.<name>.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<nntp://news.gmane.io/gmane.mail.public-inbox.general> |
| |
| Default: none |
| |
| =item publicinbox.<name>.indexlevel |
| |
| The indexing level for L<public-inbox-index(1)> |
| |
| C<basic> only requires L<DBD::SQLite(3pm)> and provides all |
| NNTP functionality along with thread-awareness in the WWW |
| interface. |
| |
| C<medium> requires L<Xapian(3pm)> or L<Search::Xapian(3pm)> to provide |
| full-text term search functionality in the WWW UI. |
| |
| C<full> 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<full> |
| |
| =item publicinbox.<name>.boost |
| |
| Control indexing order for L<public-inbox-extindex(1)>, 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.<name>.indexSequentialShard |
| |
| See L<public-inbox-index(1)/publicInbox.indexSequentialShard> |
| |
| =item publicinbox.<name>.httpbackendmax |
| |
| If a digit, the maximum number of parallel |
| L<git-http-backend(1)> processes to allow for cloning this |
| particular inbox. |
| |
| If an alphanumeric value starting with a lowercase alphabetic |
| character is specified, the inbox will use a L</NAMED LIMITER> |
| which can be shared by multiple inboxes. |
| |
| Default: 32 (using a default limiter shared by all inboxes) |
| |
| =item publicinbox.<name>.coderepo |
| |
| The nickname of a "coderepo" section associated with the inbox. |
| May be specified more than once for M:N mapping of code repos to |
| inboxes. If enabled, diff hunk headers in patch emails will |
| link to the line numbers of blobs. |
| |
| Default: none |
| |
| =item publicinbox.<name>.altid |
| |
| Index by an alternative ID mechanism as a Xapian search prefix e.g. |
| C<gmane:1234>. This is useful to allow looking up legacy serial IDs |
| (e.g. gmane article numbers). |
| |
| It must be specified in the form of |
| C<serial:$USER_PREFIX:file=$SQLITE_FILENAME> where C<$USER_PREFIX> is a |
| lowercase prefix like C<gmane> for search queries, and |
| C<$SQLITE_FILENAME> is points to an SQLite DB. C<$SQLITE_FILENAME> may |
| be an absolute path or a path relative to C<INBOXDIR> for v2 inboxes or |
| C<INBOXDIR/public-inbox> for v1 inboxes. |
| |
| The schema of C<$SQLITE_FILENAME> should be the same as a |
| C<msgmap.sqlite3>. See C<scripts/xhdr-num2mid> in the public-inbox |
| source tree for an example of how to generate such a mapping from |
| via NNTP. |
| |
| This is a noop with C<indexlevel=basic> |
| |
| Default: none |
| |
| =item publicinbox.<name>.indexheader |
| |
| Supports indexing of arbitrary mail headers in Xapian. |
| |
| It must be specified in the form of |
| C<$TYPE:$USER_PREFIX:$MAIL_HEADER:$PARAMS> |
| where C<$TYPE> determines how it's indexed and queried; |
| C<$USER_PREFIX> is a lowercase prefix for search queries, |
| C<$MAIL_HEADER> is the header to index (e.g. C<X-Label>), |
| C<$PARAMS> is a URL-style query string for optional parameters. |
| |
| Valid C<$TYPE> values (in ascending order of storage cost) are as follows: |
| |
| * C<boolean_term> - index for simple filtering (not sortable by relevance) |
| |
| * C<text> - add frequency information to allow sorting by relevance |
| |
| * C<phrase> - add positional information to match sentences or phrases |
| |
| In other words: C<phrase> forces indexing of a particular header to |
| behave like it used C<indexlevel=full>; while C<text> indexes as if |
| that header used C<indexlevel=medium>. |
| |
| Valid keys in C<$PARAMS> include: |
| |
| * raw - do not perform RFC2047 decoding of headers |
| |
| Example: |
| |
| [publicinbox "foo"] |
| indexheader = boolean_term:xlabel:X-Label:raw=1 |
| |
| Support for other parameters is not finalized and subject to change. |
| |
| This is a noop with C<indexlevel=basic> |
| |
| New in public-inbox 2.0.0 (PENDING) |
| |
| Default: none |
| |
| =item publicinbox.<name>.replyto |
| |
| May be used to control how reply instructions in the PSGI |
| interface are displayed. |
| |
| ":none=dead inbox" may be specified to denote an inactive list |
| ("dead inbox" may be replaced with another phrase). |
| |
| 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 separate mailing list/inbox. |
| |
| Mirrors of existing centralized mailing lists may use ":list" |
| here to redirect mail only to the configured inbox address. |
| The use of ":list" is discouraged for new mailing lists, as it |
| leads to centralization. |
| |
| Default: :all |
| |
| =item publicinbox.css |
| |
| The local path name of a CSS file for the PSGI web interface. |
| Space-separated attributes (C<key=val> or C<key='val with spaces'>) |
| may be specified after the path on the same line; C<media>, C<title> |
| and C<href> are currently supported, and match the associated attributes |
| of the HTML C<E<lt>styleE<gt>> tag. |
| |
| C<href> may be specified to point to the URL of a remote CSS file |
| and the path may be "/dev/null" or any empty file. |
| |
| public-inbox 2.0+ also supports a C<load> attribute with values |
| C<link> or C<import>; C<link> forces the use of a C<E<lt>linkE<gt>> tag |
| and disables inlining CSS into the C<E<lt>styleE<gt>> tag while |
| C<import> puts CSS C<@import> statements into the C<E<lt>styleE<gt>> tag. |
| C<import> appears necessary for some browser and C<media> query combinations. |
| |
| Multiple files may be specified and will be included in the |
| given order, but files specified via C<load=import> are |
| always handled first. |
| |
| Example: |
| |
| [publicinbox] |
| css = /path/to/216dark.css title=216dark \ |
| media='screen,(prefers-color-scheme:dark)' |
| |
| See the L<contrib/css |
| directory of the public-inbox |
| source|https://80x24.org/public-inbox.git/tree/contrib/css> |
| for more examples. |
| |
| =item publicinboxImport.dropUniqueUnsubscribe |
| |
| Drop C<List-Unsubscribe> headers if the message also includes |
| the C<List-Unsubscribe-Post: List-Unsubscribe=One-Click> header |
| to signal MUAs to support an instantaneous unsubscribe. This |
| is strongly recommended for users creating their own public |
| archives of mailing lists they subscribe to, otherwise any |
| archive reader can unsubscribe the archivist. |
| |
| This may break DKIM signatures if the C<List-Unsubscribe*> |
| headers are signed, but breaking DKIM signatures is the |
| lesser evil compared to allowing any reader to unsubscribe |
| the archivist. |
| |
| This affects L<public-inbox-mda(1)>, L<public-inbox-watch(1)>, |
| and L<public-inbox-learn(1)> |
| |
| =item publicinboxmda.spamcheck |
| |
| This may be set to C<none> to disable the use of SpamAssassin |
| L<spamc(1)> for filtering spam before it is imported into git |
| history. Other spam filtering backends may be supported in |
| the future. |
| |
| Default: spamc |
| |
| =item publicinboxwatch.spamcheck |
| |
| See L<public-inbox-watch(1)> |
| |
| =item publicinboxwatch.watchspam |
| |
| See L<public-inbox-watch(1)> |
| |
| =item publicinbox.imapserver |
| |
| Set this to point to the hostname(s) of the L<public-inbox-imapd(1)> |
| instance. This is used to advertise the existence of the IMAP |
| endpoint in the L<PublicInbox::WWW> HTML interface. |
| |
| Default: none |
| |
| =item publicinbox.nntpserver |
| |
| Same as C<publicinbox.imapserver>, but for the hostname(s) of the |
| L<public-inbox-nntpd(1)> instance. |
| |
| Default: none |
| |
| =item publicinbox.pop3server |
| |
| Same as C<publicinbox.imapserver>, but for the hostname(s) of the |
| L<public-inbox-pop3d(1)> instance. |
| |
| Default: none |
| |
| =item publicinbox.pop3state |
| |
| See L<public-inbox-pop3d(1)/publicinbox.pop3state> |
| |
| =item publicinbox.<name>.feedmax |
| |
| The size of an Atom feed for the inbox. If specified more than |
| once, only the last value is used. Invalid values (<= 0) will |
| be treated as the default value. |
| |
| Default: 25 |
| |
| =item publicinbox.<name>.hide |
| |
| A comma-delimited list of listings to hide the inbox from. |
| |
| Valid values are currently C<www> and C<manifest> for non-C<404> |
| values of L</publicinbox.wwwListing> and L</publicinbox.grokManifest>, |
| respectively |
| |
| Default: none |
| |
| =item coderepo.<nick>.dir |
| |
| The path to a git repository for "publicinbox.<name>.coderepo" |
| |
| =item coderepo.<nick>.cgitUrl |
| |
| The URL of the cgit instance associated with the coderepo. |
| |
| Default: none |
| |
| =item coderepo.snapshots |
| |
| See C<snapshots> in L<cgitrc(5)> |
| |
| =item publicinbox.cgitrc |
| |
| A path to a L<cgitrc(5)> file. "repo.url" directives in the cgitrc |
| will be mapped to the nickname of a coderepo (without trailing slash), |
| and "repo.path" directives map to "coderepo.<nick>.dir". |
| Use of this directive allows admins of existing cgit installations |
| to skip declaring coderepo sections and map inboxes directly to |
| code repositories known to cgit. |
| |
| Macro expansion (e.g. C<$HTTP_HOST>) is not yet supported. |
| |
| =item publicinbox.cgitbin |
| |
| A path to the C<cgit.cgi> executable. The L<PublicInbox::WWW> |
| interface can spawn cgit as a fallback if the publicinbox.cgitrc |
| 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 on the location of C<cgit.cgi> (from |
| C<publicinbox.cgitbin>), but may be overridden. |
| |
| Default: dirname of C<publicinbox.cgitbin>, /var/www/htdocs/cgit/ |
| or /usr/share/cgit/ |
| |
| =item publicinbox.cgit |
| |
| Controls whether or not and how C<cgit> is used for serving coderepos. |
| New in public-inbox 2.0.0 (PENDING). |
| |
| =over 8 |
| |
| =item * first |
| |
| Try using C<cgit> as the first choice, this is the default. |
| |
| =item * fallback |
| |
| Fall back to using C<cgit> only if our native, inbox-aware |
| git code repository viewer doesn't recognize the URL. |
| |
| =begin comment |
| =for comment rewrite is not yet implemented |
| =item * rewrite |
| |
| Rewrite C<cgit> URLs for our native, inbox-aware code repository viewer. |
| This implies C<fallback> for URLs the native viewer does not recognize. |
| |
| =end comment |
| |
| =back |
| |
| Default: C<first> (C<cgit> will be used iff C<publicinbox.cgitrc> |
| is set and the C<cgit> binary exists). |
| |
| =item publicinbox.mailEditor |
| |
| See L<public-inbox-edit(1)> |
| |
| =item publicinbox.indexMaxSize |
| |
| =item publicinbox.indexBatchSize |
| |
| =item publicinbox.indexSequentialShard |
| |
| See L<public-inbox-index(1)> |
| |
| =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<Plack::App::Cascade(3pm)> |
| |
| =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.nameIsUrl |
| |
| Treat the name of the public inbox as its unqualified URL when |
| using C<publicInbox.wwwListing=all>. That is, every |
| C<[publicinbox "foo"]> section implicitly sets C<publicinbox.foo.url=foo>. |
| |
| This is a convenient alternative to specifying |
| C<publicinbox.E<lt>nameE<gt>.url> for every single inbox if |
| your inbox URLs are domain-agnostic when using |
| C<publicInbox.wwwListing=all> |
| |
| Default: false |
| |
| New in public-inbox 2.0.0 (PENDING). |
| |
| =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<manifest.js.gz>, regardless of domain. |
| Only use this if you're serving HTTP requests in a domain-agnostic manner. |
| |
| =item * 404 |
| - C<manifest.js.gz> 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<match=domain> |
| |
| =item publicinbox.<name>.obfuscate |
| |
| Whether to obfuscate email addresses in the L<PublicInbox::WWW> HTML |
| interface. |
| |
| Default: false |
| |
| =item publicinbox.noObfuscate |
| |
| A space-delimited list of well-known addresses and domains that should |
| not be obfuscated when C<publicinbox.$NAME.obfuscate> is true (e.g., |
| C<public@example.com> and C<@example.com>). This may be specified |
| more than once, in which case the values are merged. |
| |
| Default: none |
| |
| =item extindex.<name>.topdir |
| |
| The directory of an external index. See |
| L<public-inbox-extindex(1)> for more details. |
| |
| =item extindex.<name>.url |
| |
| Identical to L</publicinbox.E<lt>nameE<gt>.url>, but for |
| external indices |
| |
| =item extindex.<name>.coderepo |
| |
| Identical to L</publicinbox.E<lt>nameE<gt>.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) |
| |
| Named limiters are useful for preventing large inboxes from |
| monopolizing (or overloading) the server. Since serving git |
| clones (via L<git-http-backend(1)> can be memory-intensive for |
| large inboxes, it makes sense to put large inboxes on a named |
| limiter with a low max value; while smaller inboxes can use |
| the default limiter. |
| |
| C<RLIMIT_*> keys may be set to enforce resource limits for |
| a particular limiter (L<BSD::Resource(3pm)> is required). |
| |
| Default named-limiters are prefixed with "-". Currently, |
| the "-cgit" named limiter is reserved for instances spawning |
| cgit via C<publicinbox.cgitrc> |
| |
| =over 8 |
| |
| =item publicinboxlimiter.<name>.max |
| |
| The maximum number of parallel processes for the given limiter. |
| |
| =item publicinboxlimiter.<name>.rlimitCore |
| |
| =item publicinboxlimiter.<name>.rlimitCPU |
| |
| =item publicinboxlimiter.<name>.rlimitData |
| |
| The maximum core size, CPU time, or data size processes run with the |
| given limiter will use. This may be comma-separated to distinguish |
| soft and hard limits. The word "INFINITY" is accepted as the |
| RLIM_INFINITY constant (if supported by your OS). |
| |
| See L<setrlimit(2)> for more info on the behavior of RLIMIT_CORE, |
| RLIMIT_CPU, and RLIMIT_DATA for you operating system. |
| |
| =back |
| |
| =head3 EXAMPLE WITH NAMED LIMITERS |
| |
| ; big inboxes which require lots of memory to clone: |
| [publicinbox "big1"] |
| inboxdir = /path/to/big1 |
| address = big1@example.com |
| httpbackendmax = big |
| [publicinbox "big2"] |
| inboxdir = /path/to/big2 |
| address = big2@example.com |
| httpbackendmax = big |
| |
| ; tiny inboxes which are easily cloned: |
| [publicinbox "tiny1"] |
| inboxdir = /path/to/tiny1 |
| address = tiny1@example.com |
| [publicinbox "tiny2"] |
| inboxdir = /path/to/tiny2 |
| address = tiny2@example.com |
| |
| [publicinboxlimiter "big"] |
| max = 4 |
| |
| In the above example, the "big1" and "big2" are limited to four |
| parallel L<git-http-backend(1)> processes between them. |
| |
| However, "tiny1" and "tiny2" will share the default limiter |
| which means there can be 32 L<git-http-backend(1)> processes |
| between them. |
| |
| =head1 ENVIRONMENT |
| |
| =over 8 |
| |
| =item PI_CONFIG |
| |
| Used to override the default "~/.public-inbox/config" value. |
| |
| =back |
| |
| =head1 CONTACT |
| |
| Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org> |
| |
| The mail archives are hosted at L<https://public-inbox.org/meta/> and |
| L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/> |
| |
| =head1 COPYRIGHT |
| |
| Copyright all contributors L<mailto:meta@public-inbox.org> |
| |
| License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt> |
| |
| =head1 SEE ALSO |
| |
| L<git(1)>, L<git-config(1)>, L<public-inbox-daemon(8)>, |
| L<public-inbox-mda(1)>, L<public-inbox-watch(1)>, |
| L<grokmirror|https://git.kernel.org/pub/scm/utils/grokmirror/grokmirror.git> |
