Convert the build system over to the use of Automake.
[mmh] / man / mh-alias.man
1 .\"
2 .\" %nmhwarning%
3 .\"
4 .TH MH-ALIAS %manext5% "%nmhdate%" MH.6.8 [%nmhversion%]
5 .SH NAME
6 mh-alias \- alias file for nmh message system
7 .SH SYNOPSIS
8 any
9 .B nmh
10 command
11 .SH DESCRIPTION
12 This describes both
13 .B nmh
14 personal alias files and
15 the global alias file for
16 .B nmh
17 mail delivery, the file
18 .PP
19 .RS 5
20 %etcdir%/MailAliases
21 .RE
22 .PP
23 It does
24 .B not
25 describe aliases files used by the message transport system.
26 Each line of the alias file has the format:
27 .PP
28 .RS 5
29 .I alias
30 .B :
31 .I address\-group
32 .RE
33 or
34 .RS 5
35 .I alias
36 .B ;
37 .I address\-group
38 .RE
39 or
40 .RS 5
41 .B <
42 .I alias\-file
43 .RE
44 or
45 .RS 5
46 .B ;
47 .I comment
48 .RE
49 .PP
50 where:
51 .PP
52 .RS 5
53 .nf
54 .IR address\-group "    := " address\-list
55 .RI "                   |  < " file
56 .RI "                   |  = " UNIX\-group
57 .RI "                   |  + " UNIX\-group
58                         |  *
59
60 .IR address\-list "     := " address
61 .RI "                   |  " address\-list ", " address
62 .fi
63 .RE
64 .PP
65 Continuation lines in alias files end with `\\' followed by the newline
66 character.
67 .PP
68 .RI \*(lq  Alias\-file \*(rq
69 and
70 .RI \*(lq file \*(rq
71 are UNIX file names.
72 .I UNIX\-group
73 is a group name (or number) from
74 .IR /etc/group .
75 An address is a \*(lqsimple\*(rq
76 Internet\-style address.  Througout this file, case is ignored, except
77 for file names.
78 .PP
79 If the line starts with a `<', then the file named after the `<' is
80 read for more alias definitions.  The reading is done recursively, so a
81 `<' may occur in the beginning of an alias file with the expected results.
82 .PP
83 If the
84 .I address\-group
85 starts with a `<', then the file named after the
86 `<' is read and its contents are added to the
87 .I address\-list
88 for the alias.
89 .PP
90 If the
91 .I address\-group
92 starts with an `=', then the file
93 .I /etc/group
94 is consulted for the UNIX\-group named after the `='.  Each login name
95 occurring as a member of the group is added to the
96 .I address\-list
97 for the alias.
98 .PP
99 In contrast, if the
100 .I address\-group
101 starts with a `+', then the file
102 .I /etc/group
103 is consulted to determine the group\-id of the
104 UNIX\-group named after the `+'.  Each login name occurring in the
105 .I /etc/passwd
106 file whose group\-id is indicated by this group is
107 added to the
108 .I address\-list
109 for the alias.
110 .PP
111 If the
112 .I address\-group
113 is simply `*', then the file
114 .I /etc/passwd
115 is consulted and all login names with a userid
116 greater than some magic number (usually 200) are added to the
117 .I address\-list
118 for the alias.
119 .PP
120 In match, a trailing \*(lq*\*(rq on an alias will match just about anything
121 appropriate.  (See example below.)
122 .PP
123 An approximation of the way aliases are resolved at posting time is
124 (it's not really done this way):
125 .PP
126 .RS 2
127 .IP 1) 3
128 Build a list of all addresses from the message to be delivered,
129 eliminating duplicate addresses.
130 .PP
131 .IP 2) 3
132 If this draft originated on the local host, then for those addresses in
133 the message that have no host specified, perform alias resolution.
134 .PP
135 .IP 3) 3
136 For each line in the alias file, compare \*(lqalias\*(rq against all of
137 the existing addresses.  If a match, remove the matched \*(lqalias\*(rq
138 from the address list, and add each new address in the address\-group to
139 the address list if it is not already on the list.  The alias itself is
140 not usually output, rather the address\-group that the alias maps to is
141 output instead.  If \*(lqalias\*(rq is terminated with a `;' instead of
142 a `:', then both the \*(lqalias\*(rq and the address are output in the
143 correct format.  (This makes replies possible since
144 .B nmh
145 aliases
146 and personal aliases are unknown to the mail transport system.)
147 .RE
148 .PP
149 Since the alias file is read line by line, forward references work, but
150 backward references are not recognized, thus, there is no recursion.
151 .PP
152 Example Alias File:
153 .PP
154 .RS 5
155 .nf
156 <%etcdir%/BBoardAliases
157 sgroup: fred, fear, freida
158 b-people: Blind List: bill, betty;
159 fred: frated@UCI
160 UNIX\-committee: <unix.aliases
161 staff: =staff
162 wheels: +wheel
163 everyone: *
164 news.*: news
165 .fi
166 .RE
167 .PP
168 The first line says that more aliases should immediately be read from
169 the file
170 .IR %etcdir%/BBoardAliases .
171 Following this, \*(lqfred\*(rq
172 is defined as an alias for \*(lqfrated@UCI\*(rq, and \*(lqsgroup\*(rq
173 is defined as an alias for the three names \*(lqfrated@UCI\*(rq,
174 \*(rqfear\*(rq, and \*(rqfreida\*(rq.
175 .PP
176 The alias \*(lqb-people\*(rq is a blind list which includes the addresses
177 \*(lqbill\*(rq and \*(lqbetty\*(rq; the message will be delieved to those
178 addresses, but the message header will  show only \*(lqBlind List: ;\*(rq
179 (not the addresses).
180 .PP
181 Next, the definition of \*(lqUNIX\-committee\*(rq is given by
182 reading the file
183 .I unix.aliases
184 in the users
185 .B nmh
186 directory,
187 \*(lqstaff\*(rq is defined as all users who are listed as members of the
188 group \*(lqstaff\*(rq in the
189 .I /etc/group
190 file, and \*(lqwheels\*(rq
191 is defined as all users whose group\-id in
192 .I /etc/passwd
193 is equivalent to the \*(lqwheel\*(rq group.
194 .PP
195 Finally, \*(lqeveryone\*(rq is defined as all users with a user\-id
196 in
197 .I /etc/passwd
198 greater than 200, and all aliases of the form
199 \*(lqnews.<anything>\*(rq are defined to be \*(lqnews\*(rq.
200 .PP
201 The key thing to understand about aliasing in
202 .B nmh
203 is that aliases in
204 .B nmh
205 alias files are expanded into the headers of messages posted.
206 This aliasing occurs first, at posting time, without the knowledge of the
207 message transport system.  In contrast, once the message transport system
208 is given a message to deliver to a list of addresses, for each address
209 that appears to be local, a system\-wide alias file is consulted.  These
210 aliases are
211 .B NOT
212 expanded into the headers of messages delivered.
213
214 .SH "HELPFUL HINTS"
215 To use aliasing in
216 .B nmh
217 quickly, do the following:
218 .PP
219 .RS 2
220 .IP 1) 3
221 In your
222 .IR \&.mh\(ruprofile ,
223 choose a name for your alias file, say
224 .RI \*(lq aliases \*(rq,
225 and add the line:
226 .PP
227 .RS 5
228 .nf
229 Aliasfile: aliases
230 .\" ali: \-alias aliases
231 .\" send: \-alias aliases
232 .\" whom: \-alias aliases
233 .fi
234 .RE
235 .PP
236 .IP 2) 3
237 Create the file
238 .RI \*(lq aliases \*(rq
239 in your
240 .B nmh
241 directory.
242 .PP
243 .IP 3) 3
244 Start adding aliases to your
245 .RI \*(lq aliases \*(rq
246 file as appropriate.
247 .RE
248
249 .SH FILES
250 .fc ^ ~
251 .nf
252 .ta \w'%etcdir%/ExtraBigFileName  'u
253 ^%etcdir%/MailAliases~^global nmh alias file
254 .fi
255
256 .SH "PROFILE COMPONENTS"
257 .fc ^ ~
258 .nf
259 .ta 2.4i
260 .ta \w'ExtraBigProfileName  'u
261 ^Aliasfile:~^For a default alias file
262 .fi
263
264 .SH "SEE ALSO"
265 ali(1), send(1), whom(1), group(5), passwd(5), conflict(8), post(8)
266
267 .SH CONTEXT
268 None
269
270 .SH BUGS
271 Although the forward-referencing semantics of
272 .B mh\-alias
273 files prevent recursion, the
274 .RI \*(lq< " alias\-file" \*(rq
275 command may defeat this.
276 Since the number of file descriptors is finite (and very limited), such
277 infinite recursion will terminate with a meaningless diagnostic when
278 all the fds are used up.
279 .PP
280 Forward references do not work correctly inside blind lists.