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

   1 =head1 NAME
   2
   3 pts_creategroup - Creates an (empty) Protection Database group entry
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<pts creategroup> S<<< B<-name> <I<group name>>+ >>>
  11     S<<< [B<-owner> <I<owner of the group>>] >>>
  12     S<<< [B<-id> <I<id (negated) for the group>>+] >>> S<<< [B<-cell> <I<cell name>>] >>>
  13     [B<-noauth>] [B<-localauth>] [B<-force>] [B<-help>]
  14     [B<-auth>] [B<-encrypt>] S<<< [B<-config> <I<config directory>>] >>>
  15
  16 B<pts createg> S<<< B<-na> <I<group name>>+ >>>  S<<< [B<-o> <I<owner of the group>>] >>>
  17     S<<< [B<-i> <I<id (negated) for the group>>+] >>> S<<< [B<-c> <I<cell name>>] >>>
  18     [B<-no>] [B<-l>] [B<-f>] [B<-h>]
  19     [B<-a>] [B<-e>] S<<< [B<-co> <I<config directory>>] >>>
  20
  21 B<pts cg> S<<< B<-na> <I<group name>>+ >>> S<<< [B<-o> <I<owner of the group>>] >>>
  22     S<<< [B<-i> <I<id (negated) for the group>>+] >>> S<<< [B<-c> <I<cell name>>] >>>
  23     [B<-no>] [B<-l>] [B<-f>] [B<-h>]
  24     [B<-a>] [B<-e>] S<<< [B<-co> <I<config directory>>] >>>
  25
  26 =for html
  27 </div>
  28
  29 =head1 DESCRIPTION
  30
  31 The B<pts creategroup> command creates an entry in the Protection Database
  32 for each group specified by the B<-name> argument. The entry records the
  33 issuer of the command as the group's creator, and as the group's owner
  34 unless the B<-owner> argument names an alternate user or group as the
  35 owner.
  36
  37 There are two types of groups:
  38
  39 =over 4
  40
  41 =item *
  42
  43 I<regular>, the names of which have two parts separated by a colon. The
  44 part before the colon names the group's owner.  Any user can create such
  45 groups.
  46
  47 =item *
  48
  49 I<prefix-less>, which do not have an owner prefix. Only members of the
  50 system:administrators group can create prefix-less groups.
  51
  52 =back
  53
  54 Creating a group lowers the issuer's group-creation quota by one. This is
  55 true even if the B<-owner> argument is used to assign ownership to an
  56 alternate user or group. To display a user's group-creation quota, use the
  57 B<pts examine> command; to set it, use the B<pts setfields> command.
  58
  59 AFS group ID (AFS GID) numbers are negative integers and by default the
  60 Protection Server assigns a GID that is one less (more negative) than the
  61 current value of the C<max group id> counter in the Protection Database,
  62 decrementing the counter by one for each group. Members of the
  63 system:administrators group can use the B<-id> argument to assign specific
  64 AFS GID numbers. If any of the specified GIDs is lower (more negative)
  65 than the current value of the C<max group id> counter, the counter is
  66 reset to that value. It is acceptable to specify a GID greater (less
  67 negative) than the current value of the counter, but the creation
  68 operation fails if an existing group already has it. To display or set the
  69 value of the C<max group id> counter, use the B<pts listmax> or B<pts
  70 setmax> command, respectively.
  71
  72 =head1 OUTPUT
  73
  74 The command generates the following string to confirm creation of each
  75 group:
  76
  77    group <name> has id <AFS GID>
  78
  79 =head1 CAUTIONS
  80
  81 Although using the B<-owner> argument to designate a machine entry as a
  82 group's owner does not generate an error, it is not recommended. The
  83 Protection Server does not extend the usual privileges of group ownership
  84 to users logged onto the machine.
  85
  86 =head1 OPTIONS
  87
  88 =over 4
  89
  90 =item B<-name> <I<group name>>
  91
  92 Specifies the name of each group to create. Provide a string of up to 63
  93 characters, which can include lowercase (but not uppercase) letters,
  94 numbers, and punctuation marks. A regular name includes a single colon
  95 (C<:>) to separate the two parts of the name; the colon cannot appear in a
  96 prefix-less group name.
  97
  98 A regular group's name must have the following format:
  99
 100    <owner_name>:<group_name>
 101
 102 and the <owner_name> field must reflect the actual owner of the group, as
 103 follows:
 104
 105 =over 4
 106
 107 =item *
 108
 109 If the optional B<-owner> argument is not included, the field must match
 110 the AFS username under which the issuer is currently authenticated.
 111
 112 =item *
 113
 114 If the B<-owner> argument names an alternate AFS user, the field must
 115 match that AFS username.
 116
 117 =item *
 118
 119 If the B<-owner> argument names another regular group, the field must
 120 match the owning group's owner field (the part of its name before the
 121 colon). If the B<-owner> argument names a prefix-less group, the field
 122 must match the owning group's complete name.
 123
 124 =back
 125
 126 =item B<-owner> <I<owner of the group>>
 127
 128 Specifies a user or group as the owner for each group, rather than the
 129 issuer of the command. Provide either an AFS username or the name of a
 130 regular or prefix-less group. An owning group must already have at least
 131 one member. This requirement prevents assignment of self-ownership to a
 132 group during its creation; use the B<pts chown> command after issuing this
 133 command, if desired.
 134
 135 =item B<-id> <I<id for the group>>
 136
 137 Specifies a negative integer AFS GID number for each group, rather than
 138 allowing the Protection Server to assign it. Precede the integer with a
 139 hyphen (C<->) to indicate that it is negative.
 140
 141 If this argument is used and the B<-name> argument names multiple new
 142 groups, it is best to provide an equivalent number of AFS GIDs. The first
 143 GID is assigned to the first group, the second to the second group, and so
 144 on. If there are fewer GIDs than groups, the Protection Server assigns
 145 GIDs to the unmatched groups based on the C<max group id> counter. If
 146 there are more GIDs than groups, the excess GIDs are ignored. If any of
 147 the GIDs is lower (more negative) than the current value of the C<max
 148 group id> counter, the counter is reset to that value.
 149
 150 =include fragments/pts-common.pod
 151
 152 =back
 153
 154 =head1 EXAMPLES
 155
 156 In the following example, the user pat creates groups called
 157 C<pat:friends> and C<pat:colleagues>.
 158
 159    % pts creategroup -name pat:friends pat:colleagues
 160
 161 The following example shows a member of the system:administrators group
 162 creating the prefix-less group C<staff> and assigning its ownership to the
 163 system:administrators group rather than to herself.
 164
 165    % pts creategroup -name staff -owner system:administrators
 166
 167 In the following example, the user pat creates a group called
 168 C<smith:team-members>, which is allowed because the B<-owner> argument
 169 specifies the required value (C<smith>).
 170
 171    % pts creategroup -name smith:team-members -owner smith
 172
 173 =head1 PRIVILEGE REQUIRED
 174
 175 The issuer must belong to the system:administrators group to create
 176 prefix-less groups or include the B<-id> argument.
 177
 178 To create a regular group, the issuer must
 179
 180 =over 4
 181
 182 =item *
 183
 184 Be authenticated. The command fails if the B<-noauth> flag is provided.
 185
 186 =item *
 187
 188 Have a group-creation quota greater than zero. The B<pts examine> command
 189 displays this quota.
 190
 191 =back
 192
 193 =head1 SEE ALSO
 194
 195 L<pts(1)>,
 196 L<pts_examine(1)>,
 197 L<pts_listmax(1)>,
 198 L<pts_setfields(1)>,
 199 L<pts_setmax(1)>
 200
 201 =head1 COPYRIGHT
 202
 203 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 204
 205 This documentation is covered by the IBM Public License Version 1.0.  It was
 206 converted from HTML to POD by software written by Chas Williams and Russ
 207 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.