6921d979b5dec4eac9924747d891694b56517fc4
[openafs.git] / doc / man-pages / pod1 / pts_examine.pod
1 =head1 NAME
2
3 pts_examine - Displays a Protection Database entry
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<pts examine> S<<< B<-nameorid> <I<user or group name or id>>+ >>>
11     S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>] 
12     [B<-force>] [B<-help>]
13
14 B<pts e> S<<< B<-na> <I<user or group name or id>>+ >>> S<<< [B<-c> <I<cell name>>] >>>
15     [B<-no>] [B<-l>] [B<-f>] [B<-h>]
16
17 B<pts check> S<<< B<-na> <I<user or group name or id>>+ >>> S<<< [B<-c> <I<cell name>>] >>>
18     [B<-no>] [B<-l>] [B<-f>] [B<-h>]
19
20 B<pts che> S<<< B<-na> <I<user or group name or id>>+ >>> S<<< [B<-c> <I<cell name>>] >>>
21     [B<-no>] [B<-l>] [B<-f>] [B<-h>]
22
23 =for html
24 </div>
25
26 =head1 DESCRIPTION
27
28 The B<pts examine> command displays information from the Protection
29 Database entry of each user, machine or group specified by the
30 B<-nameorid> argument.
31
32 =head1 OPTIONS
33
34 =over 4
35
36 =item -nameorid <I<user or group name or id>>+
37
38 Specifies the name or AFS UID of each user, the name or AFS GID of each
39 group, or the IP address (complete or wildcard-style) or AFS UID of each
40 machine for which to display the Protection Database entry. It is
41 acceptable to mix users, machines, and groups on the same command line, as
42 well as names (IP addresses for machines) and IDs. Precede the GID of each
43 group with a hyphen to indicate that it is negative.
44
45 =item B<-cell> <I<cell name>>
46
47 Names the cell in which to run the command. For more details, see
48 L<pts(1)>.
49
50 =item B<-noauth>
51
52 Assigns the unprivileged identity anonymous to the issuer. For more
53 details, see L<pts(1)>.
54
55 =item B<-localauth>
56
57 Constructs a server ticket using a key from the local
58 F</usr/afs/etc/KeyFile> file. Do not combine this flag with the 
59 B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
60
61 =item B<-force>
62
63 Enables the command to continue executing as far as possible when errors
64 or other problems occur, rather than halting execution at the first error.
65
66 =item B<-help>
67
68 Prints the online help for this command. All other valid options are
69 ignored.
70
71 =back
72
73 =head1 OUTPUT
74
75 The output for each entry consists of two lines that include the following
76 fields:
77
78 =over 4
79
80 =item Name
81
82 The contents of this field depend on the type of entry:
83
84 =over 4
85
86 =item *
87
88 For a user entry, it is the username that the user types when
89 authenticating with AFS.
90
91 =item *
92
93 For a machine entry, it is either the IP address of a single machine in
94 dotted decimal format, or a wildcard notation that represents a group of
95 machines on the same network. See the B<pts createuser> reference page for
96 an explanation of the wildcard notation.
97
98 =item *
99
100 For a group entry, it is one of two types of group name. If the name has a
101 colon between the two parts, it represents a regular group and the part
102 before the prefix reflects the group's owner. A prefix-less group does not
103 have the owner field or the colon. For more details on group names, see
104 the B<pts creategroup> reference page.
105
106 =back
107
108 =item id
109
110 A unique number that the AFS server processes use to identify AFS users,
111 machines and groups. AFS UIDs for user and machine entries are positive
112 integers, and AFS GIDs for group entries are negative integers. AFS UIDs
113 and GIDs are similar in function to the UIDs and GIDs used in local file
114 systems such as UFS, but apply only to AFS operations.
115
116 =item owner
117
118 The user or group that owns the entry and thus can administer it (change
119 the values in most of the fields displayed in the output of this command),
120 or delete it entirely. The Protection Server automatically records the
121 system:administrators group in this field for user and machine entries at
122 creation time.
123
124 =item creator
125
126 The user who issued the B<pts createuser> or B<pts creategroup> command to
127 create the entry. This field serves as an audit trail, and cannot be
128 changed.
129
130 =item membership
131
132 An integer that for users and machines represents the number of groups to
133 which the user or machine belongs. For groups, it represents the number of
134 group members.
135
136 =item flags
137
138 A string of five characters, referred to as I<privacy flags>, which
139 indicate who can display or administer certain aspects of the entry.
140
141 =over 4
142
143 =item s
144
145 Controls who can issue the B<pts examine> command to display the entry.
146
147 =item o
148
149 Controls who can issue the B<pts listowned> command to display the groups
150 that a user or group owns.
151
152 =item m
153
154 Controls who can issue the B<pts membership> command to display the groups
155 a user or machine belongs to, or which users or machines belong to a
156 group.
157
158 =item a
159
160 Controls who can issue the B<pts adduser> command to add a user or machine
161 to a group. It is meaningful only for groups, but a value must always be
162 set for it even on user and machine entries.
163
164 =item r
165
166 Controls who can issue the B<pts removeuser> command to remove a user or
167 machine from a group. It is meaningful only for groups, but a value must
168 always be set for it even on user and machine entries.
169
170 =back
171
172 Each flag can take three possible types of values to enable a different
173 set of users to issue the corresponding command:
174
175 =over 4
176
177 =item *
178
179 A hyphen (-) designates the members of the system:administrators group and
180 the entry's owner. For user entries, it designates the user in addition.
181
182 =item *
183
184 The lowercase version of the letter applies meaningfully to groups only,
185 and designates members of the group in addition to the individuals
186 designated by the hyphen.
187
188 =item *
189
190 The uppercase version of the letter designates everyone.
191
192 =back
193
194 For example, the flags C<SOmar> on a group entry indicate that anyone can
195 examine the group's entry and display the groups that it owns, and that
196 only the group's members can display, add, or remove its members.
197
198 The default privacy flags for user and machine entries are C<S---->,
199 meaning that anyone can display the entry. The ability to perform any
200 other functions is restricted to members of the system:administrators
201 group and the entry's owner (as well as the user for a user entry).
202
203 The default privacy flags for group entries are C<S-M-->, meaning that all
204 users can display the entry and the members of the group, but only the
205 entry owner and members of the system:administrators group can perform
206 other functions.
207
208 =item group quota
209
210 The number of additional groups the user is allowed to create. The B<pts
211 createuser> command sets it to 20 for both users and machines, but it has
212 no meaningful interpretation for a machine, because it is not possible to
213 authenticate as a machine. Similarly, it has no meaning in group entries
214 and the B<pts creategroup> command sets it to 0 (zero); do not change this
215 value.
216
217 =back
218
219 =head1 EXAMPLES
220
221 The following example displays the user entry for C<terry> and the machine
222 entry C<158.12.105.44>.
223
224    % pts examine terry 158.12.105.44
225    Name: terry, id: 1045, owner: system:administrators, creator: admin,
226      membership: 9, flags: S----, group quota: 15.
227    Name: 158.12.105.44, id: 5151, owner: system:administrators,
228      creator: byu, membership: 1, flags: S----, group quota: 20.
229
230 The following example displays the entries for the AFS groups with GIDs
231 -673 and -674.
232
233    % pts examine -673 -674
234    Name: terry:friends, id: -673, owner: terry, creator: terry,
235      membership: 5, flags: S-M--, group quota: 0.
236    Name: smith:colleagues, id: -674, owner: smith, creator: smith,
237      membership: 14, flags: SOM--, group quota: 0.
238
239 =head1 PRIVILEGE REQUIRED
240
241 The required privilege depends on the setting of the first privacy flag in
242 the Protection Database entry of each entry specified by the B<-nameorid>
243 argument:
244
245 =over 4
246
247 =item *
248
249 If it is lowercase C<s>, members of the system:administrators group and
250 the user associated with a user entry can examine it, and only members of
251 the system:administrators group can examine a machine or group entry.
252
253 =item *
254
255 If it is uppercase C<S>, anyone who can access the cell's database server
256 machines can examine the entry.
257
258 =back
259
260 =head1 SEE ALSO
261
262 L<pts(1)>,
263 L<pts_adduser(1)>,
264 L<pts_chown(1)>,
265 L<pts_creategroup(1)>,
266 L<pts_createuser(1)>,
267 L<pts_listowned(1)>,
268 L<pts_membership(1)>,
269 L<pts_removeuser(1)>,
270 L<pts_rename(1)>,
271 L<pts_setfields(1)>
272
273 =head1 COPYRIGHT
274
275 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
276
277 This documentation is covered by the IBM Public License Version 1.0.  It was
278 converted from HTML to POD by software written by Chas Williams and Russ
279 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.