PUBLIC-INBOX-CONFIG(5) public-inbox user manual PUBLIC-INBOX-CONFIG(5)
NAME
public-inbox-config - public-inbox config file description
SYNOPSIS
~/.public-inbox/config
DESCRIPTION
The public-inbox config file is parseable by git-config(1). This is a
global configuration file for mapping/discovering all public-inboxes
used by a particular user.
CONFIGURATION FILE
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
VARIABLES
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
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.
Absolute pathnames longer than 244 bytes cannot be indexed with
public-inbox-extindex(1)
Default: none, required
publicinbox.<name>.url
The primary URL for hosting the HTTP/HTTPS archives.
Additional HTTP/HTTPS URLs may be specified via
"$GIT_DIR/cloneurl" as documented in gitweb(1)
Default: none, optional
publicinbox.<name>.newsgroup
The NNTP group name for use with public-inbox-nntpd(1). This
may be any newsgroup name with hierarchies delimited by ".".
For example, the newsgroup for <mailto:meta@public-inbox.org>
is: "inbox.comp.mail.public-inbox.meta"
It also configures the folder hierarchy used by
public-inbox-imapd(1) as well as public-inbox-pop3d(1)
Omitting this for a given inbox will prevent the inbox from
being served by public-inbox-nntpd(1), public-inbox-imapd(1),
and/or public-inbox-pop3d(1)
Newsgroup names should be all lowercase and have a maximum
length of 244 bytes. Uppercase characters are converted to
lowercase for compatibility with IMAP, POP3, and our
public-inbox-extindex(1) and public-inbox-cindex(1) tools
starting with public-inbox 2.0+ (they were unusable before).
Default: none, optional
publicinbox.<name>.watch
See public-inbox-watch(1)
publicinbox.<name>.watchheader
See public-inbox-watch(1)
publicinbox.<name>.listid
The rfc2919 <https://tools.ietf.org/html/rfc2919> header
without angle brackets for public-inbox-mda(1) deliveries and
public-inbox-watch(1).
For public-inbox-watch users, this is a shortcut for specifying
"publicinbox.$NAME.watchheader=List-Id:<foo.example.com>"
For public-inbox-mda users, this may be used to avoid recipient
matching via "ORIGINAL_RECIPIENT" environment variable.
This may be specified multiple times for merging multiple
mailing lists into a single public-inbox, only one "List-Id"
header needs to match.
Default: none
publicinbox.<name>.imapmirror
This may be the full IMAP URL of an independently-run IMAP
mirror.
Default: none
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
"nntp://news.gmane.io/gmane.mail.public-inbox.general"
Default: none
publicinbox.<name>.indexlevel
The indexing level for public-inbox-index(1)
"basic" only requires DBD::SQLite(3pm) and provides all NNTP
functionality along with thread-awareness in the WWW interface.
"medium" requires Xapian(3pm) or Search::Xapian(3pm) to provide
full-text term search functionality in the WWW UI.
"full" also includes positional information used by Xapian to
allow for searching for phrases using quoted text. (e.g.
"looking for a complete sentence")
Default: "full"
publicinbox.<name>.boost
Control indexing order for 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: 0
publicinbox.<name>.indexSequentialShard
See "publicInbox.indexSequentialShard" in public-inbox-index(1)
publicinbox.<name>.httpbackendmax
If a digit, the maximum number of parallel 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 "NAMED LIMITER"
which can be shared by multiple inboxes.
Default: 32 (using a default limiter shared by all inboxes)
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.
Unnecessary with "--join" in public-inbox-cindex(1)
Default: none
publicinbox.<name>.altid
Index by an alternative ID mechanism as a Xapian search prefix
e.g. "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
"serial:$USER_PREFIX:file=$SQLITE_FILENAME" where $USER_PREFIX
is a lowercase prefix like "gmane" for search queries, and
$SQLITE_FILENAME points to an SQLite DB. $SQLITE_FILENAME may
be an absolute path or a path relative to "INBOXDIR" for v2
inboxes or "INBOXDIR/public-inbox" for v1 inboxes.
The schema of $SQLITE_FILENAME should be the same as for
"msgmap.sqlite3". See "scripts/xhdr-num2mid" in the public-
inbox source tree for an example of how to generate such a
mapping via NNTP.
This is a noop with "indexlevel=basic"
Default: none
publicinbox.<name>.indexheader
Supports indexing of arbitrary mail headers in Xapian.
It must be specified in the form of
"$TYPE:$USER_PREFIX:$MAIL_HEADER:$PARAMS" where $TYPE
determines how it's indexed and queried; $USER_PREFIX is a
lowercase prefix for search queries, $MAIL_HEADER is the header
to index (e.g. "X-Label"), $PARAMS is a URL-style query string
for optional parameters.
Valid $TYPE values (in ascending order of storage cost) are as
follows:
* "boolean_term" - index for simple filtering (not sortable by
relevance)
* "text" - add frequency information to allow sorting by
relevance
* "phrase" - add positional information to match sentences or
phrases
In other words: "phrase" forces indexing of a particular header
to behave like it used "indexlevel=full"; while "text" indexes
as if that header used "indexlevel=medium".
Valid keys in $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 "indexlevel=basic"
New in public-inbox 2.0+
Default: none
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
publicinbox.css
The local path name of a CSS file for the PSGI web interface.
Space-separated attributes ("key=val" or "key='val with
spaces'") may be specified after the path on the same line;
"media", "title" and "href" are currently supported, and match
the associated attributes of the HTML "<style>" tag.
"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 "load" attribute with values
"link" or "import"; "link" forces the use of a "<link>" tag and
disables inlining CSS into the "<style>" tag while "import"
puts CSS @import statements into the "<style>" tag. "import"
appears necessary for some browser and "media" query
combinations.
Multiple files may be specified and will be included in the
given order, but files specified via "load=import" are always
handled first.
Example:
[publicinbox]
css = /path/to/216dark.css title=216dark \
media='screen,(prefers-color-scheme:dark)'
See the contrib/css directory of the public-inbox source
<https://80x24.org/public-inbox.git/tree/contrib/css> for more
examples.
publicinboxImport.dropUniqueUnsubscribe
Drop "List-Unsubscribe" headers if the message also includes
the "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 "List-Unsubscribe*"
headers are signed, but breaking DKIM signatures is the lesser
evil compared to allowing any reader to unsubscribe the
archivist.
This affects public-inbox-mda(1), public-inbox-watch(1), and
public-inbox-learn(1)
publicinboxmda.spamcheck
This may be set to "none" to disable the use of SpamAssassin
spamc(1) for filtering spam before it is imported into git
history. Other spam filtering backends may be supported in the
future.
Default: spamc
publicinboxwatch.spamcheck
See public-inbox-watch(1)
publicinboxwatch.watchspam
See public-inbox-watch(1)
publicinbox.imapserver
Set this to point to the hostname(s) of the
public-inbox-imapd(1) instance. This is used to advertise the
existence of the IMAP endpoint in the PublicInbox::WWW HTML
interface.
Default: none
publicinbox.nntpserver
Same as "publicinbox.imapserver", but for the hostname(s) of
the public-inbox-nntpd(1) instance. This affects "Xref:"
headers in responses. As of public-inbox 2.0, this can be
overridden on the "public-inbox-netd(1)" command-line via
"--listen nntp://$ADDRESS:$PORT/?servername=example.com"
Default: none
publicinbox.pop3server
Same as "publicinbox.imapserver", but for the hostname(s) of
the public-inbox-pop3d(1) instance.
Default: none
publicinbox.pop3state
See "publicinbox.pop3state" in public-inbox-pop3d(1)
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
publicinbox.<name>.hide
A comma-delimited list of listings to hide the inbox from.
Valid values are currently "www" and "manifest" for non-404
values of "publicinbox.wwwListing" and
"publicinbox.grokManifest", respectively
Default: none
cindex.$NAME.topdir
cindex.$NAME.localprefix
See public-inbox-cindex(1)
coderepo.<nick>.dir
The path to a git repository for "publicinbox.<name>.coderepo"
Absolute pathnames longer than 244 bytes cannot be indexed with
public-inbox-cindex(1)
Unnecessary with "--join" in public-inbox-cindex(1)
coderepo.<nick>.cgitUrl
The URL of the cgit instance associated with the coderepo.
Unnecessary with "--join" in public-inbox-cindex(1)
Default: none
coderepo.snapshots
See "snapshots" in cgitrc(5)
publicinbox.cgitrc
A path to a 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. $HTTP_HOST) is not yet supported.
publicinbox.cgitbin
A path to the "cgit.cgi" executable. The 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
publicinbox.cgitdata
A path to the data directory used by cgit for storing static
files. Typically guessed based on the location of "cgit.cgi"
(from "publicinbox.cgitbin"), but may be overridden.
Default: dirname of "publicinbox.cgitbin",
/var/www/htdocs/cgit/ or /usr/share/cgit/
publicinbox.cgit
Controls whether or not and how "cgit" is used for serving
coderepos. New in public-inbox 2.0+.
• first
Try using "cgit" as the first choice, this is the
default.
• fallback
Fall back to using "cgit" only if our native, inbox-
aware git code repository viewer doesn't recognize the
URL.
Default: "first" ("cgit" will be used iff "publicinbox.cgitrc"
is set and the "cgit" binary exists).
publicinbox.mailEditor
See public-inbox-edit(1)
publicinbox.indexMaxSize
publicinbox.indexBatchSize
publicinbox.indexSequentialShard
See public-inbox-index(1)
publicinbox.wwwlisting
Enable a HTML listing style when the root path of the URL '/'
is accessed. Valid values are:
• all - Show all inboxes
• 404 - Return a 404 page. This is useful to allow
customization with Plack::App::Cascade(3pm)
• match=domain - Only show inboxes with URLs which belong
to the domain of the HTTP request
Default: 404
publicinbox.nameIsUrl
Treat the name of the public inbox as its unqualified URL when
using "publicInbox.wwwListing=all". That is, every
"[publicinbox "foo"]" section implicitly sets
"publicinbox.foo.url=foo".
This is a convenient alternative to specifying
"publicinbox.<name>.url" for every single inbox if your inbox
URLs are domain-agnostic when using
"publicInbox.wwwListing=all"
Default: false
New in public-inbox 2.0+
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:
• 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.
• all - All inboxes are present in "manifest.js.gz",
regardless of domain. Only use this if you're serving
HTTP requests in a domain-agnostic manner.
• 404 - "manifest.js.gz" will only contain an empty JSON
array. This does NOT affect
"$INBOX_URL/manifest.js.gz", which will always contain
all git repos used by the inbox at $INBOX_URL
Default: "match=domain"
publicinbox.<name>.obfuscate
Whether to obfuscate email addresses in the PublicInbox::WWW
HTML interface.
Default: false
publicinbox.noObfuscate
A space-delimited list of well-known addresses and domains that
should not be obfuscated when "publicinbox.$NAME.obfuscate" is
true (e.g., "public@example.com" and "@example.com"). This may
be specified more than once, in which case the values are
merged.
Default: none
extindex.<name>.topdir
The directory of an external index. See
public-inbox-extindex(1) for more details.
extindex.<name>.url
Identical to "publicinbox.<name>.url", but for external indices
extindex.<name>.coderepo
Identical to "publicinbox.<name>.coderepo", but for external
indices. Code repos may be freely associated with any number
of public inboxes and external indices.
Unnecessary with "--join" in public-inbox-cindex(1)
NAMED LIMITER (PSGI)
Named limiters are useful for preventing large inboxes from
monopolizing (or overloading) the server. Since serving git clones
(via 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.
"RLIMIT_*" keys may be set to enforce resource limits for a particular
limiter (BSD::Resource(3pm) is required).
Default named-limiters are prefixed with "-". Currently, the "-cgit"
named limiter is reserved for instances spawning cgit via
"publicinbox.cgitrc". The "-httpbackend" named limiter (in public-
inbox 2.0+) governs all git-http-backend(1) processes for inboxes and
coderepos for a given public-inbox config file. The "-codeblob"
limiter (in 2.0+) governs the entire series of git commands used for
blob reconstruction from patches.
publicinboxlimiter.<name>.max
The maximum number of parallel processes for the given limiter.
Default: 32 for "-httpbackend", 1 for everything else
publicinboxlimiter.<name>.depth
The maximum queue depth for the given limiter. HTTP 503 errors
will be returned when the queue depth is exceeded.
Default: 32
New in public-inbox 2.0+
publicinboxlimiter.<name>.rlimitCore
publicinboxlimiter.<name>.rlimitCPU
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 setrlimit(2) for more info on the behavior of RLIMIT_CORE,
RLIMIT_CPU, and RLIMIT_DATA for you operating system.
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 git-http-backend(1) processes between them.
However, "tiny1" and "tiny2" will share the default limiter which means
there can be 32 git-http-backend(1) processes between them.
ENVIRONMENT
PI_CONFIG
Used to override the default "~/.public-inbox/config" value.
CONTACT
Feedback welcome via plain-text mail to <mailto:meta@public-inbox.org>
The mail archives are hosted at <https://public-inbox.org/meta/> and
<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
COPYRIGHT
Copyright all contributors <mailto:meta@public-inbox.org>
License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
SEE ALSO
git(1), git-config(1), public-inbox-daemon(8), public-inbox-mda(1),
public-inbox-watch(1), grokmirror
<https://git.kernel.org/pub/scm/utils/grokmirror/grokmirror.git>
public-inbox.git 1993-10-02 PUBLIC-INBOX-CONFIG(5)