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