Disallow creating users with ANONYMOUSID
[openafs.git] / doc / man-pages / pod1 / pts_createuser.pod.in
1 =head1 NAME
2
3 pts_createuser - Creates a user or machine entry in the Protection Database
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<pts createuser> S<<< B<-name> <I<user name>>+ >>> S<<< [B<-id> <I<user id>>+] >>>
11     S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>] [B<-force>] 
12     [B<-help>] [B<-auth>] [B<-encrypt>] S<<< [B<-config> <I<config directory>>] >>>
13
14 B<pts createu> S<<< B<-na> <I<user name>>+ >>> S<<< [B<-i> <I<user id>>+] >>>
15     S<<< [B<-c> <I<cell name>>] >>> [B<-no>] [B<-l>] [B<-f>] [B<-h>]
16     [B<-a>] [B<-e>] S<<< [B<-co> <I<config directory>>] >>>
17
18 B<pts cu> S<<< B<-na> <I<user name>>+ >>> S<<< [B<-i> <I<user id>>+] >>>
19     S<<< [B<-c> <I<cell name>>] >>> [B<-no>] [B<-l>] [B<-f>] [B<-h>]
20     [B<-a>] [B<-e>] S<<< [B<-co> <I<config directory>>] >>>
21
22 =for html
23 </div>
24
25 =head1 DESCRIPTION
26
27 The B<pts createuser> command creates an entry in the Protection Database
28 for each user or machine specified by the B<-name> argument. A user entry
29 name becomes the user's AFS username (the one to provide when
30 authenticating with the AFS Authentication Server).  A machine entry's
31 name is the machine's IP address or a wildcard notation that represents a
32 range of consecutive IP addresses (a group of machines on the same
33 network). It is not possible to authenticate as a machine, but a group to
34 which a machine entry belongs can appear on a directory's access control
35 list (ACL), thereby granting the indicated permissions to any user logged
36 on to the machine.
37
38 AFS user IDs (AFS UIDs) are positive integers and by default the
39 Protection Server assigns an AFS UID that is one greater than the current
40 value of the C<max user id> counter in the Protection Database,
41 incrementing the counter by one for each user. To assign a specific AFS
42 UID, use the B<-id> argument. If any of the specified AFS UIDs is greater
43 than the current value of the C<max user id> counter, the counter is reset
44 to that value. It is acceptable to specify an AFS UID smaller than the
45 current value of the counter, but the creation operation fails if an
46 existing user or machine entry already has it. To display or set the value
47 of the C<max user id> counter, use the B<pts listmax> or B<pts setmax>
48 command, respectively.
49
50 The issuer of the B<pts createuser> command is recorded as the entry's
51 creator and the group system:administrators as its owner.
52
53 =head1 CAUTIONS
54
55 The Protection Server reserves several AFS UIDs, including 0 (zero) and
56 32766 (anonymous) for internal use, and returns an error if
57 the B<-id> argument has a reserved value.
58
59 =head1 OPTIONS
60
61 =over 4
62
63 =item B<-name> <I<user name>>+
64
65 Specifies either a username for a user entry, or an IP address (complete
66 or wildcarded) for a machine entry:
67
68 =over 4
69
70 =item *
71
72 A username can include up to 63 numbers and lowercase letters, but it is
73 best to make it shorter than eight characters, because many application
74 programs cannot handle longer names. Also, it is best not to include shell
75 metacharacters or other punctuation marks. In particular, the colon (C<:>)
76 and at-sign (C<@>) characters are not acceptable. The period is generally
77 used only in special administrative names, to separate the username and an
78 I<instance>, as in the example C<pat.admin>.
79
80 =item *
81
82 A machine identifier is its IP address in dotted decimal notation (for
83 example, 192.12.108.240), or a wildcard notation that represents a set of
84 IP addresses (a group of machines on the same network). The following are
85 acceptable wildcard formats. The letters C<W>, C<X>, C<Y> and C<Z> each
86 represent an actual number from the range 1 through 255.
87
88 =over 4
89
90 =item *
91
92 W.X.Y.Z represents a single machine, for example C<192.12.108.240>.
93
94 =item *
95
96 W.X.Y.0 matches all machines whose IP addresses start with the first three
97 numbers. For example, C<192.12.108.0> matches both C<192.12.108.119> and
98 C<192.12.108.120>, but does not match C<192.12.105.144>.
99
100 =item *
101
102 W.X.0.0 matches all machines whose IP addresses start with the first two
103 numbers. For example, the address C<192.12.0.0> matches both
104 C<192.12.106.23> and C<192.12.108.120>, but does not match C<192.5.30.95>.
105
106 =item *
107
108 W.0.0.0 matches all machines whose IP addresses start with the first
109 number in the specified address. For example, the address C<192.0.0.0>
110 matches both C<192.5.30.95> and C<192.12.108.120>, but does not match
111 C<138.255.63.52>.
112
113 =back
114
115 Do not define a machine entry with the name C<0.0.0.0> to match every
116 machine. The system:anyuser group is equivalent.
117
118 =back
119
120 =item B<-id> <I<user id>>+
121
122 Specifies an AFS UID for each user or machine entry, rather than allowing
123 the Protection Server to assign it. Provide a positive integer.
124
125 If this argument is used and the B<-name> argument names multiple new
126 entries, it is best to provide an equivalent number of AFS UIDs.  The
127 first UID is assigned to the first entry, the second to the second entry,
128 and so on. If there are fewer UIDs than entries, the Protection Server
129 assigns UIDs to the unmatched entries based on the C<max user id>
130 counter. If there are more UIDs than entries, the excess UIDs are
131 ignored. If any of the UIDs is greater than the current value of the C<max
132 user id> counter, the counter is reset to that value.
133
134 =include fragments/pts-common.pod
135
136 =back
137
138 =head1 OUTPUT
139
140 The command generates the following string to confirm creation of each
141 user:
142
143    User <name> has id <id>
144
145 =head1 EXAMPLES
146
147 The following example creates a Protection Database entry for the user
148 C<johnson>.
149
150    % pts createuser -name johnson
151
152 The following example creates three wildcarded machine entries in the Example
153 Corporation cell. The three entries encompass all of the machines on the
154 company's networks without including machines on other networks:
155
156    % pts createuser -name 138.255.0.0 192.12.105.0 192.12.106.0
157
158 =head1 PRIVILEGE REQUIRED
159
160 The issuer must belong to the system:administrators group.
161
162 =head1 SEE ALSO
163
164 L<pts(1)>,
165 L<pts_listmax(1)>,
166 L<pts_setmax(1)>
167
168 =head1 COPYRIGHT
169
170 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
171
172 This documentation is covered by the IBM Public License Version 1.0.  It was
173 converted from HTML to POD by software written by Chas Williams and Russ
174 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.