1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="HDRWQ531">
3 <title>Administering the Protection Database</title>
5 <para>This chapter explains how to create and maintain user, machine, and group entries in the Protection Database.</para>
8 <title>Summary of Instructions</title>
10 <para>This chapter explains how to perform the following tasks by using the indicated commands:</para>
12 <informaltable frame="none">
14 <colspec colwidth="70*" />
16 <colspec colwidth="30*" />
20 <entry>Display Protection Database entry</entry>
22 <entry><emphasis role="bold">pts examine</emphasis></entry>
26 <entry>Map user, machine or group name to AFS ID</entry>
28 <entry><emphasis role="bold">pts examine</emphasis></entry>
32 <entry>Display entry's owner or creator</entry>
34 <entry><emphasis role="bold">pts examine</emphasis></entry>
38 <entry>Display number of users or machines belonging to group</entry>
40 <entry><emphasis role="bold">pts examine</emphasis></entry>
44 <entry>Display number of groups user or machine belongs to</entry>
46 <entry><emphasis role="bold">pts examine</emphasis></entry>
50 <entry>Display group-creation quota</entry>
52 <entry><emphasis role="bold">pts examine</emphasis></entry>
56 <entry>Display entry's privacy flags</entry>
58 <entry><emphasis role="bold">pts examine</emphasis></entry>
62 <entry>Display members of group, or groups that user or machine belongs to</entry>
64 <entry><emphasis role="bold">pts membership</emphasis></entry>
68 <entry>Display groups that user or group owns</entry>
70 <entry><emphasis role="bold">pts listowned</emphasis></entry>
74 <entry>Display all entries in Protection Database</entry>
76 <entry><emphasis role="bold">pts listentries</emphasis></entry>
80 <entry>Create machine entry</entry>
82 <entry><emphasis role="bold">pts createuser</emphasis></entry>
86 <entry>Create group entry</entry>
88 <entry><emphasis role="bold">pts creategroup</emphasis></entry>
92 <entry>Add users and machines to groups</entry>
94 <entry><emphasis role="bold">pts adduser</emphasis></entry>
98 <entry>Remove users and machines from groups</entry>
100 <entry><emphasis role="bold">pts removeuser</emphasis></entry>
104 <entry>Delete machine or group entry</entry>
106 <entry><emphasis role="bold">pts delete</emphasis></entry>
110 <entry>Change a group's owner</entry>
112 <entry><emphasis role="bold">pts chown</emphasis></entry>
116 <entry>Change an entry's name</entry>
118 <entry><emphasis role="bold">pts rename</emphasis></entry>
122 <entry>Set group creation quota</entry>
124 <entry><emphasis role="bold">pts setfields</emphasis></entry>
128 <entry>Set entry's privacy flags</entry>
130 <entry><emphasis role="bold">pts setfields</emphasis></entry>
134 <entry>Display AFS ID counters</entry>
136 <entry><emphasis role="bold">pts listmax</emphasis></entry>
140 <entry>Set AFS ID counters</entry>
142 <entry><emphasis role="bold">pts setmax</emphasis></entry>
149 <primary>current protection subgroup</primary>
153 <primary>CPS</primary>
157 <primary>Protection Server</primary>
159 <secondary>building CPS</secondary>
163 <primary>File Server</primary>
165 <secondary>CPS requested from Protection Server</secondary>
169 <primary>Protection Database</primary>
171 <secondary>user entry, described</secondary>
175 <primary>user</primary>
177 <secondary>Protection Database entry, described</secondary>
181 <primary>machine</primary>
183 <secondary>Protection Database entry, described</secondary>
187 <primary>Protection Database</primary>
189 <secondary>machine entry, described</secondary>
193 <primary>group</primary>
195 <secondary>Protection Database entry, described</secondary>
199 <primary>Protection Database</primary>
201 <secondary>group entry</secondary>
205 <sect1 id="HDRWQ534">
206 <title>About the Protection Database</title>
208 <para>The Protection Database stores information about AFS users, client machines, and groups which the File Server process uses
209 to determine whether clients are authorized to access AFS data.</para>
211 <para>To obtain authenticated access to an AFS cell, a user must have an entry in the cell's Protection Database. The first time
212 that a user requests access to the data stored on a file server machine, the File Server on that machine contacts the Protection
213 Server to request the user's <emphasis>current protection subgroup</emphasis> (<emphasis>CPS</emphasis>), which lists all the
214 groups to which the user belongs. The File Server scans the access control list (ACL) of the directory that houses the data,
215 looking for groups on the CPS. It grants access in accordance with the permissions that the ACL extends to those groups or to
216 the user individually. (The File Server stores the CPS and uses it as long as the user has the same tokens. When a user's group
217 membership changes, he or she must reauthenticate for the File Server to recognize the change.)</para>
219 <para>Only administrators who belong to the cell's <emphasis role="bold">system:administrators</emphasis> group can create user
220 entries (the group is itself defined in the Protection Database, as discussed in <link linkend="HDRWQ535">The System
221 Groups</link>). Members of the <emphasis role="bold">system:administrators</emphasis> group can also create machine entries,
222 which can then be used to control access based on the machine from which the access request originates. After creating a machine
223 entry, add it to a Protection Database group and place the group on ACLs (a machine cannot appear on ACLs directly). A machine
224 entry can represent a single machine or multiple machines with consecutive IP addresses as specified by a wildcard notation. For
225 instructions, see <link linkend="HDRWQ542">Creating User and Machine Entries</link>. Because all replicas of a volume share the
226 same ACL (the one on the volume's root directory mount point), machine entries enable you to replicate the volume that houses a
227 program's binary file while still complying with a machine-based license agreement as required by the program's manufacturer.
228 See <link linkend="HDRWQ542">Creating User and Machine Entries</link>.</para>
230 <para>A group entry is a list of user entries, machine entries, or both (groups cannot belong to other groups). Putting a group
231 on an ACL is a convenient way to extend or deny access to a set of users without listing them on the ACL individually.
232 Similarly, adding users to a group automatically grants them access to all files and directories for which the associated ACL
233 lists that group. Both administrators and regular users can create groups. <indexterm>
234 <primary>system groups</primary>
236 <secondary>defined</secondary>
237 </indexterm> <indexterm>
238 <primary>group</primary>
240 <secondary>system</secondary>
241 </indexterm> <indexterm>
242 <primary>membership</primary>
244 <secondary>system groups</secondary>
245 </indexterm> <indexterm>
246 <primary>system:anyuser group</primary>
247 </indexterm> <indexterm>
248 <primary>system:authuser group</primary>
249 </indexterm> <indexterm>
250 <primary>system:administrators group</primary>
253 <sect2 id="HDRWQ535">
254 <title>The System Groups</title>
256 <para>In addition to the groups that users and administrators can create, AFS defines the following three system groups. The
257 Protection Server creates them automatically when it builds the first version of a cell's Protection Database, and always
258 assigns them the same AFS GIDs. <variablelist>
260 <term><emphasis role="bold">system:anyuser</emphasis></term>
263 <para>Represents all users able to access the cell's filespace from the local and foreign cells, authenticated or not.
264 Its AFS GID is <emphasis role="bold">-101</emphasis>. The group has no stable membership listed in the Protection
265 Database. Accordingly, the <emphasis role="bold">pts examine</emphasis> command displays <emphasis
266 role="bold">0</emphasis> in its <computeroutput>membership</computeroutput> field, and the <emphasis role="bold">pts
267 membership</emphasis> command does not list any members for it.</para>
269 <para>Placing this group on an ACL is a convenient way to extend access to all users. The File Server automatically
270 places this group on the CPS of any user who requests access to data stored on a file server machine. (Every
271 unauthenticated user is assigned the identity <emphasis role="bold">anonymous</emphasis> and this group is the only
272 entry on the CPS for <emphasis role="bold">anonymous</emphasis>.)</para>
277 <term><emphasis role="bold">system:authuser</emphasis></term>
280 <para>Represents all users who are able to access the cell's filespace from the local and foreign cells and who have
281 successfully obtained an AFS token in the local cell (are authenticated). Its AFS GID is <emphasis
282 role="bold">-102</emphasis>. Like the <emphasis role="bold">system:anyuser</emphasis> group, it has no stable
283 membership listed in the Protection Database. Accordingly, the <emphasis role="bold">pts examine</emphasis> command
284 displays <emphasis role="bold">0</emphasis> in its <computeroutput>membership</computeroutput> field, and the
285 <emphasis role="bold">pts membership</emphasis> command does not list any members for it.</para>
287 <para>Placing this group on an ACL is therefore a convenient way to extend access to all authenticated users. The File
288 Server automatically places this group on the CPS of any authenticated user who requests access to data stored on a
289 file server machine.</para>
294 <term><emphasis role="bold">system:administrators</emphasis></term>
297 <para>Represents the small number of cell administrators authorized to issue privileged <emphasis
298 role="bold">pts</emphasis> commands and the <emphasis role="bold">fs</emphasis> commands that set quota. The ACL on
299 the root directory of every newly created volume grants all permissions to the group. Even if you remove that entry,
300 the group implicitly retains the <emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>), and
301 by default also the <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>), permission on every
302 ACL. Its AFS GID is <emphasis role="bold">-204</emphasis>. For instructions on administering this group, see <link
303 linkend="HDRWQ586">Administering the system:administrators Group</link>.</para>
306 </variablelist></para>
310 <sect1 id="HDRWQ536">
311 <title>Displaying Information from the Protection Database</title>
313 <para>This section describes the commands you can use to display Protection Database entries and associated information. In
314 addition to name and AFS ID, the Protection Database stores the following information about each user, machine, or group entry.
317 <para>The entry's owner, which is the user or group of users who can administer the entry</para>
321 <para>The entry's creator, which serves mostly as an audit trail</para>
325 <para>A membership count, which indicates how many groups a user or machine belongs to, or how many members belong to a
330 <para>A set of privacy flags, which control which users can administer or display information about the entry</para>
334 <para>A group-creation quota, which defines how many groups a user can create</para>
338 <para>A list of the groups to which a user or machine belongs, or of the users and machines that belong to a group</para>
342 <para>A list of the groups that a user or group owns</para>
344 </itemizedlist></para>
347 <primary>displaying</primary>
349 <secondary>Protection Database entry</secondary>
353 <primary>displaying</primary>
355 <secondary>owner of Protection Database entry</secondary>
359 <primary>displaying</primary>
361 <secondary>creator of Protection Database entry</secondary>
365 <primary>displaying</primary>
367 <secondary>privacy flags on Protection Database entry</secondary>
371 <primary>displaying</primary>
373 <secondary>membership count in Protection Database entry</secondary>
377 <primary>displaying</primary>
379 <secondary>group-creation quota in Protection Database entry</secondary>
383 <primary>Protection Database</primary>
385 <secondary>membership count</secondary>
387 <tertiary>displaying</tertiary>
391 <primary>Protection Database</primary>
393 <secondary>group entry</secondary>
395 <tertiary>displaying</tertiary>
399 <primary>Protection Database</primary>
401 <secondary>machine entry</secondary>
403 <tertiary>displaying</tertiary>
407 <primary>Protection Database</primary>
409 <secondary>user entry</secondary>
411 <tertiary>displaying</tertiary>
415 <primary>Protection Database</primary>
417 <secondary>owner of entry</secondary>
419 <tertiary>displaying</tertiary>
423 <primary>Protection Database</primary>
425 <secondary>creator of entry</secondary>
427 <tertiary>displaying</tertiary>
431 <primary>Protection Database</primary>
433 <secondary>privacy flags</secondary>
435 <tertiary>displaying</tertiary>
439 <primary>Protection Database</primary>
441 <secondary>group creation quota</secondary>
443 <tertiary>displaying</tertiary>
447 <primary>mapping</primary>
449 <secondary>AFS ID to group, machine, or username</secondary>
453 <primary>mapping</primary>
455 <secondary>username to AFS UID</secondary>
459 <primary>mapping</primary>
461 <secondary>machine name to AFS UID</secondary>
465 <primary>mapping</primary>
467 <secondary>group name to AFS GID</secondary>
471 <primary>AFS UID</primary>
473 <secondary>displaying</secondary>
475 <tertiary>for one user or machine</tertiary>
479 <primary>AFS GID</primary>
481 <secondary>displaying</secondary>
483 <tertiary>for one group</tertiary>
487 <primary>owner</primary>
489 <secondary>Protection Database entry</secondary>
491 <tertiary>displaying</tertiary>
495 <primary>creator</primary>
497 <secondary>Protection Database entry</secondary>
499 <tertiary>displaying</tertiary>
503 <primary>members</primary>
505 <secondary>group, displaying</secondary>
509 <primary>privacy flags on Protection Database entry</primary>
511 <secondary>displaying</secondary>
515 <primary>group</primary>
517 <secondary>Protection Database entry</secondary>
519 <tertiary>displaying</tertiary>
523 <primary>group</primary>
525 <secondary>owner</secondary>
527 <tertiary>displaying</tertiary>
531 <primary>group</primary>
533 <secondary>creation quota</secondary>
539 <primary>group</primary>
541 <secondary>privacy flags on Protection Database entry</secondary>
543 <tertiary>displaying</tertiary>
547 <primary>machine</primary>
549 <secondary>group memberships</secondary>
551 <tertiary>displaying number</tertiary>
555 <primary>machine</primary>
557 <secondary>Protection Database entry</secondary>
559 <tertiary>displaying</tertiary>
563 <primary>machine</primary>
565 <secondary>privacy flags on Protection Database entry</secondary>
567 <tertiary>displaying</tertiary>
571 <primary>quota</primary>
573 <secondary>group-creation</secondary>
575 <tertiary>displaying</tertiary>
579 <primary>user</primary>
581 <secondary>group-creation quota</secondary>
583 <tertiary>displaying</tertiary>
587 <primary>user</primary>
589 <secondary>Protection Database entry</secondary>
591 <tertiary>displaying</tertiary>
595 <primary>user</primary>
597 <secondary>privacy flags on Protection Database entry</secondary>
599 <tertiary>displaying</tertiary>
603 <primary>user</primary>
605 <secondary>group memberships</secondary>
607 <tertiary>displaying number</tertiary>
611 <primary>pts commands</primary>
613 <secondary>examine</secondary>
617 <primary>commands</primary>
619 <secondary>pts examine</secondary>
622 <sect2 id="HDRWQ537">
623 <title>To display a Protection Database entry</title>
627 <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group, which enables you to
628 display an entry regardless of the setting of its first (<emphasis role="bold">s</emphasis>) privacy flag. By default, any
629 user can display a Protection Database entry. If necessary, issue the <emphasis role="bold">pts membership</emphasis>
630 command, which is fully described in <link linkend="HDRWQ587">To display the members of the system:administrators
631 group</link>. <programlisting>
632 % <emphasis role="bold">pts membership system:administrators</emphasis>
633 </programlisting></para>
637 <para>Issue the <emphasis role="bold">pts examine</emphasis> command to display one or more Protection Database entries.
639 % <emphasis role="bold">pts examine</emphasis> <<replaceable>user or group name or id</replaceable>>+
640 </programlisting></para>
646 <term><emphasis role="bold">e</emphasis></term>
649 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">examine</emphasis> (and <emphasis
650 role="bold">check</emphasis> is an alias).</para>
655 <term><emphasis role="bold">user or group name or id</emphasis></term>
658 <para>Specifies the name or AFS ID of each entry to display. Precede any AFS GID with a hyphen (<emphasis
659 role="bold">-</emphasis>) because it is a negative integer.</para>
666 <para>The output includes the following fields. Examples follow. <variablelist>
668 <term><emphasis role="bold"><computeroutput>Name</computeroutput></emphasis></term>
671 <para>Specifies the entry's name. <itemizedlist>
673 <para>For a user, this is the name used when authenticating with AFS and the name that appears on ACL
678 <para>For a machine, this is the IP address of a single machine, or a wildcard notation that represents a group
679 of machines with consecutive IP addresses, as described in <link linkend="HDRWQ542">Creating User and Machine
680 Entries</link>.</para>
684 <para>For a group, this is the name that appears on ACL entries and in the list of groups output by the
685 <emphasis role="bold">pts membership</emphasis> command. The names of <emphasis>regular</emphasis> groups have
686 two parts, separated by a colon (<emphasis role="bold">:</emphasis>). The part before the colon indicates the
687 group's owner, and the part after is the unique name. A <emphasis>prefix-less</emphasis> group's name does not
688 have the owner prefix; only members of the <emphasis role="bold">system:administrators</emphasis> group can
689 create prefix-less groups. For further discussion of group names, see <link linkend="HDRWQ544">Creating
690 Groups</link>.</para>
692 </itemizedlist></para>
695 <primary>AFS UID</primary>
697 <secondary>definition</secondary>
701 <primary>AFS GID</primary>
703 <secondary>definition</secondary>
707 <primary>UNIX UID</primary>
709 <secondary>difference from AFS UID</secondary>
715 <term><emphasis role="bold"><computeroutput>id</computeroutput></emphasis></term>
718 <para>Specifies the entry's unique AFS identification number. For user and machine entries, the AFS user ID (AFS UID)
719 is a positive integer; for groups, the AFS group ID (AFS GID) is a negative integer. AFS UIDs and GIDs have the same
720 function as their counterparts in the UNIX file system, but are used by the AFS servers and the Cache Manager
723 <para>Normally, the Protection Server assigns an AFS UID or GID automatically when you create Protection Database
724 entries. Members of the <emphasis role="bold">system:administrators</emphasis> group can specify an ID if desired. For
725 further discussion, see <link linkend="HDRWQ542">Creating User and Machine Entries</link> and <link
726 linkend="HDRWQ544">Creating Groups</link>.</para>
731 <term><emphasis role="bold"><computeroutput>owner</computeroutput></emphasis></term>
734 <para>Names the user or group who owns the entry and therefore can administer it (for more information about a group
735 owning another group, see <link linkend="HDRWQ545">Using Groups Effectively</link>). Other users possibly have
736 administrative privileges, too, depending on the setting of the entry's privacy flags. For instructions on changing
737 the owner, see <link linkend="HDRWQ554">Changing a Group's Owner</link>.</para>
742 <term><emphasis role="bold"><computeroutput>creator</computeroutput></emphasis></term>
745 <para>Names the user who created the entry, and serves as an audit trail. If the entry is deleted from the Protection
746 Database, the creator's group creation quota increases by one, even if the creator no longer owns the entry; see <link
747 linkend="HDRWQ558">Setting Group-Creation Quota</link>.</para>
749 <para>The value <computeroutput>anonymous</computeroutput> in this field generally indicates that the entry was
750 created when the Protection Server was running in no-authentication mode, probably during initial configuration of the
751 cell's first file server machine. For a description of no-authentication mode, see <link linkend="HDRWQ123">Managing
752 Authentication and Authorization Requirements</link>.</para>
757 <term><emphasis role="bold"><computeroutput>membership</computeroutput></emphasis></term>
760 <para>Specifies the number of groups to which the user or machine belongs, or the number of users or machines that
761 belong to the group.</para>
766 <term><emphasis role="bold"><computeroutput>flags</computeroutput></emphasis></term>
769 <para>Specifies who can display or change information in a Protection Database entry. The five flags, each
770 representing a different capability, always appear in the same order. <itemizedlist>
772 <para>For user entries, the default value is <computeroutput>S----</computeroutput>, which indicates that anyone
773 can issue the <emphasis role="bold">pts examine</emphasis> command on the entry, but only the user and members
774 of the <emphasis role="bold">system:administrators</emphasis> group can perform any other action.</para>
778 <para>For machine entries, the default value is <computeroutput>S----</computeroutput>, which indicates that
779 anyone can issue the <emphasis role="bold">pts examine</emphasis> command on the entry, but only members of the
780 <emphasis role="bold">system:administrators</emphasis> group can perform any other action.</para>
784 <para>For group entries, the default value is <computeroutput>S-M--</computeroutput>, which indicates that
785 anyone can issue the <emphasis role="bold">pts examine</emphasis> and <emphasis role="bold">pts
786 membership</emphasis> commands on the entry, but only the group's owner and members of the <emphasis
787 role="bold">system:administrators</emphasis> group can perform any other action.</para>
789 </itemizedlist></para>
791 <para>For a complete description of possible values for the flags, see <link linkend="HDRWQ559">Setting the Privacy
792 Flags on Database Entries</link>.</para>
797 <term><emphasis role="bold"><computeroutput>group quota</computeroutput></emphasis></term>
800 <para>Specifies how many more groups a user can create in the Protection Database. The value for a newly created user
801 entry is 20, but members of the <emphasis role="bold">system:administrators</emphasis> group can issue the <emphasis
802 role="bold">pts setfields</emphasis> command at any time to change the value; see <link linkend="HDRWQ558">Setting
803 Group-Creation Quota</link>.</para>
805 <para>Group creation quota has no meaning for a machine or group entry: the Protection Server recognizes the issuer of
806 the <emphasis role="bold">pts creategroup</emphasis> command only as an authenticated user or as the <emphasis
807 role="bold">anonymous</emphasis> user, never as a machine or group. The default value for group entries is 0 (zero),
808 and there is no reason to change it.</para>
811 </variablelist></para>
813 <para>The following examples show the output for a user called <emphasis role="bold">pat</emphasis>, a machine with IP address
814 <emphasis role="bold">192.12.108.133</emphasis> and a group called <emphasis role="bold">terry:friends</emphasis>:</para>
817 % <emphasis role="bold">pts examine pat</emphasis>
818 Name: pat, id: 1020, owner: system:administrators, creator: admin,
819 membership: 12, flags: S----, group quota: 15.
820 % <emphasis role="bold">pts ex 192.12.108.133</emphasis>
821 Name: 192.12.108.133, id: 5151, owner: system:administrators, creator: admin,
822 membership: 1, flags: S----, group quota: 20.
823 % <emphasis role="bold">pts examine terry:friends</emphasis>
824 Name: terry:friends, id: -567, owner: terry, creator: terry,
825 membership: 12, flags: SOm--, group quota: 0.
829 <primary>displaying</primary>
831 <secondary>groups to which user or machine belongs</secondary>
835 <primary>displaying</primary>
837 <secondary>members of group</secondary>
841 <primary>group</primary>
843 <secondary>members, displaying</secondary>
847 <primary>group</primary>
849 <secondary>membership of machine or user, displaying</secondary>
853 <primary>user</primary>
855 <secondary>group memberships, displaying</secondary>
859 <primary>machine</primary>
861 <secondary>group memberships, displaying</secondary>
865 <primary>members</primary>
867 <secondary>group, displaying</secondary>
871 <primary>pts commands</primary>
873 <secondary>membership</secondary>
877 <primary>commands</primary>
879 <secondary>pts membership</secondary>
883 <sect2 id="HDRWQ538">
884 <title>To display group membership</title>
888 <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group, which enables you to
889 display an entry's group membership information regardless of the setting of its third (<emphasis
890 role="bold">m</emphasis>) privacy flag. By default the owner and the user can display group membership for a user entry,
891 the owner for a machine entry, and anyone for a group entry. If necessary, issue the <emphasis role="bold">pts
892 membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To display the members of the
893 system:administrators group</link>. <programlisting>
894 % <emphasis role="bold">pts membership system:administrators</emphasis>
895 </programlisting></para>
899 <para><anchor id="LIWQ539" />Issue the <emphasis role="bold">pts membership</emphasis> command to display the list of
900 groups to which a user or machine belongs, or the list of users and machines that belong to a group. <programlisting>
901 % <emphasis role="bold">pts membership</emphasis> <<replaceable>user or group name or id</replaceable>>+
902 </programlisting></para>
908 <term><emphasis role="bold">m</emphasis></term>
911 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">membership</emphasis>.</para>
916 <term><emphasis role="bold">user or group name or id</emphasis></term>
919 <para>Specifies the name or AFS UID of each user or machine for which to list the groups it belongs to, or the name
920 or AFS GID of each group for which to list the members.</para>
927 <para>For user and machine entries, the output begins with the following string, and then each group appears on its own
931 Groups user_or_machine (id: AFS_UID) is a member of:
934 <para>For group entries, the output begins with the following string, and then each member appears on its own line:</para>
937 Members of group (id: AFS_GID) are:
940 <para>For the system groups <emphasis role="bold">system:anyuser</emphasis> and <emphasis
941 role="bold">system:authuser</emphasis>, the output includes the initial header string only, because these groups do not have a
942 stable membership listed in their Protection Database entry. See <link linkend="HDRWQ535">The System Groups</link>.</para>
944 <para>The following examples show the output for a user called <emphasis role="bold">terry</emphasis> and a group called
945 <emphasis role="bold">terry:friends</emphasis>:</para>
948 % <emphasis role="bold">pts mem terry</emphasis>
949 Groups terry (id: 5347) is a member of:
953 % <emphasis role="bold">pts mem terry:friends</emphasis>
954 Members of terry:friends (id: -567) are:
961 <primary>group</primary>
963 <secondary>groups owned, displaying</secondary>
967 <primary>displaying</primary>
969 <secondary>groups owned by a user or group</secondary>
973 <primary>group</primary>
975 <secondary>orphaned, displaying</secondary>
979 <primary>orphaned group</primary>
983 <primary>user</primary>
985 <secondary>groups owned, displaying</secondary>
989 <primary>group</primary>
991 <secondary>owned by user or group, displaying</secondary>
995 <primary>pts commands</primary>
997 <secondary>listowned</secondary>
1001 <primary>commands</primary>
1003 <secondary>pts listowned</secondary>
1007 <sect2 id="HDRWQ540">
1008 <title>To list the groups that a user or group owns</title>
1012 <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group, which enables you to
1013 display an entry's group ownership information regardless of the setting of its second (<emphasis
1014 role="bold">o</emphasis>) privacy flag. By default the owner can list the groups owned by group, and a user the groups he
1015 or she owns. If necessary, issue the <emphasis role="bold">pts membership</emphasis> command, which is fully described in
1016 <link linkend="HDRWQ587">To display the members of the system:administrators group</link>. <programlisting>
1017 % <emphasis role="bold">pts membership system:administrators</emphasis>
1018 </programlisting></para>
1022 <para>Issue the <emphasis role="bold">pts listowned</emphasis> command to list the groups owned by each user or group.
1024 % <emphasis role="bold">pts listowned</emphasis> <<replaceable>user or group name or id</replaceable>>+
1025 </programlisting></para>
1031 <term><emphasis role="bold">listo</emphasis></term>
1034 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">listowned</emphasis>.</para>
1039 <term><emphasis role="bold">user or group name or id</emphasis></term>
1042 <para>Specifies the name or AFS UID of each user, or the name or AFS GID or each group, for which to list the groups
1050 <para>The output begins with the following string, and then each group appears on its own line:</para>
1053 Groups owned by user_or_group (id: AFS_ID) are:
1056 <para>The following examples show the output for a user called <emphasis role="bold">terry</emphasis> and a group called
1057 <emphasis role="bold">terry:friends</emphasis>:</para>
1060 % <emphasis role="bold">pts listo terry</emphasis>
1061 Groups owned by terry (id: 5347) are:
1064 % <emphasis role="bold">pts listo terry:friends</emphasis>
1065 Groups owned by terry:friends (id: -567) are:
1071 <primary>displaying</primary>
1073 <secondary>Protection Database entries (all)</secondary>
1077 <primary>displaying</primary>
1079 <secondary>owner of Protection Database entry</secondary>
1083 <primary>displaying</primary>
1085 <secondary>creator of Protection Database entry</secondary>
1089 <primary>Protection Database</primary>
1091 <secondary>group entry</secondary>
1093 <tertiary>displaying all</tertiary>
1097 <primary>Protection Database</primary>
1099 <secondary>machine entry</secondary>
1101 <tertiary>displaying all</tertiary>
1105 <primary>Protection Database</primary>
1107 <secondary>user entry</secondary>
1109 <tertiary>displaying all</tertiary>
1113 <primary>Protection Database</primary>
1115 <secondary>owner of entry</secondary>
1117 <tertiary>displaying for all</tertiary>
1121 <primary>Protection Database</primary>
1123 <secondary>creator of entry</secondary>
1125 <tertiary>displaying for all</tertiary>
1129 <primary>AFS UID</primary>
1131 <secondary>displaying</secondary>
1133 <tertiary>for all users and machines in Protection Database</tertiary>
1137 <primary>AFS GID</primary>
1139 <secondary>displaying</secondary>
1141 <tertiary>for all groups in Protection Database</tertiary>
1145 <primary>owner</primary>
1147 <secondary>Protection Database entry</secondary>
1149 <tertiary>displaying all</tertiary>
1153 <primary>creator</primary>
1155 <secondary>Protection Database entry</secondary>
1157 <tertiary>displaying all</tertiary>
1161 <primary>group</primary>
1163 <secondary>Protection Database entry</secondary>
1165 <tertiary>displaying all</tertiary>
1169 <primary>group</primary>
1171 <secondary>owner</secondary>
1173 <tertiary>displaying for all</tertiary>
1177 <primary>machine</primary>
1179 <secondary>Protection Database entry</secondary>
1181 <tertiary>displaying all</tertiary>
1185 <primary>user</primary>
1187 <secondary>Protection Database entry</secondary>
1189 <tertiary>displaying all</tertiary>
1193 <primary>pts commands</primary>
1195 <secondary>listentries</secondary>
1199 <primary>commands</primary>
1201 <secondary>pts listentries</secondary>
1205 <sect2 id="HDRWQ541">
1206 <title>To display all Protection Database entries</title>
1210 <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
1211 <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To display
1212 the members of the system:administrators group</link>. <programlisting>
1213 % <emphasis role="bold">pts membership system:administrators</emphasis>
1214 </programlisting></para>
1218 <para>Issue the <emphasis role="bold">pts listentries</emphasis> command to display all Protection Database entries.
1220 % <emphasis role="bold">pts listentries</emphasis> [<emphasis role="bold">-users</emphasis>] [<emphasis role="bold">-groups</emphasis>]
1221 </programlisting></para>
1227 <term><emphasis role="bold">liste</emphasis></term>
1230 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">listentries</emphasis>.</para>
1235 <term><emphasis role="bold">-users</emphasis></term>
1238 <para>Displays user and machine entries. The same output results if you omit both this flag and the <emphasis
1239 role="bold">-groups</emphasis> flag.</para>
1244 <term><emphasis role="bold">-groups</emphasis></term>
1247 <para>Displays group entries.</para>
1254 <para>The output is a table that includes the following columns. Examples follow. <variablelist>
1256 <term><emphasis role="bold"><computeroutput>Name</computeroutput></emphasis></term>
1259 <para>Specifies the entry's name.</para>
1264 <term><emphasis role="bold"><computeroutput>ID</computeroutput></emphasis></term>
1267 <para>Specifies the entry's AFS identification number. For user and machine entries, the AFS user ID (AFS UID) is a
1268 positive integer; for groups, the AFS group ID (AFS GID) is a negative integer.</para>
1273 <term><emphasis role="bold"><computeroutput>Owner</computeroutput></emphasis></term>
1276 <para>Specifies the AFS ID of the user or group who owns the entry and therefore can administer it.</para>
1281 <term><emphasis role="bold"><computeroutput>Creator</computeroutput></emphasis></term>
1284 <para>Specifies the AFS UID of the user who created the entry.</para>
1287 </variablelist></para>
1289 <para>The following example is from the ABC Corporation cell. The issuer provides no options, so the output includes user and
1290 machine entries.</para>
1293 % <emphasis role="bold">pts listentries</emphasis>
1294 Name ID Owner Creator
1295 anonymous 32766 -204 -204
1301 192.12.105.33 2000 -204 1
1302 192.12.105.46 2001 -204 1
1306 <primary>creating</primary>
1308 <secondary>Protection Database machine entry</secondary>
1312 <primary>Protection Database</primary>
1314 <secondary>machine entry, creating</secondary>
1318 <primary>assigning</primary>
1320 <secondary>AFS UID to machine</secondary>
1324 <primary>machine</primary>
1326 <secondary>Protection Database entry, creating</secondary>
1330 <primary>machine</primary>
1332 <secondary>AFS UID, assigning</secondary>
1337 <sect1 id="HDRWQ542">
1338 <title>Creating User and Machine Entries</title>
1340 <para>An entry in the Protection Database is one of the two required components of every AFS user account, along with an entry
1341 in the Authentication Database. It is best to create a Protection Database user entry only in the context of creating a complete
1342 user account, by using the <emphasis role="bold">uss add</emphasis> or <emphasis role="bold">uss bulk</emphasis> command as
1343 described in <link linkend="HDRWQ449">Creating and Deleting User Accounts with the uss Command Suite</link>, or the <emphasis
1344 role="bold">pts createuser</emphasis> command as described in <link linkend="HDRWQ502">Creating AFS User Accounts</link>.</para>
1346 <para>You can also use the <emphasis role="bold">pts createuser</emphasis> command to create Protection Database machine
1347 entries, which can then be used to control access based on the machine from which the access request originates. After creating
1348 a machine entry, add it to a Protection Database group and place the group on ACLs ( a machine cannot appear on ACLs directly).
1349 Because all replicas of a volume share the same ACL (the one on the volume's root directory mount point), you can replicate the
1350 volume that houses a program's binary file while still complying with a machine-based license agreement as required by the
1351 program's manufacturer. If you do not place any other entries on the ACL, then only users working on the designated machines can
1352 access the file.</para>
1354 <para>Keep in mind that creating an ACL entry for a group with machine entries in it extends access to both authenticated and
1355 unauthenticated users working on the machine. However, you can deny access to unauthenticated users by omitting an entry for the
1356 <emphasis role="bold">system:anyuser</emphasis> group from the ACLs of the parent directories in the file's pathname.
1357 Conversely, if you want to enable unauthenticated users on the machine to access a file, then the ACL on every directory leading
1358 to it must include an entry for either the <emphasis role="bold">system:anyuser</emphasis> group or a group to which the machine
1359 entry belongs. For more information on the <emphasis role="bold">system:anyuser</emphasis> group, see <link
1360 linkend="HDRWQ535">The System Groups</link>.</para>
1362 <para>Because a machine entry can include unauthenticated users, it is best not to add both machine entries and user entries to
1363 the same group. In general, it is easier to use and administer nonmixed groups. A machine entry can represent a single machine,
1364 or multiple machines with consecutive IP addresses (that is, all machines on a network or subnet) specified by a wildcard
1365 notation. See the instructions in <link linkend="HDRWQ543">To create machine entries in the Protection Database</link>.</para>
1367 <para>By default, the Protection Server assigns the next available AFS UID to a new user or machine entry. It is best to allow
1368 this, especially for machine entries. For user entries, it makes sense to assign an AFS UID only if the user already has a UNIX
1369 UID that the AFS UID needs to match (see <link linkend="HDRWQ496">Assigning AFS and UNIX UIDs that Match</link>). When
1370 automatically allocating an AFS UID, the Protection Server increments the <computeroutput>max user id</computeroutput> counter
1371 by one and assigns the result to the new entry. Use the <emphasis role="bold">pts listmax</emphasis> command to display the
1372 counter, as described in <link linkend="HDRWQ560">Displaying and Setting the AFS UID and GID Counters</link>. <indexterm>
1373 <primary>AFS UID</primary>
1375 <secondary>reusing, about</secondary>
1378 <para>Do not reuse the AFS UIDs of users who have left your cell permanently or machine entries you have removed, even though
1379 doing so seems to avoid the apparent waste of IDs. When you remove a user or machine entry from the Protection Database, the
1380 <emphasis role="bold">fs listacl</emphasis> command displays the AFS UID associated with the former entry, rather than the name.
1381 If you then assign the AFS UID to a new user or machine, the new user or machine automatically inherits permissions that were
1382 granted to the previous possessor of the ID. To remove obsolete AFS UIDs from ACLs, use the <emphasis role="bold">fs
1383 cleanacl</emphasis> command described in <link linkend="HDRWQ579">Removing Obsolete AFS IDs from ACLs</link>.</para>
1385 <para>In addition to the name and AFS UID, the Protection Server records the following values in the indicated fields of a new
1386 user or machine's entry. For more information and instructions on displaying an entry, see <link linkend="HDRWQ537">To display a
1387 Protection Database entry</link>. <itemizedlist>
1389 <para>It sets the <computeroutput>owner</computeroutput> field to the <emphasis
1390 role="bold">system:administrators</emphasis> group, indicating that the group's members administer the entry.</para>
1394 <para>It sets the <computeroutput>creator</computeroutput> field to the username of the user who issued the <emphasis
1395 role="bold">pts createuser</emphasis> command (or the <emphasis role="bold">uss add</emphasis> or <emphasis
1396 role="bold">uss bulk</emphasis> command).</para>
1400 <para>It sets the <computeroutput>membership</computeroutput> field to <emphasis role="bold">0</emphasis> (zero), because
1401 the new entry does not yet belong to any groups.</para>
1405 <para>It sets the <computeroutput>flags</computeroutput> field to <emphasis role="bold">S----</emphasis>; for explanation,
1406 see <link linkend="HDRWQ559">Setting the Privacy Flags on Database Entries</link>.</para>
1410 <para>It sets the <computeroutput>group quota</computeroutput> field to <emphasis role="bold">20</emphasis>, meaning that
1411 the new user can create 20 groups. This field has no meaning for machine entries. For further discussion, see <link
1412 linkend="HDRWQ558">Setting Group-Creation Quota</link>.</para>
1414 </itemizedlist></para>
1417 <primary>pts commands</primary>
1419 <secondary>createuser</secondary>
1421 <tertiary>machine entry</tertiary>
1425 <primary>commands</primary>
1427 <secondary>pts createuser</secondary>
1429 <tertiary>machine entry</tertiary>
1432 <sect2 id="HDRWQ543">
1433 <title>To create machine entries in the Protection Database</title>
1437 <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
1438 <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To display
1439 the members of the system:administrators group</link>. <programlisting>
1440 % <emphasis role="bold">pts membership system:administrators</emphasis>
1441 </programlisting></para>
1445 <para>Issue the <emphasis role="bold">pts createuser</emphasis> command to create one or more machine entries.
1447 % <emphasis role="bold">pts createuser -name</emphasis> <<replaceable>user name</replaceable>>+
1448 </programlisting></para>
1454 <term><emphasis role="bold">cu</emphasis></term>
1457 <para>Is an alias for <emphasis role="bold">createuser</emphasis> (and <emphasis role="bold">createu</emphasis> is
1458 the shortest acceptable abbreviation).</para>
1463 <term><emphasis role="bold">-name</emphasis></term>
1466 <para>Specifies an IP address in dotted-decimal notation for each machine entry. An entry can represent a single
1467 machine or a set of several machines with consecutive IP addresses, using the wildcard notation described in the
1468 following list. The letters <emphasis role="bold">W</emphasis>, <emphasis role="bold">X</emphasis>, <emphasis
1469 role="bold">Y</emphasis>, and <emphasis role="bold">Z</emphasis> each represent an actual number value in the field:
1472 <para><emphasis role="bold">W.X.Y.Z</emphasis> represents a single machine, for example <emphasis
1473 role="bold">192.12.108.240</emphasis>.</para>
1477 <para><emphasis role="bold">W.X.Y.0</emphasis> matches all machines whose IP addresses start with the first
1478 three numbers. For example, <emphasis role="bold">192.12.108.0</emphasis> matches both <emphasis
1479 role="bold">192.12.108.119</emphasis> and <emphasis role="bold">192.12.108.120</emphasis>, but does not match
1480 <emphasis role="bold">192.12.105.144</emphasis>.</para>
1484 <para><emphasis role="bold">W.X.0.0</emphasis> matches all machines whose IP addresses start with the first
1485 two numbers. For example, the address <emphasis role="bold">192.12.0.0</emphasis> matches both <emphasis
1486 role="bold">192.12.106.23</emphasis> and <emphasis role="bold">192.12.108.120</emphasis>, but does not match
1487 <emphasis role="bold">192.5.30.95</emphasis>.</para>
1491 <para><emphasis role="bold">W.0.0.0</emphasis> matches all machines whose IP addresses start with the first
1492 number in the specified address. For example, the address <emphasis role="bold">192.0.0.0</emphasis> matches
1493 both <emphasis role="bold">192.5.30.95</emphasis> and <emphasis role="bold">192.12.108.120</emphasis>, but
1494 does not match <emphasis role="bold">138.255.63.52</emphasis>.</para>
1496 </itemizedlist></para>
1498 <para>Do not define a machine entry with the name <emphasis role="bold">0.0.0.0</emphasis> to match every machine.
1499 The <emphasis role="bold">system:anyuser</emphasis> group is equivalent.</para>
1506 <para>The following example creates a machine entry that includes all of the machines in the <emphasis
1507 role="bold">192.12</emphasis> network.</para>
1510 % <emphasis role="bold">pts cu 192.12.0.0</emphasis>
1514 <primary>creating</primary>
1516 <secondary>Protection Database group entry</secondary>
1520 <primary>Protection Database</primary>
1522 <secondary>group entry, creating</secondary>
1526 <primary>assigning</primary>
1528 <secondary>AFS GID to group</secondary>
1532 <primary>group</primary>
1534 <secondary>Protection Database entry, creating</secondary>
1538 <primary>group</primary>
1540 <secondary>AFS GID, assigning</secondary>
1544 <primary>group</primary>
1546 <secondary>name, assigning</secondary>
1550 <primary>group</primary>
1552 <secondary>regular and prefix-less, defined</secondary>
1556 <primary>regular group</primary>
1558 <secondary></secondary>
1564 <primary>prefix-less group</primary>
1566 <secondary></secondary>
1573 <sect1 id="HDRWQ544">
1574 <title>Creating Groups</title>
1576 <para>Before you can add members to a group, you must create the group entry itself. The instructions in this section explain
1577 how to create both regular and prefix-less groups: <itemizedlist>
1579 <para>A <emphasis>regular group</emphasis>'s name is preceded by a prefix that indicates who owns the group, in the
1580 following format:</para>
1582 <para>owner_name<emphasis role="bold">:</emphasis>group_name</para>
1584 <para>Any user can create a regular group. Group names must always be typed in full, so a short group_name that indicates
1585 the group's purpose or its members' common interest is practical. Groups with names like <emphasis
1586 role="bold">terry:1</emphasis> and <emphasis role="bold">terry:2</emphasis> are less useful because their purpose is
1587 unclear. For more details on the required format for regular group names, see the instructions in <link
1588 linkend="HDRWQ546">To create groups</link>.</para>
1592 <para>A <emphasis>prefix-less group</emphasis>, as its name suggests, has only one field in its name, equivalent to a
1593 regular group's group_name field.</para>
1595 <para>Only members of the <emphasis role="bold">system:administrators</emphasis> group can create prefix-less groups. For
1596 a discussion of their purpose, see <link linkend="HDRWQ548">Using Prefix-Less Groups</link>.</para>
1598 </itemizedlist></para>
1600 <para>By default, the Protection Server assigns the next available AFS GID to a new group entry, and it is best to allow this.
1601 When automatically allocating an AFS GID (which is a negative integer), the Protection Server decrements the <computeroutput>max
1602 group id</computeroutput> counter by one and assigns the result to the new group. Use the <emphasis role="bold">pts
1603 listmax</emphasis> command to display the counter, as described in <link linkend="HDRWQ560">Displaying and Setting the AFS UID
1604 and GID Counters</link>.</para>
1606 <para>In addition to the name and AFS GID, the Protection Server records the following values in the indicated fields of a new
1607 group's entry. See <link linkend="HDRWQ537">To display a Protection Database entry</link>. <itemizedlist>
1609 <para>It sets the <computeroutput>owner</computeroutput> field to the issuer of the <emphasis role="bold">pts
1610 creategroup</emphasis> command, or to the user or group specified by the <emphasis role="bold">-owner</emphasis>
1615 <para>It sets the <computeroutput>creator</computeroutput> field to the username of the user who issued the <emphasis
1616 role="bold">pts creategroup</emphasis> command.</para>
1620 <para>It sets the <computeroutput>membership</computeroutput> field to <emphasis role="bold">0</emphasis> (zero), because
1621 the group currently has no members.</para>
1625 <para>It sets the <computeroutput>flags</computeroutput> field to <emphasis role="bold">S-M--</emphasis>; for explanation,
1626 see <link linkend="HDRWQ559">Setting the Privacy Flags on Database Entries</link>.</para>
1630 <para>It sets the <computeroutput>group quota</computeroutput> field to <emphasis role="bold">0</emphasis>, because this
1631 field has no meaning for group entries.</para>
1633 </itemizedlist></para>
1636 <primary>group</primary>
1638 <secondary>using effectively</secondary>
1642 <primary>private use of group</primary>
1646 <primary>group</primary>
1648 <secondary>private use</secondary>
1652 <primary>shared use of group</primary>
1656 <primary>group</primary>
1658 <secondary>shared use</secondary>
1662 <primary>group use of group</primary>
1666 <primary>group</primary>
1668 <secondary>group use</secondary>
1672 <primary>self-owned group</primary>
1675 <sect2 id="HDRWQ545">
1676 <title>Using Groups Effectively</title>
1678 <para>The main reason to create groups is to place them on ACLs, which enables you to control access for multiple users
1679 without having to list them individually on the ACL. There are three basic ways to use groups, each suited to a different
1680 purpose: <itemizedlist>
1682 <para><emphasis>Private use</emphasis>: you create a group and place it on the ACL of directories you own, without
1683 necessarily informing the group's members that they belong to it. Members notice only that they can or cannot access the
1684 directory in a certain way. You retain sole administrative control over the group, since you are the owner.</para>
1686 <para>The existence of the group and the identity of its members is not necessarily secret. Other users can use the
1687 <emphasis role="bold">fs listacl</emphasis> command and see the group's name on a directory's ACL, or use the <emphasis
1688 role="bold">pts membership</emphasis> command to list the groups they themselves belong to. You can set the group's
1689 third privacy flag to limit who can use the <emphasis role="bold">pts membership</emphasis> command to list the group's
1690 membership, but a member of the <emphasis role="bold">system:administrators</emphasis> group always can; see <link
1691 linkend="HDRWQ559">Setting the Privacy Flags on Database Entries</link>.</para>
1695 <para><emphasis>Shared use</emphasis>: you inform the group's members that they belong to the group, but you still
1696 remain the sole administrator. For example, the manager of a work group can create a group of all the members in the
1697 work group, and encourage them to use it on the ACLs of directories that house information they want to share with other
1698 members of the group.</para>
1701 <para>If you place a group owned by someone else on your ACLs, the group's owner can change the group's membership
1702 without informing you. Someone new can gain or lose access in a way you did not intend and without your
1708 <para><emphasis>Group use</emphasis>: you create a group and then use the <emphasis role="bold">pts chown</emphasis>
1709 command to assign ownership to a group, either another group or the group itself (the latter type is a self-owned
1710 group). You inform the members of the owning group that they all can administer the owned group.</para>
1712 <para>The main advantage of designating a group as an owner is that it spreads responsibility for administering a group
1713 among several people. A single person does not have to perform all administrative tasks, and if the original creator
1714 leaves the group, ownership does not have to be transferred.</para>
1716 <para>However, everyone in the owner group can make changes that affect others negatively, such as adding or removing
1717 people from the group inappropriately or changing the group's ownership to themselves exclusively. These problems can be
1718 particularly sensitive in a <emphasis>self-owned</emphasis> group. Using an owner group works best if all the members
1719 know and trust each other; it is probably wise to keep the number of people in an owner group small.</para>
1721 </itemizedlist></para>
1724 <primary>pts commands</primary>
1726 <secondary>creategroup</secondary>
1730 <primary>commands</primary>
1732 <secondary>pts creategroup</secondary>
1736 <sect2 id="HDRWQ546">
1737 <title>To create groups</title>
1741 <para>If creating a prefix-less group, verify that you belong to the <emphasis
1742 role="bold">system:administrators</emphasis> group. If necessary, issue the <emphasis role="bold">pts
1743 membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To display the members of the
1744 system:administrators group</link>. <programlisting>
1745 % <emphasis role="bold">pts membership system:administrators</emphasis>
1746 </programlisting></para>
1750 <para>Issue the <emphasis role="bold">pts creategroup</emphasis> command to create each group. All of the groups have the
1751 same owner. <programlisting>
1752 % <emphasis role="bold">pts creategroup -name</emphasis> <<replaceable>group name</replaceable>>+ [<emphasis role="bold">-owner</emphasis> <<replaceable>owner of the group</replaceable>>]
1753 </programlisting></para>
1759 <term><emphasis role="bold">cg</emphasis></term>
1762 <para>Is an alias for <emphasis role="bold">creategroup</emphasis> (and <emphasis role="bold">createg</emphasis> is
1763 the shortest acceptable abbreviation). <indexterm>
1764 <primary>owner</primary>
1766 <secondary>Protection Database entry</secondary>
1768 <tertiary>rules for assigning</tertiary>
1769 </indexterm> <indexterm>
1770 <primary>rules</primary>
1772 <secondary>group names, assigning</secondary>
1773 </indexterm> <indexterm>
1774 <primary>group</primary>
1776 <secondary>rules for naming</secondary>
1782 <term><emphasis role="bold">-name</emphasis></term>
1785 <para>Names each group to create. The name can include up to 63 lowercase letters or numbers, but it is best not to
1786 include punctuation characters, especially those that have a special meaning to the shell.</para>
1788 <para>A prefix-less group name cannot include the colon (<emphasis role="bold">:</emphasis>), because it is used to
1789 separate the two parts of a regular group name:</para>
1791 <para>owner_name<emphasis role="bold">:</emphasis>group_name</para>
1793 <para>The Protection Server requires that the owner_name prefix of a regular group name accurately indicate the
1794 group's owner. By default, you are recorded as the owner, and the owner_name must be your AFS username. You can
1795 include the <emphasis role="bold">-owner</emphasis> argument to designate another AFS user, a regular group, or a
1796 prefix-less group as the owner, providing the required value in the owner_name field: <itemizedlist>
1798 <para>If the owner is a user, it must be the AFS username.</para>
1802 <para>If the owner is another regular group, it must match the owning group's owner_name field. For example,
1803 if the owner is the group <emphasis role="bold">terry:associates</emphasis>, the owner field must be <emphasis
1804 role="bold">terry</emphasis>.</para>
1808 <para>If the owner is a prefix-less group, it must be the owning group's name.</para>
1810 </itemizedlist></para>
1812 <para>(For a discussion of why it is useful for a group to own another group, see <link linkend="HDRWQ545">Using
1813 Groups Effectively</link>.)</para>
1818 <term><emphasis role="bold">-owner</emphasis></term>
1821 <para>Is optional and designates an owner other than the issuer of the command. Specify either an AFS username or
1822 the name of a regular or prefix-less group that already has at least one member. Do not include this argument if you
1823 want to make the group self-owned as described in <link linkend="HDRWQ545">Using Groups Effectively</link>. For
1824 instructions, see <link linkend="HDRWQ547">To create a self-owned group</link>.</para>
1826 <para>Do not designate a machine as a group's owner. Because a machine cannot authenticate, there is no way for a
1827 machine to administer the group.</para>
1835 <primary>group</primary>
1837 <secondary>self-owned, creating</secondary>
1841 <primary>creating</primary>
1843 <secondary>group, self-owned</secondary>
1847 <primary>changing</primary>
1849 <secondary>group ownership to self-owned</secondary>
1853 <sect2 id="HDRWQ547">
1854 <title>To create a self-owned group</title>
1858 <para>Issue the <emphasis role="bold">pts creategroup</emphasis> command to create a group. Do not include the <emphasis
1859 role="bold">-owner</emphasis> argument, because you must own a group to reassign ownership. For complete instructions, see
1860 <link linkend="HDRWQ546">To create groups</link>. <programlisting>
1861 % <emphasis role="bold">pts creategroup</emphasis> <<replaceable>group name</replaceable>>
1862 </programlisting></para>
1866 <para>Issue the <emphasis role="bold">pts adduser</emphasis> command to add one or more members to the group (a group must
1867 already have at least one member before owning another group). For complete instructions, see <link
1868 linkend="HDRWQ549">Adding and Removing Group Members</link>. <programlisting>
1869 % <emphasis role="bold">pts adduser -user</emphasis> <<replaceable>user name</replaceable>>+ <emphasis role="bold">-group</emphasis> <<replaceable>group name</replaceable>>+
1870 </programlisting></para>
1874 <para>Issue the <emphasis role="bold">pts chown</emphasis> command to assign group ownership to the group itself. For
1875 complete instructions, see <link linkend="HDRWQ555">To change a group's owner</link>. <programlisting>
1876 % <emphasis role="bold">pts chown</emphasis> <<replaceable>group name</replaceable>> <<replaceable>new owner</replaceable>>
1877 </programlisting></para>
1882 <sect2 id="HDRWQ548">
1883 <title>Using Prefix-Less Groups</title>
1885 <para>Members of the <emphasis role="bold">system:administrators</emphasis> group can create prefix-less groups, which are
1886 particularly suitable for <emphasis>group use</emphasis>, which is described in <link linkend="HDRWQ545">Using Groups
1887 Effectively</link>.</para>
1889 <para>Suppose, for example, that the manager of the ABC Corporation's Accounting Department, user <emphasis
1890 role="bold">smith</emphasis>, creates a group that includes all of the corporation's accountants and places the group on the
1891 ACLs of directories that house departmental records. Using a prefix-less group rather than a regular group is appropriate for
1892 the following reasons: <itemizedlist>
1894 <para>The fact that <emphasis role="bold">smith</emphasis> created and owns the group is irrelevant, and a regular group
1895 must be called <emphasis role="bold">smith:acctg</emphasis>. A prefix-less name like <emphasis
1896 role="bold">acctg</emphasis> is more appropriate.</para>
1900 <para>If another user (say <emphasis role="bold">jones</emphasis>) ever replaces <emphasis role="bold">smith</emphasis>
1901 as manager of the Accounting Department, <emphasis role="bold">jones</emphasis> needs to become the new owner of the
1902 group. If the group is a regular one, its owner_name prefix automatically changes to <emphasis
1903 role="bold">jones</emphasis>, but the change in the owner_name prefix does not propagate to any regular groups owned by
1904 the group. Someone must use the <emphasis role="bold">pts rename</emphasis> command to change each one's owner_name
1905 prefix from <emphasis role="bold">smith</emphasis> to <emphasis role="bold">jones</emphasis>.</para>
1907 </itemizedlist></para>
1909 <para>A possible solution is to create an authentication account for a fictional user called <emphasis
1910 role="bold">acctg</emphasis> and make it the owner of regular groups which have <emphasis role="bold">acctg</emphasis> as
1911 their owner_name prefix. However, if the <emphasis role="bold">acctg</emphasis> account is also used for other purposes, then
1912 the number of people who need to know user <emphasis role="bold">acctg</emphasis>'s password is possibly larger than the
1913 number of people who need to administer the groups it owns.</para>
1915 <para>A prefix-less group called <emphasis role="bold">acctg</emphasis> solves the problem of inappropriate owner names. The
1916 groups that it owns have <emphasis role="bold">acctg</emphasis> as their owner_name prefix, which more accurately reflects
1917 their purpose than having the manager's name there. Prefix-less groups are also more accountable than dummy authentication
1918 accounts. Belonging to the group enables individuals to exercise the permissions granted to the group on ACLs, but users
1919 continue to perform tasks under their own names rather than under the dummy username. Even if the group owns itself, only a
1920 finite number of people can administer the group entry.</para>
1924 <sect1 id="HDRWQ549">
1925 <title>Adding and Removing Group Members</title>
1927 <para>Users and machines can be members of groups; groups cannot belong to other groups. Newly created groups have no members at
1928 all. To add them, use the <emphasis role="bold">pts adduser</emphasis> command; to remove them, use the <emphasis
1929 role="bold">pts removeuser</emphasis> command. <indexterm>
1930 <primary>adding</primary>
1932 <secondary>members to groups</secondary>
1933 </indexterm> <indexterm>
1934 <primary>group</primary>
1936 <secondary>members, adding</secondary>
1937 </indexterm> <indexterm>
1938 <primary>members</primary>
1940 <secondary>group, adding</secondary>
1941 </indexterm> <indexterm>
1942 <primary>user</primary>
1944 <secondary>adding to group</secondary>
1945 </indexterm> <indexterm>
1946 <primary>machine</primary>
1948 <secondary>adding to group</secondary>
1949 </indexterm> <indexterm>
1950 <primary>pts commands</primary>
1952 <secondary>adduser</secondary>
1953 </indexterm> <indexterm>
1954 <primary>commands</primary>
1956 <secondary>pts adduser</secondary>
1959 <sect2 id="HDRWQ550">
1960 <title>To add users and machines to groups</title>
1964 <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group, which enables you to add
1965 members to a group regardless of the setting of its fourth (<emphasis role="bold">a</emphasis>) privacy flag. By default
1966 the group's owner also has the necessary privilege. If necessary, issue the <emphasis role="bold">pts
1967 membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To display the members of the
1968 system:administrators group</link>. <programlisting>
1969 % <emphasis role="bold">pts membership system:administrators</emphasis>
1970 </programlisting></para>
1974 <para>Issue the <emphasis role="bold">pts adduser</emphasis> command to add one or more members to one or more groups.
1976 % <emphasis role="bold">pts adduser -user</emphasis> <<replaceable>user name</replaceable>>+ <emphasis role="bold">-group</emphasis> <<replaceable>group name</replaceable>>+
1977 </programlisting></para>
1983 <term><emphasis role="bold">ad</emphasis></term>
1986 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">adduser</emphasis>.</para>
1991 <term><emphasis role="bold">-user</emphasis></term>
1994 <para>Specifies each username or machine IP address to add as a member of each group named by the <emphasis
1995 role="bold">-group</emphasis> argument. A group cannot belong to another group.</para>
2000 <term><emphasis role="bold">group name</emphasis></term>
2003 <para>Names each group to which to add the new members.</para>
2011 <primary>removing</primary>
2013 <secondary>group members</secondary>
2017 <primary>group</primary>
2019 <secondary>members, removing</secondary>
2023 <primary>members</primary>
2025 <secondary>group, removing</secondary>
2029 <primary>user</primary>
2031 <secondary>removing from group</secondary>
2035 <primary>machine</primary>
2037 <secondary>removing from group</secondary>
2041 <primary>pts commands</primary>
2043 <secondary>removeuser</secondary>
2047 <primary>commands</primary>
2049 <secondary>pts removeuser</secondary>
2053 <sect2 id="HDRWQ551">
2054 <title>To remove users and machines from groups</title>
2058 <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group, which enables you to
2059 remove members from a group regardless of the setting of its fifth (<emphasis role="bold">r</emphasis>) privacy flag. By
2060 default the group's owner also has the necessary privilege. If necessary, issue the <emphasis role="bold">pts
2061 membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To display the members of the
2062 system:administrators group</link>. <programlisting>
2063 % <emphasis role="bold">pts membership system:administrators</emphasis>
2064 </programlisting></para>
2068 <para>Issue the <emphasis role="bold">pts removeuser</emphasis> command to remove one or more members from one or more
2069 groups. <programlisting>
2070 % <emphasis role="bold">pts removeuser -user</emphasis> <<replaceable>user name</replaceable>>+ <emphasis role="bold">-group</emphasis> <<replaceable>group name</replaceable>>+
2071 </programlisting></para>
2077 <term><emphasis role="bold">rem</emphasis></term>
2080 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">removeuser</emphasis>.</para>
2085 <term><emphasis role="bold">-user</emphasis></term>
2088 <para>Specifies each user or machine IP address to remove from each group named by the <emphasis
2089 role="bold">-group</emphasis> argument.</para>
2094 <term><emphasis role="bold">-group</emphasis></term>
2097 <para>Names each group from which to remove members.</para>
2106 <sect1 id="HDRWQ552">
2107 <title>Deleting Protection Database Entries</title>
2109 <para>It is best to delete a Protection Database user entry only if you are removing the complete user account. Use either the
2110 <emphasis role="bold">uss delete</emphasis> command as described in <link linkend="HDRWQ486">Deleting Individual Accounts with
2111 the uss delete Command</link>, or the <emphasis role="bold">pts delete</emphasis> command as described in <link
2112 linkend="HDRWQ524">Removing a User Account</link>.</para>
2114 <para>To remove machine and group entries, use the <emphasis role="bold">pts delete</emphasis> command as described in this
2115 section. The operation has the following results: <itemizedlist>
2117 <para>When you delete a machine entry, its name (IP address wildcard) is removed from groups.</para>
2121 <para>When you delete a group entry, its AFS GID appears on ACLs instead of the name. The <emphasis>group-creation
2122 quota</emphasis> of the user who created the group increases by one, even if the user no longer owns the group.</para>
2124 <para>To remove obsolete AFS IDs from ACLs, use the <emphasis role="bold">fs cleanacl</emphasis> command as described in
2125 <link linkend="HDRWQ579">Removing Obsolete AFS IDs from ACLs</link>.</para>
2127 </itemizedlist></para>
2130 <primary>removing</primary>
2132 <secondary>Protection Database entry</secondary>
2136 <primary>Protection Database</primary>
2138 <secondary>entry, deleting</secondary>
2142 <primary>group</primary>
2144 <secondary>Protection Database entry</secondary>
2146 <tertiary>deleting</tertiary>
2150 <primary>user</primary>
2152 <secondary>Protection Database entry</secondary>
2154 <tertiary>deleting</tertiary>
2158 <primary>machine</primary>
2160 <secondary>Protection Database entry</secondary>
2162 <tertiary>deleting</tertiary>
2166 <primary>pts commands</primary>
2168 <secondary>delete</secondary>
2172 <primary>commands</primary>
2174 <secondary>pts delete</secondary>
2177 <sect2 id="HDRWQ553">
2178 <title>To delete Protection Database entries</title>
2182 <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group or own the group you are
2183 deleting. If necessary, issue the <emphasis role="bold">pts membership</emphasis> command, which is fully described in
2184 <link linkend="HDRWQ587">To display the members of the system:administrators group</link>. <programlisting>
2185 % <emphasis role="bold">pts membership system:administrators</emphasis>
2186 </programlisting></para>
2190 <para>Issue the <emphasis role="bold">pts delete</emphasis> command to delete one or more entries from the Protection
2191 Database. <programlisting>
2192 % <emphasis role="bold">pts delete</emphasis> <<replaceable>user or group name or id</replaceable>>+
2193 </programlisting></para>
2199 <term><emphasis role="bold">del</emphasis></term>
2202 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">delete</emphasis>.</para>
2207 <term><emphasis role="bold">user or group name or id</emphasis></term>
2210 <para>Specifies the IP address or AFS UID of each machine or the name or AFS GID or each group to remove.</para>
2218 <primary>changing</primary>
2220 <secondary>Protection Database entry</secondary>
2222 <tertiary>owner</tertiary>
2226 <primary>owner</primary>
2228 <secondary>Protection Database entry</secondary>
2230 <tertiary>changing</tertiary>
2235 <sect1 id="HDRWQ554">
2236 <title>Changing a Group's Owner</title>
2238 <para>For user and machine entries, the Protection Server automatically assigns ownership to the <emphasis
2239 role="bold">system:administrators</emphasis> group at creation time, and this cannot be changed. For group entries, you can
2240 change ownership. This transfers administrative responsibility for it to another user or group (for information on group
2241 ownership of other groups, see <link linkend="HDRWQ545">Using Groups Effectively</link>).</para>
2243 <para>When you create a regular group, its owner_name prefix must accurately reflect its owner, as described in <link
2244 linkend="HDRWQ546">To create groups</link>: <itemizedlist>
2246 <para>If the owner is a user, owner_name is the username.</para>
2250 <para>If the owner is a regular group, owner_name is the owning group's owner_name prefix.</para>
2254 <para>If the owner is a prefix-less group, owner_name is the owner group's name.</para>
2256 </itemizedlist></para>
2258 <para>When you change a regular group's owner, the Protection Server automatically changes its owner_name prefix appropriately.
2259 For example, if the user <emphasis role="bold">pat</emphasis> becomes the new owner of the group <emphasis
2260 role="bold">terry:friends</emphasis>, its name automatically changes to <emphasis role="bold">pat:friends</emphasis>, both in
2261 the Protection Database and on ACLs.</para>
2263 <para>However, the Protection Server does not automatically change the owner_name prefix of any regular groups that the group
2264 owns. To continue with the previous example, suppose that the group <emphasis role="bold">terry:friends</emphasis> owns the
2265 group <emphasis role="bold">terry:pals</emphasis>. When <emphasis role="bold">pat</emphasis> becomes the new owner of <emphasis
2266 role="bold">terry:friends</emphasis>, the name <emphasis role="bold">terry:pals</emphasis> does not change. To change the
2267 owner_name prefix of a regular group that is owned by another group (in the example, to change the group's name to <emphasis
2268 role="bold">pat:pals</emphasis>), use the <emphasis role="bold">pts rename</emphasis> command as described in <link
2269 linkend="HDRWQ556">Changing a Protection Database Entry's Name</link>. <indexterm>
2270 <primary>Protection Database</primary>
2272 <secondary>owner of entry</secondary>
2274 <tertiary>changing</tertiary>
2275 </indexterm> <indexterm>
2276 <primary>commands</primary>
2278 <secondary>pts chown</secondary>
2279 </indexterm> <indexterm>
2280 <primary>pts commands</primary>
2282 <secondary>chown</secondary>
2285 <sect2 id="HDRWQ555">
2286 <title>To change a group's owner</title>
2290 <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group or own the group for
2291 which you are changing the owner. If necessary, issue the <emphasis role="bold">pts membership</emphasis> command, which
2292 is fully described in <link linkend="HDRWQ587">To display the members of the system:administrators group</link>.
2294 % <emphasis role="bold">pts membership system:administrators</emphasis>
2295 </programlisting></para>
2299 <para><emphasis role="bold">(Optional)</emphasis> If you are changing the group's owner to another group (or to itself)
2300 and want to retain administrative privilege on the owned group, verify that you belong to the new owner group. If
2301 necessary, issue the <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link
2302 linkend="HDRWQ538">To display group membership</link>. <programlisting>
2303 % <emphasis role="bold">pts membership</emphasis> <<replaceable>user or group name or id</replaceable>>
2304 </programlisting></para>
2306 <para>Use the <emphasis role="bold">pts adduser</emphasis> command to add yourself if necessary, as fully described in
2307 <link linkend="HDRWQ550">To add users and machines to groups</link>.</para>
2310 % <emphasis role="bold">pts adduser</emphasis> <<replaceable>user name</replaceable>> <<replaceable>group name</replaceable>>
2315 <para>Issue the <emphasis role="bold">pts chown</emphasis> command to change the group's owner. <programlisting>
2316 % <emphasis role="bold">pts chown</emphasis> <<replaceable>group name</replaceable>> <<replaceable>new owner</replaceable>>
2317 </programlisting></para>
2323 <term><emphasis role="bold">cho</emphasis></term>
2326 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">chown</emphasis>.</para>
2331 <term><emphasis role="bold">group name</emphasis></term>
2334 <para>Specifies the current name of the group.</para>
2339 <term><emphasis role="bold">new owner</emphasis></term>
2342 <para>Names the user or group to become the group's owner.</para>
2349 <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">pts listowned</emphasis> command to
2350 display any groups that the group owns. As discussed in the introduction to this section, the <emphasis role="bold">pts
2351 chown</emphasis> command does not automatically change the owner_name prefix of any regular groups that a group owns.
2353 % <emphasis role="bold">pts listowned</emphasis> <<replaceable>user or group name or id</replaceable>>
2354 </programlisting></para>
2356 <para>If you want to change their names to match the new owning group, use the <emphasis role="bold">pts rename</emphasis>
2357 command on each one, as described in <link linkend="HDRWQ557">To change the name of a machine or group
2358 entry</link>.</para>
2361 % <emphasis role="bold">pts rename</emphasis> <<replaceable>old name</replaceable>> <<replaceable>new name</replaceable>>
2367 <primary>changing</primary>
2369 <secondary>Protection Database entry</secondary>
2371 <tertiary>name</tertiary>
2375 <primary>name</primary>
2377 <secondary>Protection Database entry</secondary>
2379 <tertiary>changing</tertiary>
2383 <primary>Protection Database</primary>
2385 <secondary>entry name</secondary>
2387 <tertiary>changing</tertiary>
2391 <primary>group</primary>
2393 <secondary>Protection Database entry</secondary>
2395 <tertiary>name, changing</tertiary>
2399 <primary>machine</primary>
2401 <secondary>Protection Database entry</secondary>
2403 <tertiary>name, changing</tertiary>
2408 <sect1 id="HDRWQ556">
2409 <title>Changing a Protection Database Entry's Name</title>
2411 <para>To change the name of a Protection Database entry, use the <emphasis role="bold">pts rename</emphasis> command. It is best
2412 to change a user entry's name only when renaming the entire user account, since so many components of the account
2413 (Authentication Database entry, volume name, home directory mount point, and so on) share the name. For instructions, see <link
2414 linkend="HDRWQ518">Changing Usernames</link>. A machine entry's name maps to the actual IP address of one or more machine, so
2415 changing the entry's name is appropriate only if the IP addresses have changed.</para>
2417 <para>It is likely, then, that most often you need to change group names. The following types of name changes are possible:
2420 <para>Changing a regular group's name to another regular group name. The most common reason for this type of change is
2421 that you have used the <emphasis role="bold">pts chown</emphasis> command to change the owner of the group. That operation
2422 does not change the owner_name prefix of a regular group owned by the group whose name has been changed. Therefore, you
2423 must use the <emphasis role="bold">pts rename</emphasis> command to change it appropriately. For example, when user
2424 <emphasis role="bold">pat</emphasis> becomes the owner of the <emphasis role="bold">terry:friends</emphasis> group, its
2425 name changes automatically to <emphasis role="bold">pat:friends</emphasis>, but the name of a group it owns, <emphasis
2426 role="bold">terry:pals</emphasis>, does not change. Use the <emphasis role="bold">pts rename</emphasis> command to rename
2427 <emphasis role="bold">terry:pals</emphasis> to <emphasis role="bold">pat:pals</emphasis>. The Protection Server does not
2428 accept changes to the owner_name prefix that do not reflect the true ownership (changing <emphasis
2429 role="bold">terry:pals</emphasis> to <emphasis role="bold">smith:pals</emphasis> is not possible).</para>
2431 <para>You can also use the <emphasis role="bold">pts rename</emphasis> command to change the group_name portion of a
2432 regular group name, with or without changing the owner_name prefix.</para>
2434 <para>Both the group's owner and the members of the <emphasis role="bold">system:administrators</emphasis> group can
2435 change its name to another regular group name.</para>
2439 <para>Changing a regular group's name to a prefix-less name. If you change a group's name in this way, you must also use
2440 the <emphasis role="bold">pts rename</emphasis> command to change the name of any regular group that the group owns. Only
2441 members of the <emphasis role="bold">system:administrators</emphasis> group can make this type of name change.</para>
2445 <para>Changing a prefix-less name to another prefix-less name. As with other name changes, the owner_name prefix of any
2446 regular groups that the prefix-less group owns does not change automatically. You must issue the <emphasis role="bold">pts
2447 rename</emphasis> command on them to maintain consistency.</para>
2449 <para>Both the group's owner and the members of the <emphasis role="bold">system:administrators</emphasis> group can
2450 change its name to another prefix-less name.</para>
2454 <para>Changing a prefix-less name to a regular name. The owner_name prefix on the new name must accurately reflect the
2455 group's ownership. As with other name changes, the owner_name prefix of any regular groups that the prefix-less group owns
2456 does not change automatically. You must issue the <emphasis role="bold">pts rename</emphasis> command on them to maintain
2459 <para>Only members of the <emphasis role="bold">system:administrators</emphasis> group can make this type of name
2462 </itemizedlist></para>
2465 <primary>commands</primary>
2467 <secondary>pts rename</secondary>
2469 <tertiary>machine or group name</tertiary>
2473 <primary>pts commands</primary>
2475 <secondary>rename</secondary>
2477 <tertiary>machine or group name</tertiary>
2480 <sect2 id="HDRWQ557">
2481 <title>To change the name of a machine or group entry</title>
2485 <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
2486 <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To display
2487 the members of the system:administrators group</link>. <programlisting>
2488 % <emphasis role="bold">pts membership system:administrators</emphasis>
2489 </programlisting></para>
2493 <para>Issue the <emphasis role="bold">pts rename</emphasis> command to change the entry's name. <programlisting>
2494 % <emphasis role="bold">pts rename</emphasis> <<replaceable>old name</replaceable>> <<replaceable>new name</replaceable>>
2495 </programlisting></para>
2501 <term><emphasis role="bold">ren</emphasis></term>
2504 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">rename</emphasis>.</para>
2509 <term><emphasis role="bold">old name</emphasis></term>
2512 <para>Specifies the entry's current name.</para>
2517 <term><emphasis role="bold">new name</emphasis></term>
2520 <para>Specifies the new name. If the new name is for a regular group, the owner_name prefix must correctly indicate
2529 <primary>setting</primary>
2531 <secondary>group-creation quota in Protection Database entry</secondary>
2535 <primary>quota</primary>
2537 <secondary>group-creation</secondary>
2539 <tertiary>setting</tertiary>
2543 <primary>Protection Database</primary>
2545 <secondary>group creation quota</secondary>
2547 <tertiary>setting</tertiary>
2551 <primary>user</primary>
2553 <secondary>group-creation quota</secondary>
2555 <tertiary>setting</tertiary>
2559 <primary>changing</primary>
2561 <secondary>group-creation quota</secondary>
2566 <sect1 id="HDRWQ558">
2567 <title>Setting Group-Creation Quota</title>
2569 <para>To prevent abuse of system resources, the Protection Server imposes a group-creation quota that limits how many more
2570 groups a user can create. When a new user entry is created, the quota is set to 20, but members of the <emphasis
2571 role="bold">system:administrators</emphasis> group can use the <emphasis role="bold">pts setfields</emphasis> command to
2572 increase or decrease it at any time.</para>
2574 <para>It is pointless to change group-creation quota for machine or group entries. It is not possible to authenticate as a group
2575 or machine and then create groups.</para>
2577 <para>To display the group-creation quota, use the <emphasis role="bold">pts examine</emphasis> command to display a user
2578 entry's <computeroutput>group quota field</computeroutput>, as described in <link linkend="HDRWQ537">To display a Protection
2579 Database entry</link>. <indexterm>
2580 <primary>pts commands</primary>
2582 <secondary>setfields</secondary>
2584 <tertiary>setting group creation quota</tertiary>
2585 </indexterm> <indexterm>
2586 <primary>commands</primary>
2588 <secondary>pts setfields</secondary>
2590 <tertiary>setting group creation quota</tertiary>
2593 <sect2 id="Header_622">
2594 <title>To set group-creation quota</title>
2598 <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
2599 <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To display
2600 the members of the system:administrators group</link>. <programlisting>
2601 % <emphasis role="bold">pts membership system:administrators</emphasis>
2602 </programlisting></para>
2606 <para>Issue the <emphasis role="bold">pts setfields</emphasis> command to specify how many more groups each of one or more
2607 users can create. <programlisting>
2608 % <emphasis role="bold">pts setfields -nameorid</emphasis> <<replaceable>user or group name or id</replaceable>>+ \
2609 <emphasis role="bold">-groupquota</emphasis> <<replaceable>set limit on group creation</replaceable>>
2610 </programlisting></para>
2616 <term><emphasis role="bold">setf</emphasis></term>
2619 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">setfields</emphasis>.</para>
2624 <term><emphasis role="bold">-nameorid</emphasis></term>
2627 <para>Specifies the name or AFS UID of each user for which to set group-creation quota.</para>
2632 <term><emphasis role="bold">-groupquota</emphasis></term>
2635 <para>Defines how many groups each user can create in addition to existing groups (in other words, groups that
2636 already exist do not count against the quota). The value you specify overwrites the current value, rather than
2637 incrementing it.</para>
2645 <primary>group</primary>
2647 <secondary>privacy flags on Protection Database entry</secondary>
2649 <tertiary>setting</tertiary>
2653 <primary>user</primary>
2655 <secondary>privacy flags on Protection Database entry</secondary>
2657 <tertiary>setting</tertiary>
2661 <primary>machine</primary>
2663 <secondary>privacy flags on Protection Database entry</secondary>
2665 <tertiary>setting</tertiary>
2669 <primary>setting</primary>
2671 <secondary>privacy flags on Protection Database entry</secondary>
2675 <primary>privacy flags on Protection Database entry</primary>
2677 <secondary>setting</secondary>
2681 <primary>Protection Database</primary>
2683 <secondary>privacy flags</secondary>
2685 <tertiary>setting</tertiary>
2690 <sect1 id="HDRWQ559">
2691 <title>Setting the Privacy Flags on Database Entries</title>
2693 <para>Members of the <emphasis role="bold">system:administrators</emphasis> group can always display and administer Protection
2694 Database entries in any way, and regular users can display and administer their own entries and any group entries they own. The
2695 <emphasis>privacy flags</emphasis> on a Protection Database entry determine who else can display certain information from the
2696 entry, and who can add and remove members in a group.</para>
2698 <para>To display the flags, use the <emphasis role="bold">pts examine</emphasis> command as described in <link
2699 linkend="HDRWQ537">To display a Protection Database entry</link>. The flags appear in the output's
2700 <computeroutput>flags</computeroutput> field. To set the flags, include the <emphasis role="bold">-access</emphasis> argument to
2701 the <emphasis role="bold">pts setfields</emphasis> command.</para>
2703 <para>The five flags always appear, and always must be set, in the following order:</para>
2707 <term><emphasis role="bold">s</emphasis></term>
2710 <para>Controls who can issue the <emphasis role="bold">pts examine</emphasis> command to display the entry.</para>
2715 <term><emphasis role="bold">o</emphasis></term>
2718 <para>Controls who can issue the <emphasis role="bold">pts listowned</emphasis> command to display the groups that a user
2719 or group owns.</para>
2724 <term><emphasis role="bold">m</emphasis></term>
2727 <para>Controls who can issue the <emphasis role="bold">pts membership</emphasis> command to display the groups a user or
2728 machine belongs to, or which users or machines belong to a group.</para>
2733 <term><emphasis role="bold">a</emphasis></term>
2736 <para>Controls who can issue the <emphasis role="bold">pts adduser</emphasis> command to add a user or machine to a group.
2737 It is meaningful only for groups, but a value must always be set for it even on user and machine entries.</para>
2742 <term><emphasis role="bold">r</emphasis></term>
2745 <para>Controls who can issue the <emphasis role="bold">pts removeuser</emphasis> command to remove a user or machine from
2746 a group. It is meaningful only for groups, but a value must always be set for it even on user and machine entries.</para>
2751 <para>Each flag can take three possible types of values to enable a different set of users to issue the corresponding command:
2754 <para>A hyphen (<emphasis role="bold">-</emphasis>) designates the members of the <emphasis
2755 role="bold">system:administrators</emphasis> group and the entry's owner. For user entries, it designates the user in
2760 <para>The lowercase version of the letter applies meaningfully to groups only, and designates members of the group in
2761 addition to the individuals designated by the hyphen.</para>
2765 <para>The uppercase version of the letter designates everyone.</para>
2767 </itemizedlist></para>
2769 <para>For example, the flags <computeroutput>SOmar</computeroutput> on a group entry indicate that anyone can examine the
2770 group's entry and display the groups that it owns, and that only the group's members can display, add, or remove its
2773 <para>The default privacy flags for user and machine entries are <computeroutput>S----</computeroutput>, meaning that anyone can
2774 display the entry. The ability to perform any other functions is restricted to members of the <emphasis
2775 role="bold">system:administrators</emphasis> group and the entry's owner (as well as the user for a user entry).</para>
2777 <para>The default privacy flags for group entries are <computeroutput>S-M--</computeroutput>, meaning that all users can display
2778 the entry and the members of the group, but only the entry owner and members of the <emphasis
2779 role="bold">system:administrators</emphasis> group can perform other functions. <indexterm>
2780 <primary>pts commands</primary>
2782 <secondary>setfields</secondary>
2784 <tertiary>setting privacy flags</tertiary>
2785 </indexterm> <indexterm>
2786 <primary>commands</primary>
2788 <secondary>pts setfields</secondary>
2790 <tertiary>setting privacy flags</tertiary>
2793 <sect2 id="Header_624">
2794 <title>To set a Protection Database entry's privacy flags</title>
2798 <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
2799 <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To display
2800 the members of the system:administrators group</link>. <programlisting>
2801 % <emphasis role="bold">pts membership system:administrators</emphasis>
2802 </programlisting></para>
2806 <para>Issue the <emphasis role="bold">pts setfields</emphasis> command to set the privacy flags. <programlisting>
2807 % <emphasis role="bold">pts setfields</emphasis> <<replaceable>user or group name or id</replaceable>>+ <emphasis
2808 role="bold">-access</emphasis> <<replaceable>set privacy flags</replaceable>>
2809 </programlisting></para>
2815 <term><emphasis role="bold">setf</emphasis></term>
2818 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">setfields</emphasis>.</para>
2823 <term><emphasis role="bold">user or group name or id</emphasis></term>
2826 <para>Specifies the name or AFS UID of each user, the IP address or AFS UID of each machine, or the name or AFS GID
2827 of each group for which to set the privacy flags.</para>
2832 <term><emphasis role="bold">-access</emphasis></term>
2835 <para>Specifies the set of privacy flags to associate with each entry. Provide a value for each of the five flags,
2836 observing the following constraints: <itemizedlist>
2838 <para>Provide a value for all five flags, even though the fourth and fifth flags are not meaningful for user
2839 and machine entries.</para>
2843 <para>For self-owned groups, the hyphen is equivalent to a lowercase letter, because all the members of a
2844 self-owned group own it.</para>
2848 <para>Set the first flag to lowercase <emphasis role="bold">s</emphasis> or uppercase <emphasis
2849 role="bold">S</emphasis> only. For user and machine entries, the Protection Server interprets the lowercase
2850 <emphasis role="bold">s</emphasis> as equivalent to the hyphen.</para>
2854 <para>Set the second flag to the hyphen (<emphasis role="bold">-</emphasis>) or uppercase <emphasis
2855 role="bold">O</emphasis> only. For groups, the Protection Server interprets the hyphen as equivalent to
2856 lowercase <emphasis role="bold">o</emphasis> (that is, members of a group can always list the groups that it
2861 <para>Set the third flag to the hyphen (<emphasis role="bold">-</emphasis>), lowercase <emphasis
2862 role="bold">m</emphasis>, or uppercase <emphasis role="bold">M</emphasis>. For user and machine entries, the
2863 lowercase <emphasis role="bold">m</emphasis> does not have a meaningful interpretation, because they have no
2868 <para>Set the fourth flag to the hyphen (<emphasis role="bold">-</emphasis>), lowercase <emphasis
2869 role="bold">a</emphasis>, or uppercase <emphasis role="bold">A</emphasis>. Although this flag does not have a
2870 meaningful interpretation for user and machine entries (because they have no members), it must be set,
2871 preferably to the hyphen.</para>
2875 <para>Set the fifth flag to the hyphen (<emphasis role="bold">-</emphasis>) or lowercase <emphasis
2876 role="bold">r</emphasis> only. Although this flag does not have a meaningful interpretation for user and
2877 machine entries (because they have no members), it must be set, preferably to the hyphen.</para>
2879 </itemizedlist></para>
2887 <primary>counter</primary>
2889 <secondary>Protection Database (max user id, max group id)</secondary>
2893 <primary>Protection Database</primary>
2895 <secondary>max user id and max group id counters, displaying and setting</secondary>
2899 <primary>AFS UID</primary>
2901 <secondary>counter for automatic allocation, displaying and setting</secondary>
2905 <primary>AFS GID</primary>
2907 <secondary>counter for automatic allocation, displaying and setting</secondary>
2912 <sect1 id="HDRWQ560">
2913 <title>Displaying and Setting the AFS UID and GID Counters</title>
2915 <para>When you use the <emphasis role="bold">pts createuser</emphasis> command to create a user or machine entry in the
2916 Protection Database, the Protection Server by default automatically allocates an AFS user ID (AFS UID) for it; similarly, it
2917 allocates an AFS group ID (AFS GID) for each group entry you create with the <emphasis role="bold">pts creategroup</emphasis>
2918 command. It tracks the next available AFS UID (which is a positive integer) and AFS GID (which is a negative integer) with the
2919 <computeroutput>max user id</computeroutput> and <computeroutput>max group id</computeroutput> counters, respectively.</para>
2921 <para>Members of the <emphasis role="bold">system:administrators</emphasis> group can include the <emphasis
2922 role="bold">-id</emphasis> argument to either <emphasis role="bold">pts</emphasis> creation command to assign a specific ID to a
2923 new user, machine, or group. It often makes sense to assign AFS UIDs explicitly when creating AFS accounts for users with
2924 existing UNIX accounts, as discussed in <link linkend="HDRWQ456">Assigning AFS and UNIX UIDs that Match</link>. It is also
2925 useful if you want to establish ranges of IDs that correspond to departmental affiliations (for example, assigning AFS UIDs from
2926 300 to 399 to members of one department, AFS UIDs from 400 to 499 to another department, and so on).</para>
2928 <para>To display the current value of the counters, use the <emphasis role="bold">pts listmax</emphasis> command. When you next
2929 create a user or machine entry and do not specify its AFS UID, the Protection Server increments the <computeroutput>max user
2930 id</computeroutput> counter by one and assigns that number to the new entry. When you create a new group and do not specify its
2931 AFS GID, the Protection Server decrements the <computeroutput>max group id</computeroutput> counter by one (makes it more
2932 negative), and assigns that number to the new group.</para>
2934 <para>You can change the value of either counter, or both, in one of two ways:</para>
2938 <para>Directly, using the <emphasis role="bold">pts setmax</emphasis> command.</para>
2942 <para>Indirectly, by using the <emphasis role="bold">-id</emphasis> argument to the <emphasis role="bold">pts
2943 createuser</emphasis> command to assign an AFS UID that is larger than the <computeroutput>max user id</computeroutput>
2944 counter, or by using the <emphasis role="bold">-id</emphasis> to the <emphasis role="bold">pts creategroup</emphasis>
2945 command to assign an AFS GID that is less (more negative) than the max group id counter. In either case, the Protection
2946 Server changes the counter to the value of the <emphasis role="bold">-id</emphasis> argument. The Protection Server does not
2947 use the IDs between the previous value of the counter and the new one when allocating IDs automatically, unless you use the
2948 <emphasis role="bold">pts setmax</emphasis> command to move the counter back to its old value.</para>
2950 <para>If the value you specify with the <emphasis role="bold">-id</emphasis> argument is less than the <computeroutput>max
2951 user id</computeroutput> counter or greater (less negative) than the <computeroutput>max group id</computeroutput> counter,
2952 then the counter does not change.</para>
2957 <primary>pts commands</primary>
2959 <secondary>listmax</secondary>
2963 <primary>commands</primary>
2965 <secondary>pts listmax</secondary>
2969 <primary>max user id counter (Protection Database)</primary>
2971 <secondary>displaying</secondary>
2975 <primary>max group id counter (Protection Database)</primary>
2977 <secondary>displaying</secondary>
2981 <primary>displaying</primary>
2983 <secondary>counters for AFS UID and AFS GID</secondary>
2987 <primary>displaying</primary>
2989 <secondary>AFS user id and max group id counters</secondary>
2992 <sect2 id="HDRWQ561">
2993 <title>To display the AFS ID counters</title>
2997 <para>Issue the <emphasis role="bold">pts listmax</emphasis> command to display the counters. <programlisting>
2998 % <emphasis role="bold">pts listmax</emphasis>
2999 </programlisting></para>
3001 <para>where <emphasis role="bold">listm</emphasis> is an acceptable abbreviation of <emphasis
3002 role="bold">listmax</emphasis>.</para>
3006 <para>The following example illustrates the output's format. In this case, the next automatically assigned AFS UID is 5439 and
3007 AFS GID is -469.</para>
3010 % <emphasis role="bold">pts listmax</emphasis>
3011 Max user id is 5438 and max group id is -468.
3015 <primary>max user id counter (Protection Database)</primary>
3017 <secondary>setting</secondary>
3021 <primary>max group id counter (Protection Database)</primary>
3023 <secondary>setting</secondary>
3027 <primary>setting</primary>
3029 <secondary>counters for AFS UID and AFS GID</secondary>
3033 <primary>setting</primary>
3035 <secondary>AFS user id and max group id counters</secondary>
3039 <primary>Protection Database</primary>
3041 <secondary>ID counters, setting</secondary>
3045 <primary>setting</primary>
3047 <secondary>AFS UID and AFS GID counters</secondary>
3051 <primary>Protection Database</primary>
3053 <secondary>setting</secondary>
3055 <tertiary>counters for AFS UIDs</tertiary>
3059 <primary>AFS UID</primary>
3061 <secondary>setting counters for automatic allocation</secondary>
3065 <primary>setting</primary>
3067 <secondary>AFS UID counters</secondary>
3071 <primary>pts commands</primary>
3073 <secondary>setmax</secondary>
3077 <primary>commands</primary>
3079 <secondary>pts setmax</secondary>
3083 <sect2 id="Header_627">
3084 <title>To set the AFS ID counters</title>
3088 <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
3089 <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To display
3090 the members of the system:administrators group</link>. <programlisting>
3091 % <emphasis role="bold">pts membership system:administrators</emphasis>
3092 </programlisting></para>
3096 <para>Issue the <emphasis role="bold">pts setmax</emphasis> command to set the <computeroutput>max user
3097 id</computeroutput> counter, the <computeroutput>max group id</computeroutput> counter, or both. <programlisting>
3098 % <emphasis role="bold">pts setmax</emphasis> [<emphasis role="bold">-group</emphasis> <<replaceable>group max</replaceable>>] [<emphasis
3099 role="bold">-user</emphasis> <<replaceable>user max</replaceable>>]
3100 </programlisting></para>
3106 <term><emphasis role="bold">setm</emphasis></term>
3109 <para>Is the shortest acceptable abbreviation of <emphasis role="bold">setmax</emphasis>.</para>
3114 <term><emphasis role="bold">-group</emphasis></term>
3117 <para>Specifies an integer one greater (less negative) than the AFS GID that the Protection Server is to assign to
3118 the next group entry. Because the value is a negative integer, precede it with a hyphen (<emphasis
3119 role="bold">-</emphasis>).</para>
3124 <term><emphasis role="bold">-user</emphasis></term>
3127 <para>Specifies an integer one less than the AFS UID that the Protection Server is to assign to the next user or
3128 machine entry.</para>