doc/xml/UserGuide/auusg008.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <chapter id="HDRWQ60">
   3   <title>Using Groups</title>
   4
   5   <para>This chapter explains how to create groups and discusses different ways to use them.</para>
   6
   7   <sect1 id="HDRWQ61">
   8     <title>About Groups</title>
   9
  10     <para>An AFS <emphasis>group</emphasis> is a list of specific users that you can place on access control lists (ACLs). Groups
  11     make it much easier to maintain ACLs. Instead of creating an ACL entry for every user individually, you create one entry for a
  12     group to which the users belong. Similarly, you can grant a user access to many directories at once by adding the user to a
  13     group that appears on the relevant ACLs.</para>
  14
  15     <para>AFS client machines can also belong to a group. Anyone logged into the machine inherits the permissions granted to the
  16     group on an ACL, even if they are not authenticated with AFS. In general, groups of machines are useful only to system
  17     administrators, for specialized purposes like complying with licensing agreements your cell has with software vendors. Talk with
  18     your system administrator before putting a client machine in a group or using a machine group on an ACL. <indexterm>
  19         <primary>machines</primary>
  20
  21         <secondary>as members of groups</secondary>
  22       </indexterm> <indexterm>
  23         <primary>groups</primary>
  24
  25         <secondary>machines as members</secondary>
  26       </indexterm></para>
  27
  28     <para>To learn about AFS file protection and how to add groups to ACLs, see <link linkend="HDRWQ44">Protecting Your Directories
  29     and Files</link>.</para>
  30
  31     <sect2 id="HDRWQ62">
  32       <title>Suggestions for Using Groups Effectively</title>
  33
  34       <para>There are three typical ways to use groups, each suited to a particular purpose: private use, shared use, and group use.
  35       The following are only suggestions. You are free to use groups in any way you choose.</para>
  36
  37       <itemizedlist>
  38         <listitem>
  39           <para><emphasis>Private use</emphasis>: you create a group and place it on the ACL of directories you own, without
  40           necessarily informing the group's members that they belong to it. Members notice only that they can or cannot access the
  41           directory in a certain way. You retain sole administrative control over the group, since you are the owner. <indexterm>
  42               <primary>private use of group</primary>
  43             </indexterm> <indexterm>
  44               <primary>groups</primary>
  45
  46               <secondary>private use</secondary>
  47             </indexterm></para>
  48
  49           <para>The existence of the group and the identity of its members is not necessarily secret. Other users can see the
  50           group's name on an ACL when they use the <emphasis role="bold">fs listacl</emphasis> command, and can use the <emphasis
  51           role="bold">pts membership</emphasis> command to display + the groups to which they themselves belong. You can, however,
  52           limit who can display the members of the group, as described in <link linkend="HDRWQ74">Protecting Group-Related
  53           Information</link>.</para>
  54         </listitem>
  55
  56         <listitem>
  57           <para><emphasis>Shared use</emphasis>: you inform the group's members that they belong to the group, but you are the
  58           group's sole owner and administrator. For example, the manager of a work group can create a group of all the members in
  59           the work group, and encourage them to use it on the ACLs of directories that house information they want to share with
  60           other members of the group. <indexterm>
  61               <primary>shared use of group</primary>
  62             </indexterm> <indexterm>
  63               <primary>groups</primary>
  64
  65               <secondary>shared use</secondary>
  66             </indexterm> <note>
  67               <para>If you place a group owned by someone else on your ACLs, the group's owner can change the group's membership
  68               without informing you. Someone new can gain or lose access in a way you did not intend and without your
  69               knowledge.</para>
  70             </note></para>
  71         </listitem>
  72
  73         <listitem>
  74           <para><emphasis>Group use</emphasis>: you create a group and then use the <emphasis role="bold">pts chown</emphasis>
  75           command to assign ownership to a group--either another group or the group itself (the latter type is a
  76           <emphasis>self-owned</emphasis> group). You inform the members of the owning group that they all can administer the owned
  77           group. For instructions for the <emphasis role="bold">pts chown</emphasis> command, see <link linkend="HDRWQ73">To Change
  78           a Group's Owner</link>. <indexterm>
  79               <primary>group use of group</primary>
  80             </indexterm> <indexterm>
  81               <primary>self-owned group</primary>
  82             </indexterm> <indexterm>
  83               <primary>groups</primary>
  84
  85               <secondary>group use</secondary>
  86             </indexterm> <indexterm>
  87               <primary>groups</primary>
  88
  89               <secondary>group-owned groups</secondary>
  90             </indexterm> <indexterm>
  91               <primary>groups</primary>
  92
  93               <secondary>self-owned groups</secondary>
  94             </indexterm></para>
  95
  96           <para>The main advantage of designating a group as an owner is that several people share responsibility for administering
  97           the group. A single person does not have to perform all administrative tasks, and if the group's original owner leaves the
  98           cell, there are still other people who can administer it.</para>
  99
 100           <para>However, everyone in the owner group can make changes that affect others negatively: adding or removing people from
 101           the group inappropriately or changing the group's ownership to themselves exclusively. These problems can be particularly
 102           sensitive in a self-owned group. Using an owner group works best if all the members know and trust each other; it is
 103           probably wise to keep the number of people in an owner group small.</para>
 104         </listitem>
 105       </itemizedlist>
 106     </sect2>
 107
 108     <sect2 id="HDRWQ63">
 109       <title>Group Names</title>
 110
 111       <indexterm>
 112         <primary>groups</primary>
 113
 114         <secondary>naming conventions</secondary>
 115       </indexterm>
 116
 117       <para>The groups you create must have names with two parts, in the following format:</para>
 118
 119       <para><replaceable>owner_name</replaceable><emphasis role="bold">:</emphasis><replaceable>group_name</replaceable></para>
 120
 121       <para>The <replaceable>owner_name</replaceable> prefix indicates which user or group owns the group (naming rules appear in
 122       <link linkend="HDRWQ69">To Create a Group</link>). The <replaceable>group_name</replaceable> part indicates the group's
 123       purpose or its members' common interest. Group names must always be typed in full, so a short
 124       <replaceable>group_name</replaceable> is most practical. However, names like <emphasis role="bold">terry:1</emphasis> and
 125       <emphasis role="bold">terry:2</emphasis> that do not indicate the group's purpose are less useful than names like <emphasis
 126       role="bold">terry:project</emphasis>.</para>
 127
 128       <para>Groups that do not have the <replaceable>owner_name</replaceable> prefix possibly appear on some ACLs; they are created
 129       by system administrators only. All of the groups you create must have an <replaceable>owner_name</replaceable> prefix.</para>
 130     </sect2>
 131
 132     <sect2 id="Header_116">
 133       <title>Group-creation Quota</title>
 134
 135       <indexterm>
 136         <primary>group-creation quota</primary>
 137
 138         <secondary>defined</secondary>
 139       </indexterm>
 140
 141       <indexterm>
 142         <primary>groups</primary>
 143
 144         <secondary>creation quota</secondary>
 145       </indexterm>
 146
 147       <para>By default, you can create 20 groups, but your system administrators can change your <emphasis>group-creation
 148       quota</emphasis> if appropriate. When you create a group, your group quota decrements by one. When a group that you created is
 149       deleted, your quota increments by one, even if you are no longer the owner. You cannot increase your quota by transferring
 150       ownership of a group to someone else, because you are always recorded as the creator.</para>
 151
 152       <para>If you exhaust your group-creation quota and need to create more groups, ask your system administrator. For instructions
 153       for displaying your group-creation quota, see <link linkend="HDRWQ67">To Display A Group Entry</link>.</para>
 154     </sect2>
 155   </sect1>
 156
 157   <sect1 id="HDRWQ64">
 158     <title>Displaying Group Information</title>
 159
 160     <indexterm>
 161       <primary>displaying</primary>
 162
 163       <secondary>group information</secondary>
 164     </indexterm>
 165
 166     <indexterm>
 167       <primary>groups</primary>
 168
 169       <secondary>displaying information</secondary>
 170     </indexterm>
 171
 172     <indexterm>
 173       <primary>users</primary>
 174
 175       <secondary>displaying group information</secondary>
 176     </indexterm>
 177
 178     <para>You can use the following commands to display information about groups and the users who belong to them:</para>
 179
 180     <itemizedlist>
 181       <listitem>
 182         <para>To display the members of a group, or the groups to which a user belongs, use the <emphasis role="bold">pts
 183         membership</emphasis> command.</para>
 184       </listitem>
 185
 186       <listitem>
 187         <para>To display the groups that a user or group owns, use the <emphasis role="bold">pts listowned</emphasis>
 188         command.</para>
 189       </listitem>
 190
 191       <listitem>
 192         <para>To display general information about a user or group, including its name, AFS ID, creator, and owner, use the
 193         <emphasis role="bold">pts examine</emphasis> command.</para>
 194       </listitem>
 195     </itemizedlist>
 196
 197     <note>
 198       <para>The <emphasis role="bold">system:anyuser</emphasis> and <emphasis role="bold">system:authuser</emphasis> system groups
 199       do not appear in a user's list of group memberships, and the <emphasis role="bold">pts membership</emphasis> command does not
 200       display their members. For more information on the system groups, see <link linkend="HDRWQ50">Using the System Groups on
 201       ACLs</link>.</para>
 202     </note>
 203
 204     <sect2 id="HDRWQ65">
 205       <title>To Display Group Membership</title>
 206
 207       <indexterm>
 208         <primary>commands</primary>
 209
 210         <secondary>pts membership</secondary>
 211       </indexterm>
 212
 213       <indexterm>
 214         <primary>pts commands</primary>
 215
 216         <secondary>membership</secondary>
 217       </indexterm>
 218
 219       <para>Issue the <emphasis role="bold">pts membership</emphasis> command to display the members of a group, or the groups to
 220       which a user belongs.</para>
 221
 222       <programlisting>
 223    % <emphasis role="bold">pts membership</emphasis> &lt;<replaceable>user or group name or id</replaceable>&gt;<superscript>+</superscript>
 224 </programlisting>
 225
 226       <para>where <replaceable>user or group name or id</replaceable> specifies the name or AFS UID of each user for which to
 227       display group membership, or the name or AFS GID of each group for which to display the members. If identifying a group by its
 228       AFS GID, precede the GID with a hyphen (<emphasis role="bold">-</emphasis>) to indicate that it is a negative number.</para>
 229     </sect2>
 230
 231     <sect2 id="Header_119">
 232       <title>Example: Displaying the Members of a Group</title>
 233
 234       <indexterm>
 235         <primary>examples</primary>
 236
 237         <secondary>displaying members of a group</secondary>
 238       </indexterm>
 239
 240       <para>The following example displays the members of the group <emphasis role="bold">terry:team</emphasis>.</para>
 241
 242       <programlisting>
 243    % <emphasis role="bold">pts membership terry:team</emphasis>
 244    Members of terry:team (id: -286) are:
 245      terry
 246      smith
 247      pat
 248      johnson
 249 </programlisting>
 250     </sect2>
 251
 252     <sect2 id="Header_120">
 253       <title>Example: Displaying the Groups to Which a User Belongs</title>
 254
 255       <para>The following example displays the groups to which users <emphasis role="bold">terry</emphasis> and <emphasis
 256       role="bold">pat</emphasis> belong.</para>
 257
 258       <programlisting>
 259    % <emphasis role="bold">pts membership terry pat</emphasis>
 260    Groups terry (id: 1022) is a member of:
 261      smith:friends
 262      pat:accounting
 263      terry:team
 264    Groups pat (id: 1845) is a member of:
 265      pat:accounting
 266      sam:managers
 267      terry:team
 268 </programlisting>
 269     </sect2>
 270
 271     <sect2 id="HDRWQ66">
 272       <title>To Display the Groups a User or Group Owns</title>
 273
 274       <indexterm>
 275         <primary>displaying</primary>
 276
 277         <secondary>groups owned by a group</secondary>
 278       </indexterm>
 279
 280       <indexterm>
 281         <primary>commands</primary>
 282
 283         <secondary>pts listowned</secondary>
 284       </indexterm>
 285
 286       <indexterm>
 287         <primary>users</primary>
 288
 289         <secondary>listing groups owned</secondary>
 290       </indexterm>
 291
 292       <indexterm>
 293         <primary>groups</primary>
 294
 295         <secondary>listing groups owned</secondary>
 296       </indexterm>
 297
 298       <indexterm>
 299         <primary>pts commands</primary>
 300
 301         <secondary>listowned</secondary>
 302       </indexterm>
 303
 304       <para>Issue the <emphasis role="bold">pts listowned</emphasis> command to display the groups that a user or group owns.</para>
 305
 306       <programlisting>
 307    %  <emphasis role="bold">pts listowned</emphasis> &lt;<replaceable>user or group name or id</replaceable>&gt;<superscript>+</superscript>
 308 </programlisting>
 309
 310       <para>where <replaceable>user or group name or id</replaceable> specifies the name or AFS UID of each user, or the name or AFS
 311       GID of each group, for which to display group ownership. If identifying a group by its AFS GID, precede the GID with a hyphen
 312       (<emphasis role="bold">-</emphasis>) to indicate that it is a negative number.</para>
 313     </sect2>
 314
 315     <sect2 id="Header_122">
 316       <title>Example: Displaying the Groups a Group Owns</title>
 317
 318       <indexterm>
 319         <primary>examples</primary>
 320
 321         <secondary>displaying groups a group owns</secondary>
 322       </indexterm>
 323
 324       <para>The following example displays the groups that the group <emphasis role="bold">terry:team</emphasis> owns.</para>
 325
 326       <programlisting>
 327    % <emphasis role="bold">pts listowned -286</emphasis>
 328    Groups owned by terry:team (id: -286) are:
 329      terry:project
 330      terry:planners
 331 </programlisting>
 332     </sect2>
 333
 334     <sect2 id="Header_123">
 335       <title>Example: Displaying the Groups a User Owns</title>
 336
 337       <indexterm>
 338         <primary>examples</primary>
 339
 340         <secondary>displaying groups a user owns</secondary>
 341       </indexterm>
 342
 343       <para>The following example displays the groups that user <emphasis role="bold">pat</emphasis> owns.</para>
 344
 345       <programlisting>
 346    % <emphasis role="bold">pts listowned pat</emphasis>
 347    Groups owned by pat (id: 1845) are:
 348       pat:accounting
 349       pat:plans
 350
 351 </programlisting>
 352     </sect2>
 353
 354     <sect2 id="HDRWQ67">
 355       <title>To Display A Group Entry</title>
 356
 357       <indexterm>
 358         <primary>commands</primary>
 359
 360         <secondary>pts examine</secondary>
 361       </indexterm>
 362
 363       <indexterm>
 364         <primary>pts commands</primary>
 365
 366         <secondary>examine</secondary>
 367       </indexterm>
 368
 369       <indexterm>
 370         <primary>displaying</primary>
 371
 372         <secondary>group owner</secondary>
 373       </indexterm>
 374
 375       <indexterm>
 376         <primary>displaying</primary>
 377
 378         <secondary>group creator</secondary>
 379       </indexterm>
 380
 381       <indexterm>
 382         <primary>displaying</primary>
 383
 384         <secondary>group-creation quota</secondary>
 385       </indexterm>
 386
 387       <indexterm>
 388         <primary>groups</primary>
 389
 390         <secondary>owner, displaying</secondary>
 391       </indexterm>
 392
 393       <indexterm>
 394         <primary>groups</primary>
 395
 396         <secondary>creator, displaying</secondary>
 397       </indexterm>
 398
 399       <indexterm>
 400         <primary>users</primary>
 401
 402         <secondary>displaying number of group memberships</secondary>
 403       </indexterm>
 404
 405       <indexterm>
 406         <primary>group-creation quota</primary>
 407
 408         <secondary>displaying</secondary>
 409       </indexterm>
 410
 411       <para>Issue the <emphasis role="bold">pts examine</emphasis> command to display general information about a user or group,
 412       including its name, AFS ID, creator, and owner.</para>
 413
 414       <programlisting>
 415    %  <emphasis role="bold">pts examine</emphasis> &lt;<replaceable>user or group name or id</replaceable>&gt;<superscript>+</superscript>
 416 </programlisting>
 417
 418       <para>where <replaceable>user or group name or id</replaceable> specifies the name or AFS UID of each user, or the name or AFS
 419       GID of each group, for which to display group-related information. If identifying a group by its AFS GID, precede the GID with
 420       a hyphen (<emphasis role="bold">-</emphasis>) to indicate that it is a negative number.</para>
 421
 422       <para>The output includes information in the following fields:</para>
 423
 424       <variablelist>
 425         <varlistentry>
 426           <term><emphasis role="bold"><computeroutput>Name</computeroutput></emphasis></term>
 427
 428           <listitem>
 429             <para>For users, this is the character string typed when logging in. For machines, the name is the IP address; a zero in
 430             address field acts as a wildcard, matching any value. For most groups, this is a name of the form
 431             <replaceable>owner_name</replaceable><emphasis role="bold">:</emphasis><replaceable>group_name</replaceable>. Some
 432             groups created by your system administrator do not have the <replaceable>owner_name</replaceable> prefix. See <link
 433             linkend="HDRWQ63">Group Names</link>.</para>
 434           </listitem>
 435         </varlistentry>
 436
 437         <varlistentry>
 438           <term><emphasis role="bold"><computeroutput>id</computeroutput></emphasis></term>
 439
 440           <listitem>
 441             <para>This is a unique identification number that the AFS server processes use internally. It is similar in function to
 442             a UNIX UID, but operates in AFS rather than the UNIX file system. Users and machines have positive integer AFS user IDs
 443             (UIDs), and groups have negative integer AFS group IDs (GIDs). <indexterm>
 444                 <primary>AFS</primary>
 445
 446                 <secondary>UIDs and GIDs</secondary>
 447               </indexterm> <indexterm>
 448                 <primary>GID, AFS</primary>
 449               </indexterm> <indexterm>
 450                 <primary>UID, AFS</primary>
 451               </indexterm></para>
 452           </listitem>
 453         </varlistentry>
 454
 455         <varlistentry>
 456           <term><emphasis role="bold"><computeroutput>owner</computeroutput></emphasis></term>
 457
 458           <listitem>
 459             <para>This is the user or group that owns the entry and so can administer it.</para>
 460           </listitem>
 461         </varlistentry>
 462
 463         <varlistentry>
 464           <term><emphasis role="bold"><computeroutput>creator</computeroutput></emphasis></term>
 465
 466           <listitem>
 467             <para>The name of the user who issued the <emphasis role="bold">pts createuser</emphasis> and <emphasis role="bold">pts
 468             creategroup</emphasis> command to create the entry. This field is useful mainly as an audit trail and cannot be
 469             changed.</para>
 470           </listitem>
 471         </varlistentry>
 472
 473         <varlistentry>
 474           <term><emphasis role="bold"><computeroutput>membership</computeroutput></emphasis></term>
 475
 476           <listitem>
 477             <para>For users and machines, this indicates how many groups the user or machine belongs to. For groups, it indicates
 478             how many members belong to the group. This number cannot be set explicitly.</para>
 479           </listitem>
 480         </varlistentry>
 481
 482         <varlistentry>
 483           <term><emphasis role="bold"><computeroutput>flags</computeroutput></emphasis></term>
 484
 485           <listitem>
 486             <para>This field indicates who is allowed to list certain information about the entry or change it in certain ways. See
 487             <link linkend="HDRWQ74">Protecting Group-Related Information</link>.</para>
 488           </listitem>
 489         </varlistentry>
 490
 491         <varlistentry>
 492           <term><emphasis role="bold"><computeroutput>group quota</computeroutput></emphasis></term>
 493
 494           <listitem>
 495             <para>This field indicates how many more groups a user is allowed to create. It is set to 20 when a user entry is
 496             created. The creation quota for machines or groups is meaningless because it not possible to authenticate as a machine
 497             or group.</para>
 498           </listitem>
 499         </varlistentry>
 500       </variablelist>
 501     </sect2>
 502
 503     <sect2 id="Header_125">
 504       <title>Example: Listing Information about a Group</title>
 505
 506       <indexterm>
 507         <primary>examples</primary>
 508
 509         <secondary>displaying information about group</secondary>
 510       </indexterm>
 511
 512       <para>The following example displays information about the group <emphasis role="bold">pat:accounting</emphasis>, which
 513       includes members of the department that <emphasis role="bold">pat</emphasis> manages. Notice that the group is self-owned,
 514       which means that all of its members can administer it.</para>
 515
 516       <programlisting>
 517    % <emphasis role="bold">pts examine pat:accounting</emphasis>
 518    Name: pat:accounting, id: -673, owner: pat:accounting, creator: pat,
 519      membership: 15, flags: S-M--, group quota: 0
 520 </programlisting>
 521     </sect2>
 522
 523     <sect2 id="Header_126">
 524       <title>Example: Listing Group Information about a User</title>
 525
 526       <indexterm>
 527         <primary>examples</primary>
 528
 529         <secondary>displaying group information about a user</secondary>
 530       </indexterm>
 531
 532       <para>The following example displays group-related information about user <emphasis role="bold">pat</emphasis>. The two most
 533       interesting fields are <computeroutput>membership</computeroutput>, which shows that <emphasis role="bold">pat</emphasis>
 534       belongs to 12 groups, and <computeroutput>group quota</computeroutput>, which shows that <emphasis role="bold">pat</emphasis>
 535       can create another 17 groups.</para>
 536
 537       <programlisting>
 538   % <emphasis role="bold">pts examine pat</emphasis>
 539    Name: pat, id: 1045, owner: system:administrators, creator: admin,
 540      membership: 12, flags: S-M--, group quota: 17
 541 </programlisting>
 542     </sect2>
 543   </sect1>
 544
 545   <sect1 id="HDRWQ68">
 546     <title>Creating Groups and Adding Members</title>
 547
 548     <indexterm>
 549       <primary>adding</primary>
 550
 551       <secondary>users to groups</secondary>
 552     </indexterm>
 553
 554     <indexterm>
 555       <primary>creating</primary>
 556
 557       <secondary>groups</secondary>
 558     </indexterm>
 559
 560     <indexterm>
 561       <primary>groups</primary>
 562
 563       <secondary>creating</secondary>
 564     </indexterm>
 565
 566     <indexterm>
 567       <primary>groups</primary>
 568
 569       <secondary>adding members</secondary>
 570     </indexterm>
 571
 572     <indexterm>
 573       <primary>groups</primary>
 574
 575       <secondary>owner as administrator</secondary>
 576     </indexterm>
 577
 578     <para>Use the <emphasis role="bold">pts creategroup</emphasis> command to create a group and the <emphasis role="bold">pts
 579     adduser</emphasis> command to add members to it. Users and machines can belong to groups, but other groups cannot.</para>
 580
 581     <para>When you create a group, you normally become its owner automatically. This means you alone can administer it: add and
 582     remove members, change the group's name, transfer ownership of the group, or delete the group entirely. If you wish, you can
 583     designate another owner when you create the group, by including the <emphasis role="bold">-owner</emphasis> argument to the
 584     <emphasis role="bold">pts creategroup</emphasis> command. If you assign ownership to another group, the owning group must
 585     already exist and have at least one member. You can also change a group's ownership after creating it by using the <emphasis
 586     role="bold">pts chown</emphasis> command as described in <link linkend="HDRWQ72">Changing a Group's Owner or Name</link>.</para>
 587
 588     <sect2 id="HDRWQ69">
 589       <title>To Create a Group</title>
 590
 591       <indexterm>
 592         <primary>commands</primary>
 593
 594         <secondary>pts creategroup</secondary>
 595       </indexterm>
 596
 597       <indexterm>
 598         <primary>pts commands</primary>
 599
 600         <secondary>creategroup</secondary>
 601       </indexterm>
 602
 603       <para>Issue the <emphasis role="bold">pts creategroup</emphasis> command to create a group. Your group-creation quota
 604       decrements by one for each group.</para>
 605
 606       <programlisting>
 607    % <emphasis role="bold">pts creategroup -name</emphasis> &lt;<replaceable>group name</replaceable>&gt;+ [<emphasis role="bold">-owner</emphasis> &lt;<replaceable>owner of the group</replaceable>&gt;]
 608 </programlisting>
 609
 610       <para>where</para>
 611
 612       <variablelist>
 613         <varlistentry>
 614           <term><emphasis role="bold">cg</emphasis></term>
 615
 616           <listitem>
 617             <para>Is an alias for <emphasis role="bold">creategroup</emphasis> (and <emphasis role="bold">createg</emphasis> is the
 618             shortest acceptable abbreviation).</para>
 619           </listitem>
 620         </varlistentry>
 621
 622         <varlistentry>
 623           <term><emphasis role="bold">-name</emphasis></term>
 624
 625           <listitem>
 626             <para>Names each group to create. The name must have the following format:</para>
 627
 628             <para><replaceable>owner_name</replaceable><emphasis
 629             role="bold">:</emphasis><replaceable>group_name</replaceable></para>
 630
 631             <para>The <replaceable>owner_name</replaceable> prefix must accurately indicate the group's owner. By default, you are
 632             recorded as the owner, and the <replaceable>owner_name</replaceable> must be your AFS username. You can include the
 633             <emphasis role="bold">-owner</emphasis> argument to designate another AFS user or group as the owner, as long as you
 634             provide the required value in the <replaceable>owner_name</replaceable> field: <indexterm>
 635                 <primary>groups</primary>
 636
 637                 <secondary>rules for assigning ownership</secondary>
 638               </indexterm> <indexterm>
 639                 <primary>rules for assigning group names</primary>
 640               </indexterm></para>
 641
 642             <itemizedlist>
 643               <listitem>
 644                 <para>If the owner is a user, it must be the AFS username.</para>
 645               </listitem>
 646
 647               <listitem>
 648                 <para>If the owner is another regular group, it must match the owning group's <replaceable>owner_name</replaceable>
 649                 field. For example, if the owner is the group <emphasis role="bold">terry:associates</emphasis>, the owner field
 650                 must be <emphasis role="bold">terry</emphasis>.</para>
 651               </listitem>
 652
 653               <listitem>
 654                 <para>If the owner is a group without an <replaceable>owner_name</replaceable> prefix, it must be the owning group's
 655                 name.</para>
 656               </listitem>
 657             </itemizedlist>
 658
 659             <para>The name can include up to 63 characters including the colon. Use numbers and lowercase letters, but no spaces or
 660             punctuation characters other than the colon.</para>
 661           </listitem>
 662         </varlistentry>
 663
 664         <varlistentry>
 665           <term><emphasis role="bold">-owner</emphasis></term>
 666
 667           <listitem>
 668             <para>Is optional and assigns ownership to a user other than yourself, or to a group. If you specify a group, it must
 669             already exist and have at least one member. (This means that to make a group self-owned, you must issue the <emphasis
 670             role="bold">pts chown</emphasis> command after using this command to create the group, and the <emphasis role="bold">pts
 671             adduser</emphasis> command to add a member. See <link linkend="HDRWQ72">Changing a Group's Owner or Name</link>.)</para>
 672
 673             <para>Do not name a machine as the owner. Because no one can authenticate as a machine, there is no way to administer a
 674             group owned by a machine.</para>
 675           </listitem>
 676         </varlistentry>
 677       </variablelist>
 678     </sect2>
 679
 680     <sect2 id="Header_129">
 681       <title>Example: Creating a Group</title>
 682
 683       <para><indexterm>
 684           <primary>examples</primary>
 685
 686           <secondary>creating a group</secondary>
 687         </indexterm></para>
 688
 689       <para>In the following example user <emphasis role="bold">terry</emphasis> creates a group to include all the other users in
 690       his work team, and then examines the new group entry.</para>
 691
 692       <programlisting>
 693    % <emphasis role="bold">pts creategroup terry:team</emphasis>
 694    group terry:team has id -286
 695    % <emphasis role="bold">pts examine terry:team</emphasis>
 696    Name: terry:team, id: -286, owner: terry, creator: terry,
 697      membership: 0, flags: S----, group quota: 0.
 698 </programlisting>
 699     </sect2>
 700
 701     <sect2 id="HDRWQ70">
 702       <title>To Add Members to a Group</title>
 703
 704       <indexterm>
 705         <primary>groups</primary>
 706
 707         <secondary>adding members</secondary>
 708       </indexterm>
 709
 710       <indexterm>
 711         <primary>commands</primary>
 712
 713         <secondary>pts adduser</secondary>
 714       </indexterm>
 715
 716       <indexterm>
 717         <primary>pts commands</primary>
 718
 719         <secondary>adduser</secondary>
 720       </indexterm>
 721
 722       <indexterm>
 723         <primary>users</primary>
 724
 725         <secondary>adding as group members</secondary>
 726       </indexterm>
 727
 728       <para>Issue the <emphasis role="bold">pts adduser</emphasis> command to add one or more users to one or more groups. You can
 729       always add members to a group you own (either directly or because you belong to the owning group). If you belong to a group,
 730       you can add members if its fourth privacy flag is the lowercase letter <emphasis role="bold">a</emphasis>; see <link
 731       linkend="HDRWQ74">Protecting Group-Related Information</link>.</para>
 732
 733       <programlisting>
 734    % <emphasis role="bold">pts adduser -user</emphasis> &lt;<replaceable>user name</replaceable>&gt;<superscript>+</superscript> <emphasis
 735           role="bold">-group</emphasis> &lt;<replaceable>group name</replaceable>&gt;<superscript>+</superscript>
 736 </programlisting>
 737
 738       <para>You must add yourself to groups that you own, if that is appropriate. You do not belong automatically just because you
 739       own the group.</para>
 740
 741       <note>
 742         <para>If you already have a token when you are added to a group, you must issue the <emphasis role="bold">aklog</emphasis>
 743         command to reauthenticate before you can exercise the permissions granted to the group on ACLs.</para>
 744       </note>
 745
 746       <para>where</para>
 747
 748       <variablelist>
 749         <varlistentry>
 750           <term><emphasis role="bold">-user</emphasis></term>
 751
 752           <listitem>
 753             <para>Specifies the username of each user to add to the groups named by the <emphasis role="bold">-group</emphasis>
 754             argument. Groups cannot belong to other groups.</para>
 755           </listitem>
 756         </varlistentry>
 757
 758         <varlistentry>
 759           <term><emphasis role="bold">-group</emphasis></term>
 760
 761           <listitem>
 762             <para>Names each group to which to add users.</para>
 763           </listitem>
 764         </varlistentry>
 765       </variablelist>
 766     </sect2>
 767
 768     <sect2 id="Header_131">
 769       <title>Example: Adding Members to a Group</title>
 770
 771       <indexterm>
 772         <primary>examples</primary>
 773
 774         <secondary>adding members to a group</secondary>
 775       </indexterm>
 776
 777       <para>In this example, user <emphasis role="bold">terry</emphasis> adds himself, <emphasis role="bold">pat</emphasis>,
 778       <emphasis role="bold">indira</emphasis>, and <emphasis role="bold">smith</emphasis> to the group he just created, <emphasis
 779       role="bold">terry:team</emphasis>, and then verifies the new list of members.</para>
 780
 781       <programlisting>
 782    % <emphasis role="bold">pts adduser -user terry pat indira smith -group terry:team</emphasis>
 783    % <emphasis role="bold">pts members terry:team</emphasis>
 784    Members of terry:team (id: -286) are:
 785      terry
 786      pat
 787      indira
 788      smith
 789 </programlisting>
 790     </sect2>
 791   </sect1>
 792
 793   <sect1 id="HDRWQ71">
 794     <title>Removing Users from a Group and Deleting a Group</title>
 795
 796     <indexterm>
 797       <primary>groups</primary>
 798
 799       <secondary>removing members</secondary>
 800     </indexterm>
 801
 802     <indexterm>
 803       <primary>groups</primary>
 804
 805       <secondary>deleting</secondary>
 806     </indexterm>
 807
 808     <indexterm>
 809       <primary>removing</primary>
 810
 811       <secondary>users from groups</secondary>
 812     </indexterm>
 813
 814     <indexterm>
 815       <primary>deleting groups</primary>
 816     </indexterm>
 817
 818     <indexterm>
 819       <primary>removing</primary>
 820
 821       <secondary>users from groups</secondary>
 822     </indexterm>
 823
 824     <indexterm>
 825       <primary>users</primary>
 826
 827       <secondary>removing from groups</secondary>
 828     </indexterm>
 829
 830     <indexterm>
 831       <primary>removing</primary>
 832
 833       <secondary>obsolete ACL entries</secondary>
 834     </indexterm>
 835
 836     <indexterm>
 837       <primary>ACL</primary>
 838
 839       <secondary>removing obsolete entries</secondary>
 840     </indexterm>
 841
 842     <para>You can use the following commands to remove groups and their members:</para>
 843
 844     <itemizedlist>
 845       <listitem>
 846         <para>To remove a user from a group, use the <emphasis role="bold">pts removeuser</emphasis> command</para>
 847       </listitem>
 848
 849       <listitem>
 850         <para>To delete a group entirely, use the <emphasis role="bold">pts delete</emphasis> command</para>
 851       </listitem>
 852
 853       <listitem>
 854         <para>To remove deleted groups from ACLs, use the <emphasis role="bold">fs cleanacl</emphasis> command</para>
 855       </listitem>
 856     </itemizedlist>
 857
 858     <para>When a group that you created is deleted, your group-creation quota increments by one, even if you no longer own the
 859     group.</para>
 860
 861     <para>When a group or user is deleted, its AFS ID appears on ACLs in place of its AFS name. You can use the <emphasis
 862     role="bold">fs cleanacl</emphasis> command to remove these obsolete entries from ACLs on which you have the <emphasis
 863     role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) permission.</para>
 864
 865     <sect2 id="Header_133">
 866       <title>To Remove Members from a Group</title>
 867
 868       <indexterm>
 869         <primary>commands</primary>
 870
 871         <secondary>pts removeuser</secondary>
 872       </indexterm>
 873
 874       <indexterm>
 875         <primary>pts commands</primary>
 876
 877         <secondary>removeuser</secondary>
 878       </indexterm>
 879
 880       <para>Issue the <emphasis role="bold">pts removeuser</emphasis> command to remove one or more members from one or more groups.
 881       You can always remove members from a group that you own (either directly or because you belong to the owning group). If you
 882       belong to a group, you can remove members if its fifth privacy flag is the lowercase letter <emphasis
 883       role="bold">r</emphasis>; see <link linkend="HDRWQ74">Protecting Group-Related Information</link>. (To display a group's
 884       owner, use the <emphasis role="bold">pts examine</emphasis> command as described in <link linkend="HDRWQ67">To Display A Group
 885       Entry</link>.)</para>
 886
 887       <programlisting>
 888    % <emphasis role="bold">pts removeuser -user</emphasis>  &lt;<replaceable>user name</replaceable>&gt;<superscript>+</superscript>  <emphasis
 889           role="bold">-group</emphasis> &lt;<replaceable>group name</replaceable>&gt;<superscript>+</superscript>
 890 </programlisting>
 891
 892       <para>where</para>
 893
 894       <variablelist>
 895         <varlistentry>
 896           <term><emphasis role="bold">-user</emphasis></term>
 897
 898           <listitem>
 899             <para>Specifies the username of each user to remove from the groups named by the <emphasis role="bold">-group</emphasis>
 900             argument.</para>
 901           </listitem>
 902         </varlistentry>
 903
 904         <varlistentry>
 905           <term><emphasis role="bold">-group</emphasis></term>
 906
 907           <listitem>
 908             <para>Names each group from which to remove users.</para>
 909           </listitem>
 910         </varlistentry>
 911       </variablelist>
 912     </sect2>
 913
 914     <sect2 id="Header_134">
 915       <title>Example: Removing Group Members</title>
 916
 917       <indexterm>
 918         <primary>examples</primary>
 919
 920         <secondary>removing group members</secondary>
 921       </indexterm>
 922
 923       <para>The following example removes user <emphasis role="bold">pat</emphasis> from both the <emphasis
 924       role="bold">terry:team</emphasis> and <emphasis role="bold">terry:friends</emphasis> groups.</para>
 925
 926       <programlisting>
 927    % <emphasis role="bold">pts removeuser  pat -group terry:team terry:friends</emphasis>
 928 </programlisting>
 929     </sect2>
 930
 931     <sect2 id="Header_135">
 932       <title>To Delete a Group</title>
 933
 934       <indexterm>
 935         <primary>commands</primary>
 936
 937         <secondary>pts delete</secondary>
 938       </indexterm>
 939
 940       <indexterm>
 941         <primary>pts commands</primary>
 942
 943         <secondary>delete</secondary>
 944       </indexterm>
 945
 946       <para>Issue the <emphasis role="bold">pts delete</emphasis> command to delete a group. You can always delete a group that you
 947       own (either directly or because you belong to the owning group). To display a group's owner, use the <emphasis role="bold">pts
 948       examine</emphasis> command as described in <link linkend="HDRWQ67">To Display A Group Entry</link>.</para>
 949
 950       <programlisting>
 951    % <emphasis role="bold">pts delete</emphasis> &lt;<replaceable>user or group name or id</replaceable>&gt;<superscript>+</superscript>
 952 </programlisting>
 953
 954       <para>where <replaceable>user or group name or id</replaceable> specifies the name or AFS UID of each user, or the name or AFS
 955       GID of each group, to delete. If identifying a group by its AFS GID, precede the GID with a hyphen (<emphasis
 956       role="bold">-</emphasis>) to indicate that it is a negative number.</para>
 957     </sect2>
 958
 959     <sect2 id="Header_136">
 960       <title>Example: Deleting a Group</title>
 961
 962       <para><indexterm>
 963           <primary>examples</primary>
 964
 965           <secondary>deleting a group</secondary>
 966         </indexterm></para>
 967
 968       <para>In the following example, the group <emphasis role="bold">terry:team</emphasis> is deleted.</para>
 969
 970       <programlisting>
 971    % <emphasis role="bold">pts delete terry:team</emphasis>
 972 </programlisting>
 973     </sect2>
 974
 975     <sect2 id="Header_137">
 976       <title>To Remove Obsolete ACL Entries</title>
 977
 978       <indexterm>
 979         <primary>commands</primary>
 980
 981         <secondary>fs cleanacl</secondary>
 982       </indexterm>
 983
 984       <indexterm>
 985         <primary>fs commands</primary>
 986
 987         <secondary>cleanacl</secondary>
 988       </indexterm>
 989
 990       <para>Issue the <emphasis role="bold">fs cleanacl</emphasis> command to remove obsolete entries from ACLs after the
 991       corresponding user or group has been deleted.</para>
 992
 993       <programlisting>
 994    % <emphasis role="bold">fs cleanacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;<superscript>+</superscript>]
 995 </programlisting>
 996
 997       <para>where <replaceable>dir/file path</replaceable> name each directory for which to clean the ACL. If you omit this
 998       argument, the current working directory's ACL is cleaned.</para>
 999
