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

   1 .de Vb
   2 .ft CW
   3 .nf
   4 .ne \\$1
   5 ..
   6 .de Ve
   7 .ft R
   8
   9 .fi
  10 ..
  11 .TH ezmlm-split 1
  12 .SH NAME
  13 ezmlm-split \- distribute (un)subscribe requests to sublists
  14 .SH SYNOPSIS
  15 .B ezmlm-split
  16 .I dir
  17 [
  18 .B \-dD
  19 ][
  20 .I splitfile
  21 ]
  22 .SH DESCRIPTION
  23 If the action is
  24 .I \-subscribe
  25 or
  26 .IR \-unsubscribe ,
  27 .B ezmlm-split
  28 analyzes the target of the request,
  29  computing a hash in the range 0-52 from
  30 the address, and determines the ``domain key'', i.e.
  31 the two top levels of the host address in reverse order.
  32 Thus, the domain entry for ``d@a.b.c'' becomes ``c.b''
  33 and the one for ``d@a'' becomes ``a''.
  34
  35 The hash and domain parts are then tested against successive lines of
  36 .I splitfile
  37 (default is
  38 .IR dir\fB/split ).
  39 If a match is found, the request is forwarded to the corresponding
  40 sublist, and
  41 .B ezmlm-split
  42 exits 99. If a match is not found or action is not
  43 .I \-subscribe
  44 or
  45 .IR \-unsubscribe ,
  46 .B ezmlm-split
  47 exits 0.
  48
  49 In
  50 .IR splitfile ,
  51 blank lines and lines with ``#'' in position 1 are ignored. Other lines are
  52 expected to be of the format ``dom:low:hi:list@host'', where ``dom'' is
  53 the top level domain, ``low''-``hi'' the range of the hash (defaults 0 and 52),
  54 and ``list@host'' the name of the corresponding list (default is the
  55 local list). A line is considered to match if the address hash is
  56 between ``low'' and ``hi'' inclusive and ``dom'' is empty,
  57 or if the ``domain key'' matches ``dom'' for the full length of ``dom''. Thus,
  58 the address ``user@aol.com'' would match ``com'' and ``aol.com'',
  59 but not ``host.com''.
  60
  61 If the domain
  62 specified is the top level domain up to 3 characters, the split is identical
  63 as that used by the SQL subscriber interface. This is recommended.
  64 There can be several entries for a given sublist.
  65
  66 .B ezmlm-split
  67 can be used also for list with SQL-based sublisting. In this case,
  68 addresses matching the
  69 .I splitfile
  70 are forwarded to the respective non-SQL sublist, and non-matching addresses
  71 are handed by the SQL sublist.
  72
  73 .SH OPTIONS
  74 .TP
  75 .B \-d
  76 (Default.)
  77 Do. Forward requests to the appropriate list.
  78 .TP
  79 .B \-D
  80 Do not process messages. Rather, read addresses, one per line from stdin, and
  81 print ``sublist@host: address'' where ``sublist@host'' is the address to which
  82 the request would have been forwarded in normal operation. This is used to
  83 process a set of existing addresses into a set of address collections, one
  84 per sublist. The output can be sorted and easily processed into a set of files,
  85 one per sublist containing the addresses that sublist handles.
  86 .SH "SPLIT LIST SETUP"
  87 To use a hierarchy of sublists, set up the master list and add a
  88 .B ezmlm-split
  89 line before the
  90 .B ezmlm-manage(1)
  91 line in
  92 .IR dir\fB/manager .
  93 Create any number of sublists of the main list on other local or
  94 distant hosts. Ideally, these should be non-archived, to point to the correct
  95 message numbers of the main list archive (see
  96 .BR ezmlm-send(1) .
  97 You can use
  98 .B ezmlm-make -C\fIezmlmsubrc
  99 for this. If you don't, use the text files from the main list, except
 100 .IR bounce-bottom .
 101 Next, create
 102 .I split
 103 in the main list directory to achieve an appropriate split. Load splitting
 104 between several local hosts is best achieved by hash, with a blank domain.
 105 Geographical splitting with hosts in different countries is best done
 106 via ``domain'' and naturally, a large domain can be subdivided by hash.
 107
 108 Subscribers will receive all messages 'From:' the main list. When they
 109 subscribe or unsubscribe, the request will be forwarded to the appropriate
 110 sublist, which will handle the confirmation. All information, except
 111 .I bounce-bottom
 112 refers the user to the main list. Thus, to the user the list appears as
 113 a single list with the address of the main list, and distribution among
 114 sublists is at the discretion of the administrator of the main list.
 115
 116 .SH "ADDING/REMOVING SUBLISTS"
 117 In general, the main list should be disabled, while changing the sublist
 118 split. This can be done by changing the mode of
 119 .I dir\fB/lock
 120 to 0 or by setting the sticky bit for the home directory of the user
 121 controlling the list.
 122
 123 To remove a sublist, edit the lines for that sublist in the splitfile to
 124 point to another list, and add the existing subscribers of the removed
 125 sublist to the sublist taking the load.
 126 When splitting a sublist into several sublists, create the new sublists,
 127 and edit the split file to distribute the load
 128 between them (usually by hash). Process the subscribers of the old list
 129 with:
 130
 131 .Vb 1
 132  | ezmlm-split -D dir | sort | program
 133 .Ve
 134 where to get one file of addresses per new sublist, ``program'' could be:
 135
 136 .Vb 12
 137 \&#!/usr/bin/perl
 138 \&while (<>) {
 139 \&  ($f,$t) = split (':');
 140 \&  $t =~ s/^\ //;
 141 \&  if ($f ne $of) {
 142 \&    $of = $f;
 143 \&    close(OUT) if ($of);
 144 \&    open(OUT,">$f") or die("Unable to open $f");
 145 \&  }
 146 \&  print OUT $t;
 147 \&}
 148 \&close(OUT) if ($of);
 149 .Ve
 150
 151 Remove all subscribers from the old list,
 152 and add the respective subscribers to each list.
 153
 154 For any more drastic reorganizations, collect all the subscribes of the
 155 affected sublists, create the new subscriber lists, and update the
 156 subscribers of the affected lists.
 157
 158 Reorganizations are easier done when lists use SQL support. By
 159 temporarily using SQL support, reorganizations can be done on running
 160 lists even when normally using
 161 .B ezmlm-split
 162 and local subscriber databases.
 163 .SH "SEE ALSO"
 164 ezmlm-list(1),
 165 ezmlm-make(1),
 166 ezmlm-manage(1),
 167 ezmlm-sub(1)
 168 ezmlm-unsub(1),
 169 ezmlm(5),
 170 ezmlmrc(5),
 171 ezmlmsubrc(5)