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