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