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