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