Documentation/public-inbox-v1-format.pod

   1 % public-inbox developer manual
   2
   3 =head1 NAME
   4
   5 public-inbox-v1-format - git repository and tree description (aka "ssoma")
   6
   7 =head1 DESCRIPTION
   8
   9 WARNING: this does NOT describe the scalable v2 format used
  10 by public-inbox.  Use of ssoma is not recommended for new
  11 installations due to scalability problems.
  12
  13 ssoma uses a git repository to store each email as a git blob.
  14 The tree filename of the blob is based on the SHA1 hexdigest of
  15 the first Message-ID header.  A commit is made for each message
  16 delivered.  The commit SHA-1 identifier is used by ssoma clients
  17 to track synchronization state.
  18
  19 =head1 PATHNAMES IN TREES
  20
  21 A Message-ID may be extremely long and also contain slashes, so using
  22 them as a path name is challenging.  Instead we use the SHA-1 hexdigest
  23 of the Message-ID (excluding the leading "E<lt>" and trailing "E<gt>")
  24 to generate a path name.  Leading and trailing white space in the
  25 Message-ID header is ignored for hashing.
  26
  27 A message with Message-ID of: E<lt>20131106023245.GA20224@dcvr.yhbt.netE<gt>
  28
  29 Would be stored as: f2/8c6cfd2b0a65f994c3e1be266105413b3d3f63
  30
  31 Thus it is easy to look up the contents of a message matching a given
  32 a Message-ID.
  33
  34 =head1 MESSAGE-ID CONFLICTS
  35
  36 public-inbox v1 repositories currently do not resolve conflicting
  37 Message-IDs or messages with multiple Message-IDs.
  38
  39 =head1 HEADERS
  40
  41 The Message-ID header is required.
  42 "Bytes", "Lines" and "Content-Length" headers are stripped and not
  43 allowed, they can interfere with further processing.
  44 When using ssoma with public-inbox-mda, the "Status" mbox header
  45 is also stripped as that header makes no sense in a public archive.
  46
  47 =head1 LOCKING
  48
  49 L<flock(2)> locking exclusively locks the empty $GIT_DIR/ssoma.lock file
  50 for all non-atomic operations.
  51
  52 =head1 EXAMPLE INPUT FLOW (SERVER-SIDE MDA)
  53
  54 1. Message is delivered to a mail transport agent (MTA)
  55
  56 1a. (optional) reject/discard spam, this should run before ssoma-mda
  57
  58 1b. (optional) reject/strip unwanted attachments
  59
  60 ssoma-mda handles all steps once invoked.
  61
  62 2. Mail transport agent invokes ssoma-mda
  63
  64 3. reads message via stdin, extracting Message-ID
  65
  66 4. acquires exclusive flock lock on $GIT_DIR/ssoma.lock
  67
  68 5. creates or updates the blob of associated 2/38 SHA-1 path
  69
  70 6. updates the index and commits
  71
  72 7. releases $GIT_DIR/ssoma.lock
  73
  74 ssoma-mda can also be used as an L<inotify(7)> trigger to monitor maildirs,
  75 and the ability to monitor IMAP mailboxes using IDLE will be available
  76 in the future.
  77
  78 =head1 GIT REPOSITORIES (SERVERS)
  79
  80 ssoma uses bare git repositories on both servers and clients.
  81
  82 Using the L<git-init(1)> command with --bare is the recommend method
  83 of creating a git repository on a server:
  84
  85         git init --bare /path/to/wherever/you/want.git
  86
  87 There are no standardized paths for servers, administrators make
  88 all the choices regarding git repository locations.
  89
  90 Special files in $GIT_DIR on the server:
  91
  92 =over
  93
  94 =item $GIT_DIR/ssoma.lock
  95
  96 An empty file for L<flock(2)> locking.
  97 This is necessary to ensure the index and commits are updated
  98 consistently and multiple processes running MDA do not step on
  99 each other.
 100
 101 =item $GIT_DIR/public-inbox/msgmap.sqlite3
 102
 103 SQLite3 database maintaining a stable mapping of Message-IDs to NNTP
 104 article numbers.  Used by L<public-inbox-nntpd(1)> and created
 105 and updated by L<public-inbox-index(1)>.
 106
 107 Users of the L<PublicInbox::WWW> interface will find it
 108 useful for attempting recovery from copy-paste truncations of
 109 URLs containing long Message-IDs.
 110
 111 Automatically updated by L<public-inbox-mda(1)>,
 112 L<public-inbox-learn(1)> and L<public-inbox-watch(1)>.
 113
 114 Losing or damaging this file will cause synchronization problems for
 115 NNTP clients.  This file is expected to be stable and require no
 116 updates to its schema.
 117
 118 Requires L<DBD::SQLite>.
 119
 120 =item $GIT_DIR/public-inbox/xapian$N/
 121
 122 Xapian database for search indices in the PSGI web UI.
 123
 124 $N is the value of PublicInbox::Search::SCHEMA_VERSION, and
 125 installations may have parallel versions on disk during upgrades
 126 or to roll-back upgrades.
 127
 128 This is created and updated by L<public-inbox-index(1)>.
 129
 130 Automatically updated by L<public-inbox-mda(1)>,
 131 L<public-inbox-learn(1)> and L<public-inbox-watch(1)>.
 132
 133 This directory can always be regenerated with L<public-inbox-index(1)>.
 134 If lost or damaged, there is no need to back it up unless the
 135 CPU/memory cost of regenerating it outweighs the storage/transfer cost.
 136
 137 Since SCHEMA_VERSION 15 and the development of the v2 format,
 138 the "overview" DB also exists in the xapian directory for v1
 139 repositories.  See L<public-inbox-v2-format(5)/OVERVIEW DB>
 140
 141 Our use of the L</OVERVIEW DB> requires Xapian document IDs to
 142 remain stable.  Using L<public-inbox-compact(1)> and
 143 L<public-inbox-xcpdb(1)> wrappers are recommended over tools
 144 provided by Xapian.
 145
 146 This directory is large, often two to three times the size of
 147 the objects stored in a packed git repository.
 148
 149 =item $GIT_DIR/ssoma.index
 150
 151 This file is no longer used or created by public-inbox, but it is
 152 updated if it exists to remain compatible with ssoma installations.
 153
 154 A git index file used for MDA updates.  The normal git index (in
 155 $GIT_DIR/index) is not used at all as there is typically no working
 156 tree.
 157
 158 =back
 159
 160 Each client $GIT_DIR may have multiple mbox/maildir/command targets.
 161 It is possible for a client to extract the mail stored in the git
 162 repository to multiple mboxes for compatibility with a variety of
 163 different tools.
 164
 165 =head1 CAVEATS
 166
 167 It is NOT recommended to check out the working directory of a git.
 168 there may be many files.
 169
 170 It is impossible to completely expunge messages, even spam, as git
 171 retains full history.  Projects may (with adequate notice) cycle to new
 172 repositories/branches with history cleaned up via L<git-filter-repo(1)>
 173 or L<git-filter-branch(1)>.
 174 This is up to the administrators.
 175
 176 =head1 COPYRIGHT
 177
 178 Copyright 2013-2021 all contributors L<mailto:meta@public-inbox.org>
 179
 180 License: AGPL-3.0+ L<http://www.gnu.org/licenses/agpl-3.0.txt>
 181
 182 =head1 SEE ALSO
 183
 184 L<gitrepository-layout(5)>, L<ssoma(1)>