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