Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | uss_add - Creates a user account (deprecated) | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | =for html | |
8 | <div class="synopsis"> | |
9 | ||
10 | B<uss add> S<<< B<-user> <I<login name>> >>> S<<< [B<-realname> <I<full name in quotes>>] >>> | |
11 | S<<< [B<-pass> <I<initial password>>] >>> | |
12 | [B<-pwexpires> <I<< password expires in [0..254] days (0 => never) >>>] | |
13 | S<<< [B<-server> <I<file server for home volume>>] >>> | |
14 | S<<< [B<-partition> <I<file server's disk partition for home volume>>] >>> | |
15 | S<<< [B<-mount> <I<home directory mount point>>] >>> | |
16 | S<<< [B<-uid> <I<uid to assign the user>>] >>> | |
17 | S<<< [B<-template> <I<pathname of template file>>] >>> | |
18 | [B<-verbose>] S<<< [B<-var> <I<auxiliary argument pairs (Num val)>>+] >>> | |
19 | S<<< [B<-cell> <I<cell name>>] >>> S<<< [B<-admin> <I<administrator to authenticate>>] >>> | |
20 | [B<-dryrun>] [B<-skipauth>] [B<-overwrite>] [B<-help>] | |
21 | ||
22 | B<uss ad> S<<< B<-us> <I<login name>> >>> S<<< [B<-r> <I<full name in quotes>>] >>> | |
23 | S<<< [B<-pas> <I<initial password>>] >>> | |
24 | [B<-pw> <I<< password expires in [0..254] days (0 => never) >>>] | |
25 | S<<< [B<-se> <I<FileServer for home volume>>] >>> | |
26 | S<<< [B<-par> <I<FileServer's disk partition for home volume>>] >>> | |
27 | S<<< [B<-m> <I<home directory mount point>>] >>> | |
28 | S<<< [B<-ui> <I<uid to assign the user>>] >>> | |
29 | S<<< [B<-t> <I<pathname of template file>>] >>> [B<-ve>] | |
30 | S<<< [B<-va> <I<auxiliary argument pairs (Num val)>>+] >>> S<<< [B<-c> <I<cell name>>] >>> | |
31 | S<<< [B<-a> <I<administrator to authenticate>>] >>> [B<-d>] [B<-sk>] [B<-o>] | |
32 | [B<-h>] | |
33 | ||
34 | =for html | |
35 | </div> | |
36 | ||
37 | =head1 CAUTIONS | |
38 | ||
39 | The B<uss> command suite is currently designed for cells using the | |
40 | obsolete Authentication Server, and therefore is primarily useful for | |
41 | sites that have not yet migrated to a Kerberos version 5 KDC. The | |
42 | Authentication Server and supporting commands will be removed in a future | |
43 | version of OpenAFS, which may include B<uss> unless someone who finds it | |
44 | useful converts it to work with a Kerberos version 5 KDC. | |
45 | ||
46 | =head1 DESCRIPTION | |
47 | ||
48 | The B<uss add> command creates entries in the Protection Database and | |
49 | Authentication Database for the user name specified by the B<-user> | |
50 | argument. By default, the Protection Server automatically allocates an AFS | |
51 | user ID (UID) for the new user; to specify an alternate AFS UID, include | |
52 | the B<-uid> argument. If a password is provided with the B<-pass> | |
53 | argument, it is stored as the user's password in the Authentication | |
54 | Database after conversion into a form suitable for use as an encryption | |
55 | key. Otherwise, the string C<changeme> is assigned as the user's initial | |
56 | password. | |
57 | ||
58 | The other results of the command depend on which instructions and which of | |
59 | a defined set of variables appear in the template file specified with the | |
60 | B<-template> argument. Many of the command's arguments supply a value for | |
61 | one of the defined variables, and failure to provide an argument when the | |
62 | corresponding variable appears in the template file halts the account | |
63 | creation process at the point where the command interpreter first | |
64 | encounters the variable in the template file. | |
65 | ||
66 | To create multiple accounts with a single command, use the B<uss bulk> | |
67 | command. To delete accounts with a single command, use the B<uss delete> | |
68 | command. | |
69 | ||
70 | =head1 OPTIONS | |
71 | ||
72 | =over 4 | |
73 | ||
74 | =item B<-user> <I<login name>> | |
75 | ||
76 | Names the user's Authentication Database and Protection Database | |
77 | entries. It can include up to eight alphanumeric characters, but not any | |
78 | of the following characters: C<:> (colon), C<@> (at-sign), C<.> (period), | |
79 | space, or newline. Because it becomes the username (the name under which a | |
80 | user logs in), it is best not to include shell metacharacters and to obey | |
81 | the restrictions that many operating systems impose on usernames (usually, | |
82 | to contain no more than eight lowercase letters). | |
83 | ||
84 | Corresponding variable in the template file: $USER. | |
85 | ||
86 | =item B<-realname> <I<full name in quotes>> | |
87 | ||
88 | Specifies the user's full name. If it contains spaces or punctuation, | |
89 | surround it with double quotes. If not provided, it defaults to the user | |
90 | name provided with the B<-user> argument. | |
91 | ||
92 | Corresponding variable in the template file: $NAME. Many operating systems | |
93 | include a field for the full name in a user's entry in the local password | |
94 | file (F</etc/passwd> or equivalent), and this variable can be used to pass | |
95 | a value to be used in that field. | |
96 | ||
97 | =item B<-pass> <I<initial password>> | |
98 | ||
99 | Specifies the user's initial password. Although the AFS commands that | |
100 | handle passwords accept strings of virtually unlimited length, it is best | |
101 | to use a password of eight characters or less, which is the maximum length | |
102 | that many applications and utilities accept. If not provided, this | |
103 | argument defaults to the string C<changeme>. | |
104 | ||
105 | Corresponding variable in the template file: none. | |
106 | ||
107 | =item B<-pwexpires> <I<password expiration>> | |
108 | ||
109 | Sets the number of days after a user's password is changed that it remains | |
110 | valid. Provide an integer from the range C<1> through C<254> to specify | |
111 | the number of days until expiration, or the value C<0> to indicate that | |
112 | the password never expires (the default). | |
113 | ||
114 | When the password becomes invalid (expires), the user is unable to | |
115 | authenticate, but has 30 more days in which to issue the B<kpasswd> | |
116 | command to change the password (after that, only an administrator can | |
117 | change it). | |
118 | ||
119 | Corresponding variable in the template file: $PWEXPIRES. | |
120 | ||
121 | =item B<-server> <I<file server name>> | |
122 | ||
123 | Names the file server machine on which to create the new user's volume. It | |
124 | is best to provide a fully qualified hostname (for example, | |
125 | C<fs1.example.com>), but an abbreviated form is acceptable provided that the | |
126 | cell's naming service is available to resolve it at the time the volume is | |
127 | created. | |
128 | ||
129 | Corresponding variable in the template file: $SERVER. | |
130 | ||
131 | =item B<-partition> <I<file server partition>> | |
132 | ||
133 | Specifies the partition on which to create the user's volume; it must be | |
134 | on the file server machine named by the B<-server> argument. Provide the | |
135 | complete partition name (for example F</vicepa>) or one of the following | |
136 | abbreviated forms: | |
137 | ||
138 | /vicepa = vicepa = a = 0 | |
139 | /vicepb = vicepb = b = 1 | |
140 | ||
141 | After F</vicepz> (for which the index is 25) comes | |
142 | ||
143 | /vicepaa = vicepaa = aa = 26 | |
144 | /vicepab = vicepab = ab = 27 | |
145 | ||
146 | and so on through | |
147 | ||
148 | /vicepiv = vicepiv = iv = 255 | |
149 | ||
150 | Corresponding variable in the template file: $PART. | |
151 | ||
152 | =item B<-mount> <I<home directory mount point>> | |
153 | ||
154 | Specifies the pathname for the user's home directory. Partial pathnames | |
155 | are interpreted relative to the current working directory. | |
156 | ||
157 | Specify the read/write path to the directory, to avoid the failure that | |
158 | results from attempting to create a new mount point in a read-only | |
159 | volume. By convention, the read/write path is indicated by placing a | |
160 | period before the cell name at the pathname's second level (for example, | |
161 | F</afs/.example.com>). For further discussion of the concept of read/write and | |
162 | read-only paths through the filespace, see the B<fs mkmount> reference | |
163 | page. | |
164 | ||
165 | Corresponding variable in template: $MTPT, but in the template file's C<V> | |
166 | instruction only. Occurrences of the $MTPT variable in template | |
167 | instructions that follow the C<V> instruction take their value from the | |
168 | C<V> instruction's I<mount_point> field. Thus the value of this command | |
169 | line argument becomes the value for the $MTPT variable in instructions | |
170 | that follow the C<V> instruction only if the string $MTPT appears alone in | |
171 | the C<V> instruction's I<mount_point> field. | |
172 | ||
173 | =item B<-uid> <I<uid to assign the user>> | |
174 | ||
175 | Specifies a positive integer other than 0 (zero) to assign as the user's | |
176 | AFS UID. If this argument is omitted, the Protection Server assigns an AFS | |
177 | UID that is one greater than the current value of the C<max user id> | |
178 | counter (use the B<pts listmax> command to display the counter). If | |
179 | including this argument, it is best first to use the B<pts examine> | |
180 | command to verify that no existing account already has the desired AFS | |
181 | UID; it one does, the account creation process terminates with an error. | |
182 | ||
183 | Corresponding variable in the template file: $UID. | |
184 | ||
185 | =item B<-template> <I<pathname of template file>> | |
186 | ||
187 | Specifies the pathname of the template file. If this argument is omitted, | |
188 | the command interpreter searches the following directories in the | |
189 | indicated order for a file called C<uss.template>: | |
190 | ||
191 | =over 4 | |
192 | ||
193 | =item * | |
194 | ||
195 | The current working directory. | |
196 | ||
197 | =item * | |
198 | ||
199 | F</afs/I<cellname>/common/uss>, where I<cellname> names the local cell. | |
200 | ||
201 | =item * | |
202 | ||
203 | F</etc> | |
204 | ||
205 | =back | |
206 | ||
207 | If the issuer provides a filename other than C<uss.template> but without a | |
208 | pathname, the command interpreter searches for it in the indicated | |
209 | directories. If the issuer provides a full or partial pathname, the | |
210 | command interpreter consults the specified file only; it interprets | |
211 | partial pathnames relative to the current working directory. | |
212 | ||
213 | If the specified template file is empty (zero-length), the command creates | |
214 | Protection and Authentication Database entries only. | |
215 | ||
216 | L<uss(5)> details the file's format. | |
217 | ||
218 | =item B<-verbose> | |
219 | ||
220 | Produces on the standard output stream a detailed trace of the command's | |
221 | execution. If this argument is omitted, only warnings and error messages | |
222 | appear. | |
223 | ||
224 | =item B<-var> <I<auxilliary argument pairs>> | |
225 | ||
226 | Specifies values for each of the number variables $1 through $9 that can | |
227 | appear in the template file. Use the number variables to assign values to | |
228 | variables in the B<uss> template file that are not part of the standard | |
229 | set. | |
230 | ||
231 | Corresponding variables in the template file: $1 through $9. | |
232 | ||
233 | For each instance of this argument, provide two parts in the indicated | |
234 | order, separated by a space: | |
235 | ||
236 | =over 4 | |
237 | ||
238 | =item * | |
239 | ||
240 | The integer from the range C<1> through C<9> that matches the variable in | |
241 | the template file. Do not precede it with a dollar sign. | |
242 | ||
243 | =item * | |
244 | ||
245 | A string of alphanumeric characters to assign as the value of the | |
246 | variable. | |
247 | ||
248 | =back | |
249 | ||
250 | See the chapter on uss in the I<OpenAFS Administration Guide> for further | |
251 | explanation. | |
252 | ||
253 | =item B<-cell> <I<cell name>> | |
254 | ||
255 | Specifies the cell in which to run the command. For more details, see | |
256 | L<uss(8)>. | |
257 | ||
258 | =item B<-admin> <I<administrator to authenticate>> | |
259 | ||
260 | Specifies the AFS user name under which to establish authenticated | |
261 | connections to the AFS server processes that maintain the various | |
262 | components of a user account. For more details, see L<uss(8)>. | |
263 | ||
264 | =item B<-dryrun> | |
265 | ||
266 | Reports actions that the command interpreter needs to perform while | |
267 | executing the command, without actually performing them. For more details, | |
268 | see L<uss(8)>. | |
269 | ||
270 | =item B<-skipauth> | |
271 | ||
272 | Prevents authentication with the AFS Authentication Server, allowing a | |
273 | site using Kerberos to substitute that form of authentication. | |
274 | ||
275 | =item B<-overwrite> | |
276 | ||
277 | Overwrites any directories, files and links that exist in the file system | |
278 | and for which there are definitions in C<D>, C<E>, C<F>, C<L>, or C<S> | |
279 | instructions in the template file named by the B<-template> argument. If | |
280 | this flag is omitted, the command interpreter prompts once for | |
281 | confirmation that it is to overwrite all such elements. | |
282 | ||
283 | =item B<-help> | |
284 | ||
285 | Prints the online help for this command. All other valid options are | |
286 | ignored. | |
287 | ||
288 | =back | |
289 | ||
290 | =head1 EXAMPLES | |
291 | ||
292 | The combination of the following example uss add command and C<V> | |
293 | instruction in a template file called C<uss.tpl> creates Protection and | |
294 | Authentication Database entries named C<smith>, and a volume called | |
295 | C<user.smith> with a quota of 2500 kilobyte blocks, mounted at the | |
296 | pathname F</afs/example.com/usr/smith>. The access control list (ACL) on the | |
297 | mount point grants C<smith> all rights. | |
298 | ||
299 | The issuer of the B<uss add> command provides only the template file's | |
300 | name, not its complete pathname, because it resides in the current working | |
301 | directory. The command and C<V> instruction appear here on two lines only | |
302 | for legibility; there are no line breaks in the actual instruction or | |
303 | command. | |
304 | ||
305 | V user.$USER $SERVER.example.com /vice$PART $1 \ | |
306 | /afs/example.com/usr/$USER $UID $USER all | |
307 | ||
308 | % uss add -user smith -realname "John Smith" -pass js_pswd \ | |
309 | -server fs2 -partition b -template uss.tpl -var 1 2500 | |
310 | ||
311 | =head1 PRIVILEGE REQUIRED | |
312 | ||
313 | The issuer (or the user named by the B<-admin> argument) must belong to | |
314 | the system:administrators group in the Protection Database and must have | |
315 | the C<ADMIN> flag turned on in his or her Authentication Database entry. | |
316 | ||
317 | If the template contains a C<V> instruction, the issuer must be listed in | |
318 | the F</usr/afs/etc/UserList> file and must have at least C<a> (administer) | |
319 | and C<i> (insert) permissions on the ACL of the directory that houses the | |
320 | new mount point. If the template file includes instructions for creating | |
321 | other types of objects (directories, files or links), the issuer must have | |
322 | each privilege necessary to create them. | |
323 | ||
324 | =head1 SEE ALSO | |
325 | ||
326 | L<UserList(5)>, | |
327 | L<uss(5)>, | |
328 | L<fs_mkmount(1)>, | |
329 | L<uss(8)>, | |
330 | L<uss_bulk(8)>, | |
331 | L<uss_delete(8)> | |
332 | ||
333 | =head1 COPYRIGHT | |
334 | ||
335 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
336 | ||
337 | This documentation is covered by the IBM Public License Version 1.0. It was | |
338 | converted from HTML to POD by software written by Chas Williams and Russ | |
339 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |