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