PTS_EXAMINE(1)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

💖 PTS_EXAMINE 💖

okay bestie, sit down, hydrate, and let me tell you about pts_examine — it lives in the AFS Command Reference, section 1, and it is genuinely one of the most useful little gremlins in the whole pts family. ✨

🌸 NAME 🌸

pts_examine — displays a Protection Database entry. that's it, that's the job, and she does it flawlessly. 💅

🎀 SYNOPSIS 🎀

pts examine -nameorid <user or group name or id>+
    [-cell <cell name>] [-noauth] [-localauth]
    [-force] [-auth] [-help]
    [-encrypt] [-config <config directory>]

pts e -na <user or group name or id>+ [-c <cell name>]
    [-no] [-l] [-f] [-a] [-h]
    [-e] [-co <config directory>]

pts check -na <user or group name or id>+ [-c <cell name>]
    [-no] [-l] [-f] [-a] [-h]
    [-e] [-co <config directory>]

pts che -na <user or group name or id>+ [-c <cell name>]
    [-no] [-l] [-f] [-a] [-h]
    [-e] [-co <config directory>]

like yes, there are three aliases and she answers to all of them, main character energy fr fr 👑

🦋 DESCRIPTION 🦋

ok so the way that this works: pts examine pulls up the tea on the Protection Database entry for every user, machine, or group you hand it in the -nameorid argument. you say who, she says everything. no cap. 💖

✨ OPTIONS ✨

  • -nameorid <user or group name or id>+ — tells her whose entry to pull up. this can be the name or AFS UID of each user, the name or AFS GID of each group, or the IP address (complete or wildcard-style) or AFS UID of each machine. and yes you can absolutely mix users, machines, and groups on the same command line, and mix names (IP addresses for machines) with IDs too, she does not care, she thrives on chaos. ⚠️ one thing though: put a hyphen in front of each group's GID, because group IDs are negative. don't forget it, bestie.
  • -auth — uses the calling user's tokens to talk to the Protection Server. for more deets, peek at pts(1). 🫶
  • -cell <cell name> — names the cell you want the command to run in. more deets in pts(1).
  • -config <config directory> — use an alternate config directory instead. more deets in pts(1).
  • -encrypt — encrypts any communication with the Protection Server. more deets in pts(1). she's being careful, we love that 💜
  • -force — lets the command keep going as far as she possibly can when errors or other problems pop up, instead of slamming on the brakes at the very first error. resilience queen. 🔥
  • -help — prints the online help for this command. every other valid option gets ignored when you use this, so don't bother piling them on.
  • -localauth — constructs a server ticket using a key from the local /etc/openafs/server/KeyFile file. 🚨 do NOT combine this flag with the -cell or -noauth options. more deets in pts(1).
  • -noauth — assigns the unprivileged identity anonymous to the issuer. more deets in pts(1).

🌈 OUTPUT 🌈

for each entry you get two lines of output, and those lines include the following fields:

Name

what shows up here depends on what kind of entry it is:

  • for a user entry, it's the username that the user types when authenticating with AFS.
  • for a machine entry, it's either the IP address of a single machine in dotted decimal format, or a wildcard notation that represents a group of machines on the same network. see the pts createuser reference page for an explanation of the wildcard notation.
  • for a group entry, it's one of two types of group name. if the name has a colon between the two parts, it represents a regular group and the part before the prefix reflects the group's owner. a prefix-less group does not have the owner field or the colon. for more details on group names, see the pts creategroup reference page.

id

a unique number that the AFS server processes use to identify AFS users, machines and groups. AFS UIDs for user and machine entries are positive integers, and AFS GIDs for group entries are negative integers. AFS UIDs and GIDs are similar in function to the UIDs and GIDs used in local file systems such as UFS, but they apply only to AFS operations. 🫡

owner

the user or group that owns the entry, and therefore can administer it (change the values in most of the fields displayed in the output of this command), or delete it entirely. the Protection Server automatically records the system:administrators group in this field for user and machine entries at creation time.

creator

the user who issued the pts createuser or pts creategroup command to create the entry. this field is an audit trail, and it cannot be changed. periodt. 🔒

