PUBLIC-INBOX-CONFIG(5)

📦
version 2.0.0~20230714git590023f · 6 versions
, in fedora 43, fedora 44

🌸 PUBLIC-INBOX-CONFIG 🌸

okay bestie, welcome to the public-inbox user manual 💖 this is PUBLIC-INBOX-CONFIG(5) and it's literally the page that explains the config file. grab a snack, we're going in 🫶

✨ NAME ✨

public-inbox-config — the description of the public-inbox config file, periodt 💅

🦋 SYNOPSIS 🦋

~/.public-inbox/config

🌈 DESCRIPTION 🌈

So the public-inbox config file is parseable by git-config(1) — yeah, that's the vibe, it's just git config syntax and it eats it happily ✨

It's a global configuration file for mapping and discovering all the public-inboxes that a particular user is using. That's it, that's the whole job 🎀

💜 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

look at her go 😌 iconic little stanza ngl

👑 VARIABLES 👑

💌 publicinbox.<name>.address

The email address of the public-inbox, fr fr 📬

You can specify this more than once if you're merging multiple mailing lists together (or migrating to new addresses). This one must be specified at least once — the first value given is treated as the primary address, just for informational purposes, iykyk.

Default: none, required 🚨

📁 publicinbox.<name>.inboxdir

The absolute path to the directory that hosts the public-inbox. This must be specified exactly once.

This used to be called mainrepo — that name is still supported, but inboxdir wins if both are there. no cap.

Default: none, required 🚨

🔗 publicinbox.<name>.url

The primary URL for hosting the HTTP/HTTPS archives 💻

You can add extra HTTP/HTTPS URLs 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 can 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) 🧚

Heads up bestie: if you omit this for a given inbox, that inbox won't be served by public-inbox-nntpd(1), public-inbox-imapd(1), and/or public-inbox-pop3d(1). so like. don't forget it 💀

Default: none, optional

👀 publicinbox.<name>.watch

See public-inbox-watch(1) — go read that one, bestie 🫶

🧐 publicinbox.<name>.watchheader

See public-inbox-watch(1) — same deal 💅

🏷️ publicinbox.<name>.listid

The rfc2919 header (that's https://tools.ietf.org/html/rfc2919) without angle brackets, used for public-inbox-mda(1) deliveries and public-inbox-watch(1) 🎀

  • If you're a public-inbox-watch user, this is a shortcut for specifying publicinbox.$NAME.watchheader=List-Id:<foo.example.com>
  • If you're a public-inbox-mda user, you can use this to avoid recipient matching via the ORIGINAL_RECIPIENT environment variable ✨

You may specify this multiple times if you're 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 gives you all the NNTP functionality plus thread-awareness in the WWW interface.
  • "medium" requires Search::Xapian(3pm) to give you full-text term search in the WWW UI.
  • "full" also includes positional information used by Xapian so you can search for phrases using quoted text (e.g. "looking for a complete sentence").

Default: "full" 💖

🚀 publicinbox.<name>.boost

Controls the indexing order for public-inbox-extindex(1), with ties broken by config file order. This only affects indexing — it does not affect messages that are already indexed. so like, retroactive? no. 🙈

Default: 0

🧩 publicinbox.<name>.indexSequentialShard

See "publicInbox.indexSequentialShard" in public-inbox-index(1)

🚦 publicinbox.<name>.httpbackendmax

If it's a digit, that's the max number of parallel git-http-backend(1) processes allowed for cloning this particular inbox 👯

If it's an alphanumeric value starting with a lowercase alphabetic character, the inbox will use a NAMED LIMITER which can be shared by multiple inboxes. cute, right?

Default: 32 (using a default limiter shared by all inboxes)

🧑‍💻 publicinbox.<name>.coderepo

The nickname of a "coderepo" section associated with the inbox. You can specify this 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. that's the good stuff ✨

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. Using ":list" is discouraged for new mailing lists, because it leads to centralization. noted, bestie 🫡

Default: :all

🎨 publicinbox.css

The local path name of a CSS file for the PSGI web interface 💅

It may contain the attributes "media", "title" and "href" which 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. Multiple files may be specified and will be included in the order specified. slay 🌸

🛡️ publicinboxmda.spamcheck

This may be set to "none" to disable the use of SpamAssassin spamc(1) for filtering spam before it's 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 🗞️

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".

Default: none

🗂️ coderepo.<nick>.dir

The path to a git repository for "publicinbox.<name>.coderepo"

🖥️ coderepo.<nick>.cgitUrl

The URL of the cgit instance associated with the coderepo 🔗

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". Using this directive lets admins of existing cgit installations skip declaring coderepo sections and map inboxes directly to code repositories known to cgit. huge W honestly 🏆

Macro expansion (e.g. $HTTP_HOST) is not yet supported. don't try it, bestie 😭

🛠️ 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: basename 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.0 (PENDING).

  • 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.
  • rewrite — Rewrite "cgit" URLs for our native, inbox-aware code repository viewer. This implies "fallback" for URLs the native viewer does not recognize.

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

See public-inbox-index(1)

📦 publicinbox.indexBatchSize

See public-inbox-index(1)

🧩 publicinbox.indexSequentialShard

See public-inbox-index(1)

🏠 publicinbox.wwwlisting

Enables an 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) 🎭

part 1 done, but hold on — more parts are coming bestie, don't go anywhere 💖

  • match=domain — only show inboxes with URLs that belong to the domain of the HTTP request 🎀
  • Default: 404

💫 publicinbox.grokmanifest 💫

This one controls whether we generate a grokmirror-compatible, gzipped JSON file at the top level of the PSGI interface. Real talk: you basically never need to touch this from the default. 🦋

Valid values are:

  • match=domain — only include inboxes with URLs that belong to the domain of the HTTP request. This is compatible with virtual hosting, where several domains all come from the same host. ✨
  • all — every inbox is present in manifest.js.gz, no matter the 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). You can specify this more than once, and in that case the values get merged together. 🫶

  • Default: none

🦋 extindex.<name>.topdir 🦋

The directory of an external index. Peep public-inbox-extindex(1) for more deets. 📖

🌈 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 — no cap, share them everywhere. 💅

🚦 NAMED LIMITER (PSGI) 🚦

Named limiters are the moment when you don't want one giant inbox to monopolize (or straight-up overload) 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 just vibe on the default limiter. 🌸

RLIMIT_* keys may be set to enforce resource limits for a particular limiter (and yes, BSD::Resource(3pm) is required for that). 🧚

Default named-limiters are prefixed with -. Currently, the -cgit named limiter is reserved for instances spawning cgit via publicinbox.cgitrc. 👑

publicinboxlimiter.<name>.max

The maximum number of parallel processes for the given limiter. 🔥

publicinboxlimiter.<name>.rlimitCore

publicinboxlimiter.<name>.rlimitCPU

publicinboxlimiter.<name>.rlimitData

The maximum core size, CPU time, or data size that processes run with the given limiter will use. You can comma-separate these to distinguish soft and hard limits. The word INFINITY is accepted as the RLIM_INFINITY constant (if your OS supports it). ✨

See setrlimit(2) for more info on the behavior of RLIMIT_CORE, RLIMIT_CPU, and RLIMIT_DATA for your 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 example above, 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 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> 🌈

and that's the whole page, bestie — you made it to the end and honestly? iconic behavior. 💅 This one's from public-inbox.git, dated 1993-10-02, and it answers to the name PUBLIC-INBOX-CONFIG(5). Go forth and configure responsibly, no cap. 🎀✨

📦 where this page comes from