mdw@git.distorted.org.uk Git - ezmlm/blob - ezmlm.5

   1 .TH ezmlm 5
   2 .SH NAME
   3 ezmlm \- format of ezmlm directory
   4 .SH OVERVIEW
   5 An
   6 .B ezmlm
   7 directory,
   8 .IR dir ,
   9 stores information about an
  10 .B ezmlm
  11 mailing list.
  12 .B ezmlm-make
  13 creates
  14 .IR dir ;
  15 .B ezmlm-sub
  16 and
  17 .B ezmlm-unsub
  18 manipulate the subscriber list stored under
  19 .IR dir ;
  20 .B ezmlm-manage
  21 handles administrative requests automatically;
  22 .B ezmlm-send
  23 sends a message to all subscribers listed in
  24 .IR dir .
  25 .SH SUBSCRIBERS
  26 .I dir\fB/subscribers
  27 is a directory containing the subscriber list.
  28 .B ezmlm-manage
  29 allows automatic subscription if
  30 .I dir\fB/public
  31 exists.
  32
  33 The list is hashed into 53 files, named
  34 .B @
  35 through
  36 .B t
  37 in ASCII.
  38 A nonexistent file is treated as an empty file.
  39
  40 Each file contains a series of addresses.
  41 An address can be any string of non-NUL characters up to 400 bytes long.
  42 Each address is preceded by the letter T and followed by a NUL.
  43
  44 For reliability,
  45 when an address is added to or removed from the mailing list,
  46 the relevant file is recreated under a temporary name
  47 inside
  48 .I dir\fB/subscribers
  49 and then moved into place.
  50
  51 .I dir\fB/key
  52 is a binary file.
  53 .B ezmlm-manage
  54 uses
  55 .I dir\fB/key
  56 to create confirmation numbers.
  57 Anyone who can guess the contents of
  58 .I dir\fB/key
  59 can forge subscription requests.
  60 .B ezmlm-make
  61 does not put much effort into making
  62 .I dir\fB/key
  63 difficult to guess;
  64 for better security, you should add some random garbage to
  65 .IR dir\fB/key .
  66 .SH ARCHIVE
  67 .I dir\fB/archive
  68 is a directory containing messages previously sent to subscribers.
  69 .B ezmlm-send
  70 archives all new messages if
  71 .I dir\fB/archived
  72 exists.
  73
  74 Messages sent to the mailing list are numbered from 1 upwards,
  75 whether or not they are archived.
  76 .I dir\fB/num
  77 is the number of messages sent so far.
  78
  79 .I dir\fB/archive
  80 has subdirectories,
  81 each subdirectory storing up to 100 messages.
  82 Message number 100m+n, with n between 0 and 99, is stored in
  83 .IR dir\fB/archive/\fIm\fB/\fIn .
  84 For example, message number 15307 is stored in
  85 .IR dir\fB/archive/153/07 .
  86
  87 .B ezmlm-manage
  88 will ignore message files without the owner-execute bit set.
  89 .B ezmlm-send
  90 turns on the owner-execute bit after safely writing the message to disk.
  91 .SH BOUNCES
  92 .I dir\fB/bounce
  93 is a directory containing bounce messages.
  94 .B ezmlm-return
  95 stores several types of files here.
  96 .SH "DELIVERY INSTRUCTIONS"
  97 .B ezmlm-make
  98 sets up four files to control mailing list deliveries.
  99 Each file is a series of delivery instructions in
 100 .B dot-qmail
 101 format.
 102
 103 .I dir\fB/editor
 104 handles incoming mailing list submissions.
 105 .B ezmlm-make
 106 sets up
 107 .I dir\fB/editor
 108 to invoke
 109 .B ezmlm-send
 110 to immediately forward each message to all subscribers
 111 and then to run
 112 .BR ezmlm-warn .
 113
 114 .I dir\fB/owner
 115 handles incoming messages for the mailing list's owner.
 116 .B ezmlm-make
 117 sets up
 118 .I dir\fB/owner
 119 to store messages in
 120 .I dir\fB/Mailbox
 121 and then to run
 122 .BR ezmlm-warn .
 123
 124 .I dir\fB/bouncer
 125 handles incoming bounce messages.
 126 .B ezmlm-make
 127 sets up
 128 .I dir\fB/bouncer
 129 to invoke
 130 .B ezmlm-return
 131 and then
 132 .BR ezmlm-warn .
 133
 134 .I dir\fB/manager
 135 handles incoming administrative requests.
 136 .B ezmlm-make
 137 sets up
 138 .I dir\fB/manager
 139 to invoke
 140 .B ezmlm-manage
 141 and then
 142 .BR ezmlm-warn .
 143 .SH TEXT
 144 .I dir\fB/text
 145 is a directory
 146 containing files sent out by
 147 .B ezmlm-manage
 148 in response to administrative requests:
 149 .TP 15
 150 .B top
 151 Introducing
 152 .BR ezmlm .
 153 This is placed at the top of each response.
 154 .TP
 155 .B bottom
 156 Explaining how to use
 157 .BR ezmlm .
 158 This is placed at the bottom of each response.
 159 .TP
 160 .B sub-confirm
 161 Explaining how to confirm a subscription request.
 162 .TP
 163 .B sub-ok
 164 Acknowledging successful subscription.
 165 .TP
 166 .B sub-nop
 167 Acknowledging a subscription request for an address already
 168 on the mailing list.
 169 .TP
 170 .B sub-bad
 171 Rejecting a bad subscription confirmation number.
 172 .TP
 173 .B unsub-confirm
 174 Explaining how to confirm an unsubscription request,
 175 and explaining how to figure out the subscription address.
 176 .TP
 177 .B unsub-ok
 178 Acknowledging successful unsubscription.
 179 .TP
 180 .B unsub-nop
 181 Acknowledging an unsubscription request for an address not
 182 on the mailing list.
 183 .TP
 184 .B unsub-bad
 185 Rejecting a bad unsubscription confirmation number.
 186 .TP
 187 .B get-bad
 188 Rejecting a bad archive retrieval request.
 189 .TP
 190 .B bounce-warn
 191 Pointing out that messages have bounced.
 192 .TP
 193 .B bounce-probe
 194 Pointing out that a warning message has bounced.
 195 .TP
 196 .B bounce-num
 197 Explaining that
 198 .B ezmlm-return
 199 has kept a list of bounced message numbers.
 200 .TP
 201 .B bounce-bottom
 202 Separating the bounce message.
 203 .PP
 204 .B ezmlm-manage
 205 replaces the line
 206 .B !A
 207 in any of these files
 208 with the name of the subscription address.
 209 It replaces the line
 210 .B !R
 211 in
 212 .B sub-confirm
 213 and
 214 .B unsub-confirm
 215 with the address that the subscriber must reply to.
 216 .SH "OUTGOING MESSAGE EDITING"
 217 .I dir\fB/headerremove
 218 is a list of bad header field names,
 219 one per line.
 220 .B ezmlm-send
 221 removes these header fields from all outgoing messages.
 222 .B ezmlm-make
 223 sets up
 224 .I dir\fB/headerremove
 225 to remove
 226 .BR Return-Path ,
 227 .BR Return-Receipt-To ,
 228 and
 229 .B Return-Path
 230 fields.
 231
 232 .I dir\fB/headeradd
 233 is a list of new header fields.
 234 .B ezmlm-send
 235 adds these fields to every outgoing message.
 236 .B ezmlm-make
 237 sets up
 238 .I dir\fB/headeradd
 239 with no new fields.
 240 .SH MISCELLANY
 241 The first line of
 242 .I dir\fB/mailinglist
 243 is a line of text.
 244 .B ezmlm-send
 245 creates a new
 246 .B Mailing-List
 247 field, showing the contents of
 248 .IR dir\fB/mailinglist ,
 249 in every outgoing message.
 250
 251 The first lines of
 252 .I dir\fB/outlocal
 253 and
 254 .I dir\fB/outhost
 255 give the outgoing name of the mailing list.
 256 These are used by
 257 .B ezmlm-manage
 258 and
 259 .B ezmlm-send
 260 to construct sender addresses for outgoing messages.
 261
 262 The first lines of
 263 .I dir\fB/inlocal
 264 and
 265 .I dir\fB/inhost
 266 give the incoming name of the mailing list.
 267 These are used by
 268 .B ezmlm-manage
 269 to parse incoming envelopes.
 270 Normally
 271 .I inlocal
 272 and
 273 .I inhost
 274 are the same as
 275 .I outlocal
 276 and
 277 .IR outhost ,
 278 but sometimes they are different,
 279 with
 280 .I outlocal\fB@\fIouthost
 281 forwarded to
 282 .IR inlocal\fB@\fIinhost .
 283
 284 If
 285 .I dir\fB/sublist
 286 exists,
 287 this mailing list is a sublist,
 288 redistributing messages from a parent mailing list.
 289 The first line of
 290 .I dir\fB/sublist
 291 is the name of the parent list.
 292 This affects the behavior of
 293 .BR ezmlm-send .
 294
 295 .I dir\fB/lock
 296 is an empty file.
 297 Any program that reads or writes the subscriber list,
 298 or adds messages to the archive,
 299 locks
 300 .IR dir\fB/lock .
 301
 302 .I dir\fB/Log
 303 is an advisory log of subscription and unsubscription actions.
 304 .B WARNING:
 305 .B Log
 306 is not protected against system crashes.
 307 Log entries may be missing or corrupted if the system goes down.
 308 .SH "SEE ALSO"
 309 ezmlm-list(1),
 310 ezmlm-make(1),
 311 ezmlm-manage(1),
 312 ezmlm-return(1),
 313 ezmlm-send(1),
 314 ezmlm-sub(1),
 315 ezmlm-unsub(1),
 316 ezmlm-warn(1),
 317 dot-qmail(5)