1000       <para><indexterm>
1001           <primary>examples</primary>
1002
1003           <secondary>removing deleted groups from ACLs</secondary>
1004         </indexterm></para>
1005     </sect2>
1006
1007     <sect2 id="Header_138">
1008       <title>Example: Removing an Obsolete ACL Entry</title>
1009
1010       <para>After the group <emphasis role="bold">terry:team</emphasis> is deleted, its AFS GID (-286) appears on ACLs instead of
1011       its name. In this example, user <emphasis role="bold">terry</emphasis> cleans it from the ACL on the plans directory in his
1012       home directory.</para>
1013
1014       <programlisting>
1015    % <emphasis role="bold">fs listacl plans</emphasis>
1016    Access list for plans is
1017    Normal rights:
1018      terry rlidwka
1019      -268 rlidwk
1020      sam rliw
1021    % <emphasis role="bold">fs cleanacl plans</emphasis>
1022    % <emphasis role="bold">fs listacl plans</emphasis>
1023    Access list for plans is
1024    Normal rights:
1025      terry rlidwka
1026      sam rliw
1027 </programlisting>
1028     </sect2>
1029   </sect1>
1030
1031   <sect1 id="HDRWQ72">
1032     <title>Changing a Group's Owner or Name</title>
1033
1034     <indexterm>
1035       <primary>groups</primary>
1036
1037       <secondary>changing name</secondary>
1038     </indexterm>
1039
1040     <indexterm>
1041       <primary>changing</primary>
1042
1043       <secondary>group owner</secondary>
1044     </indexterm>
1045
1046     <indexterm>
1047       <primary>changing</primary>
1048
1049       <secondary>group name</secondary>
1050     </indexterm>
1051
1052     <indexterm>
1053       <primary>groups</primary>
1054
1055       <secondary>changing owner</secondary>
1056     </indexterm>
1057
1058     <para>To change a group's owner, use the <emphasis role="bold">pts chown</emphasis> command. To change its name, use the
1059     <emphasis role="bold">pts rename</emphasis> command.</para>
1060
1061     <para>You can change the owner or name of a group that you own (either directly or because you belong to the owning group). You
1062     can assign group ownership to another user, another group, or the group itself. If you are not already a member of the group and
1063     need to be, use the <emphasis role="bold">pts adduser</emphasis> command before transferring ownership, following the
1064     instructions in <link linkend="HDRWQ70">To Add Members to a Group</link>.</para>
1065
1066     <para>The <emphasis role="bold">pts chown</emphasis> command automatically changes a group's
1067     <replaceable>owner_name</replaceable> prefix to indicate the new owner. If the new owner is a group, only its
1068     <replaceable>owner_name</replaceable> prefix is used, not its entire name. However, the change in
1069     <replaceable>owner_name</replaceable> prefix command does not propagate to any groups owned by the group whose owner is
1070     changing. If you want their <replaceable>owner_name</replaceable> prefixes to indicate the correct owner, you must use the
1071     <emphasis role="bold">pts rename</emphasis> command.</para>
1072
1073     <para>Otherwise, you normally use the <emphasis role="bold">pts rename</emphasis> command to change only the
1074     <replaceable>group_name</replaceable> part of a group name (the part that follows the colon). You can change the
1075     <replaceable>owner_name</replaceable> prefix only to reflect the actual owner.</para>
1076
1077     <sect2 id="HDRWQ73">
1078       <title>To Change a Group's Owner</title>
1079
1080       <indexterm>
1081         <primary>commands</primary>
1082
1083         <secondary>pts chown</secondary>
1084       </indexterm>
1085
1086       <indexterm>
1087         <primary>pts commands</primary>
1088
1089         <secondary>chown</secondary>
1090       </indexterm>
1091
1092       <para>Issue the <emphasis role="bold">pts chown</emphasis> command to change a group's name.</para>
1093
1094       <programlisting>
1095    % <emphasis role="bold">pts chown</emphasis>  &lt;<replaceable>group name</replaceable>&gt; &lt;<replaceable>new owner</replaceable>&gt;
1096 </programlisting>
1097
1098       <para>where</para>
1099
1100       <variablelist>
1101         <varlistentry>
1102           <term><emphasis role="bold"><replaceable>group name</replaceable></emphasis></term>
1103
1104           <listitem>
1105             <para>Specifies the current name of the group to which to assign a new owner.</para>
1106           </listitem>
1107         </varlistentry>
1108
1109         <varlistentry>
1110           <term><emphasis role="bold"><replaceable>new owner</replaceable></emphasis></term>
1111
1112           <listitem>
1113             <para>Names the user or group that is to own the group.</para>
1114           </listitem>
1115         </varlistentry>
1116       </variablelist>
1117     </sect2>
1118
1119     <sect2 id="Header_141">
1120       <title>Example: Changing a Group's Owner to Another User</title>
1121
1122       <indexterm>
1123         <primary>examples</primary>
1124
1125         <secondary>changing group owner</secondary>
1126       </indexterm>
1127
1128       <para>In the following example, user <emphasis role="bold">pat</emphasis> transfers ownership of the group <emphasis
1129       role="bold">pat:staff</emphasis> to user <emphasis role="bold">terry</emphasis>. Its name changes automatically to <emphasis
1130       role="bold">terry:staff</emphasis>, as confirmed by the <emphasis role="bold">pts examine</emphasis> command.</para>
1131
1132       <programlisting>
1133    % <emphasis role="bold">pts chown pat:staff terry</emphasis>
1134    % <emphasis role="bold">pts examine terry:staff</emphasis>
1135    Name: terry:staff, id: -534, owner: terry, creator: pat,
1136      membership: 15, flags: SOm--, group quota: 0.
1137 </programlisting>
1138     </sect2>
1139
1140     <sect2 id="Header_142">
1141       <title>Example: Changing a Group's Owner to Itself</title>
1142
1143       <indexterm>
1144         <primary>examples</primary>
1145
1146         <secondary>creating a self-owned group</secondary>
1147       </indexterm>
1148
1149       <para>In the following example, user <emphasis role="bold">terry</emphasis> makes the <emphasis
1150       role="bold">terry:team</emphasis> group a self-owned group. Its name does not change because its
1151       <replaceable>owner_name</replaceable> prefix is already <emphasis role="bold">terry</emphasis>.</para>
1152
1153       <programlisting>
1154    % <emphasis role="bold">pts chown terry:team terry:team</emphasis>
1155    % <emphasis role="bold">pts examine terry:team</emphasis>
1156    Name: terry:team, id: -286, owner: terry:team, creator: terry,
1157      membership: 6, flags: SOm--, group quota: 0.
1158 </programlisting>
1159     </sect2>
1160
1161     <sect2 id="Header_143">
1162       <title>Example: Changing a Group's Owner to a Group</title>
1163
1164       <para>In this example, user <emphasis role="bold">sam</emphasis> transfers ownership of the group <emphasis
1165       role="bold">sam:project</emphasis> to the group <emphasis role="bold">smith:cpa</emphasis>. Its name changes automatically to
1166       <emphasis role="bold">smith:project</emphasis>, because <emphasis role="bold">smith</emphasis> is the
1167       <replaceable>owner_name</replaceable> prefix of the group that now owns it. The <emphasis role="bold">pts examine</emphasis>
1168       command displays the group's status before and after the change.</para>
1169
1170       <programlisting>
1171    % <emphasis role="bold">pts examine sam:project</emphasis>
1172    Name: sam:project, id: -522, owner: sam, creator: sam,
1173      membership: 33, flags: SOm--, group quota: 0.
1174    % <emphasis role="bold">pts chown sam:project smith:cpa</emphasis>
1175    % <emphasis role="bold">pts examine smith:project</emphasis>
1176    Name: smith:project, id: -522, owner: smith:cpa, creator: sam,
1177      membership: 33, flags: SOm--, group quota: 0.
1178 </programlisting>
1179     </sect2>
1180
1181     <sect2 id="Header_144">
1182       <title>To Change a Group's Name</title>
1183
1184       <indexterm>
1185         <primary>commands</primary>
1186
1187         <secondary>pts rename</secondary>
1188       </indexterm>
1189
1190       <indexterm>
1191         <primary>pts commands</primary>
1192
1193         <secondary>rename</secondary>
1194       </indexterm>
1195
1196       <para>Issue the <emphasis role="bold">pts rename</emphasis> command to change a group's name.</para>
1197
1198       <programlisting>
1199    % <emphasis role="bold">pts rename</emphasis>  &lt;<replaceable>old name</replaceable>&gt; &lt;<replaceable>new name</replaceable>&gt;
1200 </programlisting>
1201
1202       <para>where</para>
1203
1204       <variablelist>
1205         <varlistentry>
1206           <term><emphasis role="bold"><replaceable>old name</replaceable></emphasis></term>
1207
1208           <listitem>
1209             <para>Specifies the group's current name.</para>
1210           </listitem>
1211         </varlistentry>
1212
1213         <varlistentry>
1214           <term><emphasis role="bold"><replaceable>new name</replaceable></emphasis></term>
1215
1216           <listitem>
1217             <para>Specifies the complete new name to assign to the group. The <replaceable>owner_name</replaceable> prefix must
1218             correctly indicate the group's owner.</para>
1219           </listitem>
1220         </varlistentry>
1221       </variablelist>
1222     </sect2>
1223
1224     <sect2 id="Header_145">
1225       <title>Example: Changing a Group's <replaceable>group_name</replaceable> Suffix</title>
1226
1227       <indexterm>
1228         <primary>examples</primary>
1229
1230         <secondary>changing group name</secondary>
1231       </indexterm>
1232
1233       <para>The following example changes the name of the <emphasis role="bold">smith:project</emphasis> group to <emphasis
1234       role="bold">smith:fiscal-closing</emphasis>. The group's <replaceable>owner_name</replaceable> prefix remains <emphasis
1235       role="bold">smith</emphasis> because its owner is not changing.</para>
1236
1237       <programlisting>
1238    % <emphasis role="bold">pts examine smith:project</emphasis>
1239    Name: smith:project, id: -522, owner: smith:cpa, creator: sam,
1240      membership: 33, flags: SOm--, group quota: 0.
1241    % <emphasis role="bold">pts rename smith:project smith:fiscal-closing</emphasis>
1242    % <emphasis role="bold">pts examine smith:fiscal-closing</emphasis>
1243    Name: smith:fiscal-closing, id: -522, owner: smith:cpa, creator: sam,
1244      membership: 33, flags: SOm--, group quota: 0.
1245 </programlisting>
1246     </sect2>
1247
1248     <sect2 id="Header_146">
1249       <title>Example: Changing a Group's <replaceable>owner_name</replaceable> Prefix</title>
1250
1251       <para>In a previous example, user <emphasis role="bold">pat</emphasis> transferred ownership of the group <emphasis
1252       role="bold">pat:staff</emphasis> to user <emphasis role="bold">terry</emphasis>. Its name changed automatically to <emphasis
1253       role="bold">terry:staff</emphasis>. However, a group that <emphasis role="bold">terry:staff</emphasis> owns is still called
1254       <emphasis role="bold">pat:plans</emphasis>, because the change to a group's <replaceable>owner_name</replaceable> that results
1255       from the <emphasis role="bold">pts chown</emphasis> command does not propagate to any groups it owns. In this example, a
1256       member of <emphasis role="bold">terry:staff</emphasis> uses the <emphasis role="bold">pts rename</emphasis> command to change
1257       the name to <emphasis role="bold">terry:plans</emphasis> to reflect its actual ownership.</para>
1258
1259       <programlisting>
1260    % <emphasis role="bold">pts examine pat:plans</emphasis>
1261    Name: pat:plans, id: -535, owner: terry:staff, creator: pat,
1262      membership: 8, flags: SOm--, group quota: 0.
1263    % <emphasis role="bold">pts rename pat:plans terry:plans</emphasis>
1264    % <emphasis role="bold">pts examine terry:plans</emphasis>
1265    Name: terry:plans, id: -535, owner: terry:staff, creator: pat,
1266      membership: 8, flags: SOm--, group quota: 0.
1267 </programlisting>
1268     </sect2>
1269   </sect1>
1270
1271   <sect1 id="HDRWQ74">
1272     <title>Protecting Group-Related Information</title>
1273
1274     <indexterm>
1275       <primary>protection</primary>
1276
1277       <secondary>group-related information</secondary>
1278     </indexterm>
1279
1280     <indexterm>
1281       <primary>groups</primary>
1282
1283       <secondary>privacy flags</secondary>
1284     </indexterm>
1285
1286     <indexterm>
1287       <primary>privacy flags on groups</primary>
1288     </indexterm>
1289
1290     <indexterm>
1291       <primary>s privacy flag on groups</primary>
1292     </indexterm>
1293
1294     <indexterm>
1295       <primary>o privacy flag on groups</primary>
1296     </indexterm>
1297
1298     <indexterm>
1299       <primary>m privacy flag on groups</primary>
1300     </indexterm>
1301
1302     <indexterm>
1303       <primary>a privacy flag on groups</primary>
1304     </indexterm>
1305
1306     <indexterm>
1307       <primary>r privacy flag on groups</primary>
1308     </indexterm>
1309
1310     <para>A group's <emphasis>privacy flags</emphasis> control who can administer it in various ways. The privacy flags appear in
1311     the <computeroutput>flags</computeroutput> field of the output from the <emphasis role="bold">pts examine</emphasis> command
1312     command; see <link linkend="HDRWQ67">To Display A Group Entry</link>. To set the privacy flags for a group you own, use the
1313     <emphasis role="bold">pts setfields</emphasis> command as instructed in <link linkend="HDRWQ75">To Set a Group's Privacy
1314     Flags</link>.</para>
1315
1316     <sect2 id="HDRPRIVACY-FLAGS">
1317       <title>Interpreting the Privacy Flags</title>
1318
1319       <para>The five privacy flags always appear, and always must be set, in the following order:</para>
1320
1321       <variablelist>
1322         <varlistentry>
1323           <term><emphasis role="bold">s</emphasis></term>
1324
1325           <listitem>
1326             <para>Controls who can issue the <emphasis role="bold">pts examine</emphasis> command to display the entry.</para>
1327           </listitem>
1328         </varlistentry>
1329
1330         <varlistentry>
1331           <term><emphasis role="bold">o</emphasis></term>
1332
1333           <listitem>
1334             <para>Controls who can issue the <emphasis role="bold">pts listowned</emphasis> command to list the groups that a user
1335             or group owns.</para>
1336           </listitem>
1337         </varlistentry>
1338
1339         <varlistentry>
1340           <term><emphasis role="bold">m</emphasis></term>
1341
1342           <listitem>
1343             <para>Controls who can issue the <emphasis role="bold">pts membership</emphasis> command to list the groups a user or
1344             machine belongs to, or which users or machines belong to a group.</para>
1345           </listitem>
1346         </varlistentry>
1347
1348         <varlistentry>
1349           <term><emphasis role="bold">a</emphasis></term>
1350
1351           <listitem>
1352             <para>Controls who can issue the <emphasis role="bold">pts adduser</emphasis> command to add a user or machine to a
1353             group.</para>
1354           </listitem>
1355         </varlistentry>
1356
1357         <varlistentry>
1358           <term><emphasis role="bold">r</emphasis></term>
1359
1360           <listitem>
1361             <para>Controls who can issue the <emphasis role="bold">pts removeuser</emphasis> command to remove a user or machine
1362             from a group.</para>
1363           </listitem>
1364         </varlistentry>
1365       </variablelist>
1366
1367       <para>Each flag can take three possible types of values to enable a different set of users to issue the corresponding
1368       command:</para>
1369
1370       <itemizedlist>
1371         <listitem>
1372           <para>A hyphen (<emphasis role="bold">-</emphasis>) means that the group's owner can issue the command, along with the
1373           administrators who belong to the <emphasis role="bold">system:administrators</emphasis> group.</para>
1374         </listitem>
1375
1376         <listitem>
1377           <para>The lowercase version of the letter means that members of the group can issue the command, along with the users
1378           indicated by the hyphen.</para>
1379         </listitem>
1380
1381         <listitem>
1382           <para>The uppercase version of the letter means that anyone can issue the command.</para>
1383         </listitem>
1384       </itemizedlist>
1385
1386       <para>For example, the flags <computeroutput>SOmar</computeroutput> on a group entry indicate that anyone can examine the
1387       group's entry and list the groups that it owns, and that only the group's members can list, add, or remove its members.</para>
1388
1389       <para>The default privacy flags for groups are <computeroutput>S-M--</computeroutput>, meaning that anyone can display the
1390       entry and list the members of the group, but only the group's owner and members of the <emphasis
1391       role="bold">system:administrators</emphasis> group can perform other functions.</para>
1392     </sect2>
1393
1394     <sect2 id="HDRWQ75">
1395       <title>To Set a Group's Privacy Flags</title>
1396
1397       <indexterm>
1398         <primary>commands</primary>
1399
1400         <secondary>pts setfields</secondary>
1401       </indexterm>
1402
1403       <indexterm>
1404         <primary>pts commands</primary>
1405
1406         <secondary>setfields</secondary>
1407       </indexterm>
1408
1409       <para>Issue the <emphasis role="bold">pts setfields</emphasis> command to set the privacy flags on one or more groups.</para>
1410
1411       <programlisting>
1412    % <emphasis role="bold">pts setfields -nameorid</emphasis> &lt;<replaceable>user or group name or id</replaceable>&gt;<superscript>+</superscript>
1413                    <emphasis role="bold">-access</emphasis> &lt;<replaceable>set privacy flags</replaceable>&gt;
1414 </programlisting>
1415
1416       <para>where</para>
1417
1418       <variablelist>
1419         <varlistentry>
1420           <term><emphasis role="bold">-nameorid</emphasis></term>
1421
1422           <listitem>
1423             <para>Specifies the name or AFS GID of each group for which to set the privacy flags. If identifying a group by its AFS
1424             GID, precede the GID with a hyphen (<emphasis role="bold">-</emphasis>) to indicate that it is a negative number.</para>
1425           </listitem>
1426         </varlistentry>
1427
1428         <varlistentry>
1429           <term><emphasis role="bold">-access</emphasis></term>
1430
1431           <listitem>
1432             <para>Specifies the privacy flags to set for each group. Observe the following rules:</para>
1433
1434             <itemizedlist>
1435               <listitem>
1436                 <para>Provide a value for all five flags in the order <emphasis role="bold">somar</emphasis>.</para>
1437               </listitem>
1438
1439               <listitem>
1440                 <para>Set the first flag to lowercase <emphasis role="bold">s</emphasis> or uppercase <emphasis
1441                 role="bold">S</emphasis> only.</para>
1442               </listitem>
1443
1444               <listitem>
1445                 <para>Set the second flag to the hyphen (<emphasis role="bold">-</emphasis>) or uppercase <emphasis
1446                 role="bold">O</emphasis> only. For groups, AFS interprets the hyphen as equivalent to lowercase <emphasis
1447                 role="bold">o</emphasis> (that is, members of a group can always list the groups that it owns).</para>
1448               </listitem>
1449
1450               <listitem>
1451                 <para>Set the third flag to the hyphen (<emphasis role="bold">-</emphasis>), lowercase <emphasis
1452                 role="bold">m</emphasis>, or uppercase <emphasis role="bold">M</emphasis>.</para>
1453               </listitem>
1454
1455               <listitem>
1456                 <para>Set the fourth flag to the hyphen (<emphasis role="bold">-</emphasis>), lowercase <emphasis
1457                 role="bold">a</emphasis>, or uppercase <emphasis role="bold">A</emphasis>. The uppercase <emphasis
1458                 role="bold">A</emphasis> is not a secure choice, because it permits anyone to add members to the group.</para>
1459               </listitem>
1460
1461               <listitem>
1462                 <para>Set the fifth flag to the hyphen (<emphasis role="bold">-</emphasis>) or lowercase <emphasis
1463                 role="bold">r</emphasis> only.</para>
1464               </listitem>
1465             </itemizedlist>
1466           </listitem>
1467         </varlistentry>
1468       </variablelist>
1469     </sect2>
1470
1471     <sect2 id="Header_150">
1472       <title>Example: Setting a Group's Privacy Flags</title>
1473
1474       <indexterm>
1475         <primary>examples</primary>
1476
1477         <secondary>setting group's privacy flags</secondary>
1478       </indexterm>
1479
1480       <para>The following example sets the privacy flags on the <emphasis role="bold">terry:team</emphasis> group to set the
1481       indicated pattern of administrative privilege.</para>
1482
1483       <programlisting>
1484    % <emphasis role="bold">pts setfields terry:team -access SOm--</emphasis>
1485
1486 </programlisting>
1487
1488       <itemizedlist>
1489         <listitem>
1490           <para>Everyone can issue the <emphasis role="bold">pts examine</emphasis> command to display general information about it
1491           (uppercase <emphasis role="bold">S</emphasis>).</para>
1492         </listitem>
1493
1494         <listitem>
1495           <para>Everyone can issue the <emphasis role="bold">pts listowned</emphasis> command to display the groups it owns
1496           (uppercase <emphasis role="bold">O</emphasis>).</para>
1497         </listitem>
1498
1499         <listitem>
1500           <para>The members of the group can issue the <emphasis role="bold">pts membership</emphasis> command to display the
1501           group's members (lowercase <emphasis role="bold">m</emphasis>).</para>
1502         </listitem>
1503
1504         <listitem>
1505           <para>Only the group's owner, user <emphasis role="bold">terry</emphasis>, can issue the <emphasis role="bold">pts
1506           adduser</emphasis> command to add members (the hyphen).</para>
1507         </listitem>
1508
1509         <listitem>
1510           <para>Only the group's owner, user <emphasis role="bold">terry</emphasis>, can issue the <emphasis role="bold">pts
1511           removeuser</emphasis> command to remove members (the hyphen).</para>
1512         </listitem>
1513       </itemizedlist>
1514     </sect2>
1515   </sect1>
1516 </chapter>