| =head1 NAME |
| |
| public-inbox-init - create or reinitialize a public-inbox |
| |
| =head1 SYNOPSIS |
| |
| B<public-inbox-init> [OPTIONS] NAME INBOX_DIR HTTP_URL ADDRESS [ADDRESS..] |
| |
| =head1 DESCRIPTION |
| |
| Creates an empty public-inbox or reinitializes an existing one. |
| It updates C<~/.public-inbox/config> by creating a |
| C<[publicinbox "NAME"]> section where |
| C<publicinbox.NAME.inboxdir> is C<INBOX_DIR>, |
| C<publicinbox.NAME.url> is C<HTTP_URL>, and |
| C<publicinbox.NAME.address> is C<ADDRESS>. Multiple addresses |
| may be specified for inboxes with multiple addresses. |
| |
| =head1 OPTIONS |
| |
| =over |
| |
| =item -V FORMAT_VERSION |
| |
| =item --version FORMAT_VERSION |
| |
| Specify C<2> here to use the scalable L<public-inbox-v2-format(5)> |
| if you have L<DBD::SQLite> installed. |
| |
| The default is C<1> for the old L<public-inbox-v1-format(5)>, |
| but C<2> is strongly recommended for scalability if you have |
| L<DBD::SQLite>. |
| |
| Default: C<1> |
| |
| =item -L <basic|medium|full> |
| |
| =item --indexlevel <basic|medium|full> |
| |
| Controls the indexing level for L<public-inbox-index(1)> |
| |
| See L<public-inbox-config(5)> for more information. |
| |
| Default: C<full> |
| |
| =item --ng NEWSGROUP |
| |
| =item --newsgroup NEWSGROUP |
| |
| The NNTP group name for use with L<public-inbox-nntpd(8)>. 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> |
| |
| This may be set after-the-fact via C<publicinbox.$NAME.newsgroup> |
| in the configuration file. See L<public-inbox-config(5)> for more |
| info. |
| |
| Available in public-inbox 1.6.0+. |
| |
| Default: none. |
| |
| =item -c KEY=VALUE |
| |
| Allow setting arbitrary configs as C<publicinbox.$NAME.$KEY>. |
| This is idempotent for the same C<VALUE>, but allows setting |
| multiple values for keys such as C<publicinbox.$NAME.url> and |
| C<publicinbox.$NAME.watch>. |
| |
| =item --skip-artnum |
| |
| This option allows archivists to publish incomplete archives |
| with only new mail while allowing NNTP article numbers |
| to be reserved for yet-to-be-archived old mail. |
| |
| This is mainly intended for users of C<--skip-epoch> (documented below) |
| but may be of use to L<public-inbox-v1-format(5)> users. |
| |
| There is no automatic way to use reserved NNTP article numbers |
| when old mail is found, yet. |
| |
| Available in public-inbox 1.6.0+. |
| |
| Default: unset, no NNTP article numbers are skipped |
| |
| =item -S |
| |
| =item --skip-epoch |
| |
| For C<-V2> (L<public-inbox-v2-format(5)>) inboxes only, this option |
| allows archivists to publish incomplete archives with newer |
| mail while allowing "0.git" (or "1.git" and so on) epochs to be |
| added-after-the-fact (without affecting "git clone" followers). |
| |
| Available since public-inbox 1.2.0. |
| |
| Default: unset, no epochs are skipped |
| |
| =item -j JOBS |
| |
| =item --jobs=JOBS |
| |
| Control the number of Xapian index shards in a |
| C<-V2> (L<public-inbox-v2-format(5)>) inbox. |
| |
| It can be useful to use a single shard (C<-j1>) for inboxes on |
| high-latency storage (e.g. rotational HDD) unless the system has |
| enough RAM to cache 5-10x the size of the git repository. |
| |
| Another approach for HDDs is to use the |
| L<public-inbox-index(1)/publicInbox.indexSequentialShard> option |
| and many shards, so each shard may fit into the kernel page |
| cache. Unfortunately, excessive shards slows down read-only |
| query performance. |
| |
| For fast storage, it is generally not useful to specify higher |
| values than the default due to the top-level producer process |
| being a bottleneck. |
| |
| Default: the number of online CPUs, up to 4 (3 shard workers, 1 producer) |
| |
| =item --skip-docdata |
| |
| Do not store document data in Xapian, reducing Xapian storage |
| overhead by around 1.5%. |
| |
| Warning: this option prevents rollbacks to public-inbox 1.5.0 |
| and earlier. |
| |
| Available in public-inbox 1.6.0+. |
| |
| =back |
| |
| =head1 ENVIRONMENT |
| |
| =over 8 |
| |
| =item PI_CONFIG |
| |
| Used to override the default C<~/.public-inbox/config> value. |
| |
| =back |
| |
| =head1 LIMITATIONS |
| |
| Some of the options documented in L<public-inbox-config(5)> |
| require editing the config file. Old versions lack the |
| C<--ng>/C<--newsgroup> parameter |
| |
| See L<public-inbox-config(5)> for all the options which may be applied |
| to a given inbox. |
| |
| =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 2019-2021 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-init(1)>, L<git-config(1)>, L<public-inbox-v1-format(5)>, |
| L<public-inbox-v2-format(5)> |
