doc/man-pages/pod1/pts_examine.pod.in

   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.