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