doc: pts manpage fixes
[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 AFS UID 0 (zero) and returns an error if
56 the B<-id> argument has that value.
57
58 =head1 OPTIONS
59
60 =over 4
61
62 =item B<-name> <I<user name>>+
63
64 Specifies either a username for a user entry, or an IP address (complete
65 or wildcarded) for a machine entry:
66
67 =over 4
68
69 =item *
70
71 A username can include up to 63 numbers and lowercase letters, but it is
72 best to make it shorter than eight characters, because many application
73 programs cannot handle longer names. Also, it is best not to include shell
74 metacharacters or other punctuation marks. In particular, the colon (C<:>)
75 and at-sign (C<@>) characters are not acceptable. The period is generally
76 used only in special administrative names, to separate the username and an
77 I<instance>, as in the example C<pat.admin>.
78
79 =item *
80
81 A machine identifier is its IP address in dotted decimal notation (for
82 example, 192.12.108.240), or a wildcard notation that represents a set of
83 IP addresses (a group of machines on the same network). The following are
84 acceptable wildcard formats. The letters C<W>, C<X>, C<Y> and C<Z> each
85 represent an actual number from the range 1 through 255.
86
87 =over 4
88
89 =item *
90
91 W.X.Y.Z represents a single machine, for example C<192.12.108.240>.
92
93 =item *
94
95 W.X.Y.0 matches all machines whose IP addresses start with the first three
96 numbers. For example, C<192.12.108.0> matches both C<192.12.108.119> and
97 C<192.12.108.120>, but does not match C<192.12.105.144>.
98
99 =item *
100
101 W.X.0.0 matches all machines whose IP addresses start with the first two
102 numbers. For example, the address C<192.12.0.0> matches both
103 C<192.12.106.23> and C<192.12.108.120>, but does not match C<192.5.30.95>.
104
105 =item *
106
107 W.0.0.0 matches all machines whose IP addresses start with the first
108 number in the specified address. For example, the address C<192.0.0.0>
109 matches both C<192.5.30.95> and C<192.12.108.120>, but does not match
110 C<138.255.63.52>.
111
112 =back
113
114 Do not define a machine entry with the name C<0.0.0.0> to match every
115 machine. The system:anyuser group is equivalent.
116
117 =back
118
119 =item B<-id> <I<user id>>+
120
121 Specifies an AFS UID for each user or machine entry, rather than allowing
122 the Protection Server to assign it. Provide a positive integer.
123
124 If this argument is used and the B<-name> argument names multiple new
125 entries, it is best to provide an equivalent number of AFS UIDs.  The
126 first UID is assigned to the first entry, the second to the second entry,
127 and so on. If there are fewer UIDs than entries, the Protection Server
128 assigns UIDs to the unmatched entries based on the C<max user id>
129 counter. If there are more UIDs than entries, the excess UIDs are
130 ignored. If any of the UIDs is greater than the current value of the C<max
131 user id> counter, the counter is reset to that value.
132
133 =include fragments/pts-common.pod
134
135 =back
136
137 =head1 OUTPUT
138
139 The command generates the following string to confirm creation of each
140 user:
141
142    User <name> has id <id>
143
144 =head1 EXAMPLES
145
146 The following example creates a Protection Database entry for the user
147 C<johnson>.
148
149    % pts createuser -name johnson
150
151 The following example creates three wildcarded machine entries in the Example
152 Corporation cell. The three entries encompass all of the machines on the
153 company's networks without including machines on other networks:
154
155    % pts createuser -name 138.255.0.0 192.12.105.0 192.12.106.0
156
157 =head1 PRIVILEGE REQUIRED
158
159 The issuer must belong to the system:administrators group.
160
161 =head1 SEE ALSO
162
163 L<pts(1)>,
164 L<pts_listmax(1)>,
165 L<pts_setmax(1)>
166
167 =head1 COPYRIGHT
168
169 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
170
171 This documentation is covered by the IBM Public License Version 1.0.  It was
172 converted from HTML to POD by software written by Chas Williams and Russ
173 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.