Documentation/ssoma_repository.pod

   1 % ssoma_repository(5) ssoma user manual
   2
   3 =head1 NAME
   4
   5 ssoma_repository - repository and tree description for 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 CONFLICTS
  35
  36 Message-ID is a unique-enough identifier for practical purposes, but
  37 they may still conflict (especially in case of malicious clients and
  38 timing issues).  In the case of identical Message-ID and different
  39 messages, the blob shall become a tree with multiple messages.
  40 Likewise, if there is a (rare) SHA-1 conflict on different Message-ID
  41 headers, the tree will contain each message (with different Message-ID
  42 headers).
  43
  44 Thus the blobs for conflicting Message-IDs will be the SHA-1 hexdigest
  45 of the Subject header and raw body (no extra whitespace delimiting the
  46 two).
  47
  48   PFX=21/4527ce3741f50bb9afa65e7c5003c8a8ddc4b1
  49
  50   $PFX/287d8b67bf8ebdb30e34cb4ca9995dbd465f37aa # first copy
  51   $PFX/287d8b67bf8ebdb30e34cb4ca9995dbd465f37ab # second copy
  52   $PFX/287d8b67bf8ebdb30e34cb4ca9995dbd465f37ac # third copy
  53
  54 Note: public-inbox currently uses "ssoma-mda -1" to disable this
  55 conflict resolution feature.  This simplifies the implementation
  56 and use of public-inbox.
  57
  58 =head1 HEADERS
  59
  60 The Message-ID (case-insensitive) header is required.
  61 "Bytes", "Lines" and "Content-Length" headers are stripped and not
  62 allowed, they can interfere with further processing.
  63 When using ssoma with public-inbox-mda, the "Status" mbox header
  64 is also stripped as that header makes no sense in a public archive.
  65
  66 =head1 LOCKING
  67
  68 L<flock(2)> locking exclusively locks the empty $GIT_DIR/ssoma.lock file
  69 for all non-atomic operations.
  70
  71 =head1 EXAMPLE INPUT FLOW (SERVER-SIDE MDA)
  72
  73 1. Message is delivered to a mail transport agent (MTA)
  74
  75 1a. (optional) reject/discard spam, this should run before ssoma-lda
  76
  77 1b. (optional) reject/strip unwanted attachments
  78
  79 ssoma-mda handles all steps once invoked.
  80
  81 2. Mail transport agent invokes ssoma-mda
  82
  83 3. reads message via stdin, extracting Message-ID
  84
  85 4. acquires exclusive flock lock on $GIT_DIR/ssoma.lock
  86
  87 5. creates or updates the blob of associated 2/38 SHA-1 path
  88
  89 6. updates the index and commits
  90
  91 7. releases $GIT_DIR/ssoma.lock
  92
  93 ssoma-mda can also be used as an L<inotify(7)> trigger to monitor maildirs,
  94 and the ability to monitor IMAP mailboxes using IDLE will be available
  95 in the future.
  96
  97 =head1 GIT REPOSITORIES (SERVERS)
  98
  99 ssoma uses bare git repositories on both servers and clients.
 100
 101 Using the L<git-init(1)> command with --bare is the recommend method
 102 of creating a git repository on a server:
 103
 104         git init --bare /path/to/wherever/you/want.git
 105
 106 There are no standardized paths for servers, administrators make
 107 all the choices regarding git repository locations.
 108
 109 Special files in $GIT_DIR on the server:
 110
 111 =over
 112
 113 =item $GIT_DIR/ssoma.index
 114
 115 A git index file used for MDA updates.
 116 The normal git index (in $GIT_DIR/index) is not used at all as
 117 there is typically no working tree.
 118
 119 =item $GIT_DIR/ssoma.lock
 120
 121 An empty file for L<flock(2)> locking.
 122 This is necessary to ensure the index and commits are updated
 123 consistently and multiple processes running MDA do not step on
 124 each other.
 125
 126 =back
 127
 128 =head1 GIT REPOSITORIES (CLIENTS)
 129
 130 ssoma uses bare git repositories for clients (as well as servers).
 131
 132 The default is to use GIT_DIR=~/.ssoma/$LISTNAME.git in the user's home
 133 directory.  This is a bare git repository with two additional files:
 134
 135 =over
 136
 137 =item $GIT_DIR/ssoma.lock
 138
 139 empty lock file, same as used by L<ssoma-mda(1)>
 140
 141 =item $GIT_DIR/ssoma.state
 142
 143 a L<git-config(1)> format file used by L<ssoma(1)>
 144
 145 =back
 146
 147 Each client $GIT_DIR may have multiple mbox/maildir/command targets.
 148 It is possible for a client to extract the mail stored in the git
 149 repository to multiple mboxes for compatibility with a variety of
 150 different tools.
 151
 152 =head1 $GIT_DIR/ssoma.state format
 153
 154   ; "local" is the default name (analogous to "origin" with remotes)
 155   [target "local"]
 156     path = /path/to/mbox
 157
 158     ; this tells ssoma where to start the next import from
 159     ; this means ssoma will not redundantly import old
 160     ; messages and the user is free to move/delete old
 161     ; messages from the mbox.
 162     last-imported = 33eaf25f43fd73d8f4f7b0a066b689809d733191
 163
 164   ; "alt" is a user-defined name, in case a user wants to output
 165   ; the repo in several formats
 166   [target "alt"]
 167     ; note the trailing '/' to denote the maildir path,
 168     ; the Email::LocalDelivery Perl module depends on this
 169     ; trailing slash to identify it as a maildir
 170     path = /path/to/maildir/
 171     last-imported = 950815b313a4e616c6fe39f46b2e894b51d7d62f
 172
 173   ; users may also choose to pipe to an arbitrary command of their
 174   ; choice, this filter may behave like an MDA (and implement
 175   ; filtering).  Tools like procmail(1)/maildrop(1) may be
 176   ; invoked here.
 177   [target "script"]
 178     command = /path/to/executable/which/reads-mail-from-stdin
 179     last-imported = 950815b313a4e616c6fe39f46b2e894b51d7d62f
 180
 181 =head1 EXAMPLE OUTPUT FLOW (CLIENT)
 182
 183 1. clone or fetches to bare git repo (GIT_DIR=~/.ssoma/$LISTNAME.git)
 184
 185 2. checks for last-imported commit in ~/.ssoma/$LISTNAME.git/ssoma.state
 186
 187 3. diffs last-imported commit with current HEAD
 188
 189 4. imports new emails to mbox/maildir since last-imported up to current HEAD
 190
 191 5. updates last-imported commit
 192
 193 =head1 CAVEATS
 194
 195 It is NOT recommended to check out the working directory of a git.
 196 there may be many files.
 197
 198 It is impossible to completely expunge messages, even spam, as git
 199 retains full history.  Projects may (with adequate notice) cycle to new
 200 repositories/branches with history cleaned up via L<git-filter-branch(1)>.
 201 This is up to the administrators.
 202
 203 =head1 COPYRIGHT
 204
 205 Copyright 2013-2016 all contributors L<mailto:meta@public-inbox.org>
 206
 207 License: AGPL-3.0+ L<http://www.gnu.org/licenses/agpl-3.0.txt>
 208
 209 =head1 SEE ALSO
 210
 211 L<gitrepository-layout(5)>, L<ssoma(1)>