doc/man-pages/pod1/pts_creategroup.pod

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