membership

an integer that, for users and machines, represents the number of groups the user or machine belongs to. for groups, it represents the number of group members.

flags

a string of five characters, known as privacy flags, which say who can display or administer certain aspects of the entry.

  • s — controls who can issue the pts examine command to display the entry.
  • o — controls who can issue the pts listowned command to display the groups that a user or group owns.
  • m — controls who can issue the pts membership command to display the groups a user or machine belongs to, or which users or machines belong to a group.
  • a — controls who can issue the pts adduser command to add a user or machine to a group. it's meaningful only for groups, but a value must always be set for it even on user and machine entries.
  • r — controls who can issue the pts removeuser command to remove a user or machine from a group. it's meaningful only for groups, but a value must always be set for it even on user and machine entries.

each flag can take three possible types of values, each enabling a different set of users to issue the corresponding command:

  • A hyphen (-) designates the members of the system:administrators group and the entry's owner. for user entries, it designates the user in addition.
  • The lowercase version of the letter applies meaningfully to groups only, and designates members of the group in addition to the individuals designated by the hyphen.
  • The uppercase version of the letter designates everyone. 😳

for example, the flags "SOmar" on a group entry indicate that anyone can examine the group's entry and display the groups that it owns, and that only the group's members can display, add, or remove its members.

the default privacy flags for user and machine entries are "S----", meaning that anyone can display the entry. the ability to perform any other functions is restricted to members of the system:administrators group and the entry's owner (as well as the user for a user entry).

the default privacy flags for group entries are "S-M--", meaning that all users can display the entry and the members of the group, but only the entry owner and members of the system:administrators group can perform other functions. these defaults may be changed by running ptserver with the -default_access option. see ptserver(8) for more discussion of the -default_access option.

group quota

the number of additional groups the user is allowed to create. the pts createuser command sets it to 20 for both users and machines, but it has no meaningful interpretation for a machine, because it is not possible to authenticate as a machine. similarly, it has no meaning in group entries that only deal with the local cell, and the pts creategroup command sets it to 0 (zero); do not change this value. 🚫

when using cross-realm authentication, a special group of the form system:authuser@FOREIGN.REALM is created by an administrator and used. if the group quota for this special group is greater than zero, then aklog will automatically register foreign users in the local PTS database, add the foreign user to the system:authuser@FOREIGN.REALM, and decrement the group quota by one. ✨

🍓 EXAMPLES 🍓

this one displays the user entry for "terry" and the machine entry 158.12.105.44:

% pts examine terry 158.12.105.44
Name: terry, id: 1045, owner: system:administrators, creator: admin,
  membership: 9, flags: S----, group quota: 15.
Name: 158.12.105.44, id: 5151, owner: system:administrators,
  creator: byu, membership: 1, flags: S----, group quota: 20.

and this one displays the entries for the AFS groups with GIDs -673 and -674:

% pts examine -673 -674
Name: terry:friends, id: -673, owner: terry, creator: terry,
  membership: 5, flags: S-M--, group quota: 0.
Name: smith:colleagues, id: -674, owner: smith, creator: smith,
  membership: 14, flags: SOM--, group quota: 0.

look at her go 😭💖

👑 PRIVILEGE REQUIRED 👑

what you need depends on the setting of the first privacy flag in the Protection Database entry of each entry you named in the -nameorid argument:

  • if it's lowercase "s", members of the system:administrators group and the user associated with a user entry can examine it, and only members of the system:administrators group can examine a machine or group entry.
  • if it's uppercase "S", anyone who can access the cell's database server machines can examine the entry.

🌟 SEE ALSO 🌟

pts(1), pts_adduser(1), pts_chown(1), pts_creategroup(1), pts_createuser(1), pts_listowned(1), pts_membership(1), pts_removeuser(1), pts_rename(1), pts_setfields(1)

go read them, iykyk 📚✨

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

This documentation is covered by the IBM Public License Version 1.0. It was converted from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.

and that's the whole page, bestie 🫶 brought to you by OpenAFS, dated 2026-07-27, from the AFS Command Reference. mwah. 💅🎀🦋

📦 where this page comes from