Update the man pages pod source adding text to discourage use of
[openafs.git] / doc / man-pages / pod8 / uss_bulk.pod
1 =head1 NAME
2
3 uss_bulk - Executes multiple uss commands listed in a file
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<uss bulk> S<<< B<-file> <I<bulk input file>> >>>
11     S<<< [B<-template> <I<pathname of template file>>] >>> [B<-verbose>]
12     S<<< [B<-cell> <I<cell name>>] >>>
13     S<<< [B<-admin> <I<administrator to authenticate>>] >>> [B<-dryrun>]
14     [B<-skipauth>] [B<-overwrite>]
15     [B<-pwexpires> <I<password expires in [0..254] days (0 => never)>>]
16     [B<-pipe>] [B<-help>]
17
18 B<uss b> S<<< B<-f> <I<bulk input file>> >>> S<<< [B<-t> <I<pathname of template file>>] >>>
19     [B<-v>] S<<< [B<-c> <I<cell name>>] >>>
20     S<<< [B<-a> <I<administrator to authenticate>>] >>> [B<-d>] [B<-s>]
21     [B<-o>] [B<-pw> <I<password expires in [0..254] days (0 => never)>>]
22     [B<-pi>] [B<-h>]
23
24 =for html
25 </div>
26
27 =head1 CAUTIONS
28
29 The B<uss> command suite is currently designed for cells using the
30 obsolete Authentication Server, and therefore is primarily useful for
31 sites that have not yet migrated to a Kerberos version 5 KDC. The
32 Authentication Server and supporting commands will be removed in a future
33 version of OpenAFS, which may include B<uss> unless someone who finds it
34 useful converts it to work with a Kerberos version 5 KDC.
35
36 =head1 DESCRIPTION
37
38 The B<uss bulk> command executes the uss commands listed in the I<bulk
39 input file> specified with the B<-file> argument. If the bulk input file
40 includes B<add> instructions that reference a template file, then the
41 B<-template> argument is required.
42
43 To create a single account, use the B<uss add> command. To delete one or
44 more accounts, use the B<uss delete> command.
45
46 =head1 OPTIONS
47
48 =over 4
49
50 =item B<-file> <I<bulk input file>>
51
52 Specifies the pathname of the bulk input file. Partial pathnames are
53 interpreted relative to the current working directory. For details on the
54 file's format, see L<uss_bulk(5)>.
55
56 =item B<-template> <I<pathname of template file>>
57
58 Specifies the pathname of the template file for any uss add commands that
59 appear in the bulk input file. Partial pathnames are interpreted relative
60 to the current working directory. For details on the file's format, see
61 L<uss(5)>.
62
63 =item B<-verbose>
64
65 Produces on the standard output stream a detailed trace of the command's
66 execution. If this argument is omitted, only warnings and error messages
67 appear.
68
69 =item B<-cell> <I<cell name>>
70
71 Specifies the cell in which to run the command. For more details, see
72 L<uss(8)>.
73
74 =item B<-admin> <I<administrator to authenticate>>
75
76 Specifies the AFS user name under which to establish authenticated
77 connections to the AFS server processes that maintain the various
78 components of a user account. For more details, see L<uss(8)>.
79
80 =item B<-dryrun>
81
82 Reports actions that the command interpreter needs to perform while
83 executing the command, without actually performing them. For more details,
84 see L<uss(8)>.
85
86 =item B<-skipauth>
87
88 Prevents authentication with the AFS Authentication Server, allowing a
89 site using Kerberos to substitute that form of authentication.
90
91 =item B<-overwrite>
92
93 Overwrites any directories, files and links that exist in the file system
94 and for which there are also C<D>, C<E>, C<F>, C<L>, or C<S> instructions
95 in a template file referenced by an C<add> instruction in the bulk input
96 file. If this flag is omitted, the command interpreter prompts, once for
97 each C<add> instruction in the bulk input file, for confirmation that it
98 should overwrite such elements. Do not include this flag if the bulk input
99 file does not contain C<add> instructions.
100
101 =item B<-pwexpires> <I<password expiration>>
102
103 Sets the number of days after a user's password is changed that it remains
104 valid, for each user named by an C<add> instruction in the bulk input
105 file. Provide an integer from the range C<1> through C<254> to specify the
106 number of days until expiration, or the value C<0> to indicate that the
107 password never expires (the default).
108
109 When the password becomes invalid (expires), the user is unable to
110 authenticate, but has 30 more days in which to issue the B<kpasswd>
111 command to change the password (after that, only an administrator can
112 change it).
113
114 =item B<-pipe>
115
116 Suppresses the Authentication Server's prompt for the password of the
117 issuer or the user named by the B<-admin> argument (the Authentication
118 Server always separately authenticates the creator of an entry in the
119 Authentication Database). Instead, the command interpreter accepts the
120 password via the standard input stream, as piped in from another
121 program. This enables the B<uss bulk> command to run as part of unattended
122 batch jobs.
123
124 =item B<-help>
125
126 Prints the online help for this command. All other valid options are
127 ignored.
128
129 =back
130
131 =head1 EXAMPLES
132
133 The following example command executes the instructions in the bulk input
134 file called F<new_students>, which includes C<add> instructions that refer
135 to the template file F<student.template>. Both files reside in the current
136 working directory.
137
138    % uss bulk new_students student.template
139
140 =head1 PRIVILEGE REQUIRED
141
142 The issuer (or the user named by the B<-admin> argument) must have the
143 privileges necessary to run the commands that correspond to instructions
144 in the bulk input file.
145
146 =head1 SEE ALSO
147
148 L<uss(5)>,
149 L<uss_bulk(5)>,
150 L<uss(8)>,
151 L<uss_add(8)>,
152 L<uss_delete(8)>
153
154 =head1 COPYRIGHT
155
156 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
157
158 This documentation is covered by the IBM Public License Version 1.0.  It was
159 converted from HTML to POD by software written by Chas Williams and Russ
160 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.