=head1 NAME

pts creategroup - Creates an (empty) Protection Database group entry

=head1 SYNOPSIS

pts creategroup B<-name> I<group name> [I<group name> ...]
[B<-owner> I<owner of the group>]
[B<-id> I<id (negated) for the group> [I<id (negated) for the group> ...]]
[B<-cell> I<cell name>]
[B<-noauth>]  [B<-force>]  [B<-help>]

pts createg B<-na> I<group name> [I<group name> ...]
[B<-o> I<owner of the group>]
[B<-i> I<id (negated) for the group> [I<id (negated) for the group> ...]]
[B<-c> I<cell name>]
[B<-no>]  [B<-f>]  [B<-h>]

pts cg B<-na> I<group name> [I<group name> ...]
[B<-o> I<owner of the group>]
[B<-i> I<id (negated) for the group> [I<id (negated) for the group> ...]]
[B<-c> I<cell name>]  [B<-no>]  [B<-f>]  [B<-h>]

=head1 DESCRIPTION

The C<pts creategroup> command creates an entry in the Protection
Database for each group specified by the B<-name> argument. The entry
records the issuer of the command as the group's creator, and as the
group's owner unless the B<-owner> argument names an alternate user or
group as the owner.
There are two types of groups:

=over 4

=item *

regular, the names of which have two parts separated by a colon.
The part before the colon names the group's owner. Any user can
create such groups.

=item *

prefix-less, which do not have an owner prefix. Only members of
the system:administrators group can create prefix-less groups.

=back

Creating a group lowers the issuer's group-creation quota by one. This
is true even if the B<-owner> argument is used to assign ownership to an
alternate user or group. To display a user's group-creation quota, use
the pts examine command; to set it, use the pts setfields command.
AFS group ID (AFS GID) numbers are negative integers and by default
the Protection Server assigns a GID that is one less (more negative)
than the current value of the max group id counter in the Protection
Database, decrementing the counter by one for each group. Members of
the system:administrators group can use the B<-id> argument to assign
specific AFS GID numbers. If any of the specified GIDs is lower (more
negative) than the current value of the max group id counter, the
counter is reset to that value. It is acceptable to specify a GID
greater (less negative) than the current value of the counter, but the
creation operation fails if an existing group already has it. To
display or set the value of the max group id counter, use the pts
listmax or pts setmax command, respectively.

=head1 OPTIONS

=over 4

=item B<-name> I<group name> [I<group name> ...]

Specifies the name of each group to create. Provide a string of
up to 63 characters, which can include lowercase (but not
uppercase) letters, numbers, and punctuation marks. A regular
name includes a single colon (:) to separate the two parts of
the name; the colon cannot appear in a prefix-less group name.
A regular group's name must have the following format:
owner_name:group_name and the owner_name field must reflect the
actual owner of the group, as follows:

=over 4

=item *

If the optional  B<-owner> argument is not included, the field
must match the AFS username under which the issuer is
currently authenticated.

=item *

If the B<-owner> argument names an alternate AFS user, the field
must match that AFS username.

=item *

If the B<-owner> argument names another regular group, the field
must match the owning group's owner field (the part of its
name before the colon). If the B<-owner> argument names a
prefix-less group, the field must match the owning group's
complete name.

=back


=item B<-owner> I<owner of the group>

Specifies a user or group as the owner for each group, rather
than the issuer of the command. Provide either an AFS username
or the name of a regular or prefix-less group. An owning group
must already have at least one member. This requirement
prevents assignment of self-ownership to a group during its
creation; use the C<pts chown> command after issuing this command,
if desired.

=item B<-id> I<id (negated) for the group> [I<id (negated) for the group> ...]

Specifies a negative integer AFS GID number for each group,
rather than allowing the Protection Server to assign it.
Precede the integer with a hyphen (-) to indicate that it is
negative. If this argument is used and the B<-name> argument names multiple
new groups, it is best to provide an equivalent number of AFS
GIDs. The first GID is assigned to the first group, the second
to the second group, and so on. If there are fewer GIDs than
groups, the Protection Server assigns GIDs to the unmatched
groups based on the max group id counter. If there are more
GIDs than groups, the excess GIDs are ignored. If any of the
GIDs is lower (more negative) than the current value of the max
group id counter, the counter is reset to that value.

=item B<-cell> I<cell name>

Names the cell in which to run the command. For more details,
see the introductory L<pts(1)> reference page.

=item B<-noauth>

Assigns the unprivileged identity anonymous to the issuer. For
more details, see the introductory L<pts(1)> reference page.

=item B<-force>

Enables the command to continue executing as far as possible
when errors or other problems occur, rather than halting
execution at the first error.

=item B<-help>

Prints the online help for this command. All other valid
options are ignored.

==back

=head1 OUTPUT

The command generates the following string to confirm creation of each
group:
group name has id AFS GID

=head1 EXAMPLES

In the following example, the user pat creates groups called
pat:friends and pat:colleagues.

    pts creategroup -name pat:friends pat:colleagues

The following example shows a member of the system:administrators
group creating the prefix-less group staff and assigning its ownership
to the system:administrators group rather than to herself.

    pts creategroup -name staff -owner system:administrators

In the following example, the user pat creates a group called
smith:team-members, which is allowed because the -owner argument
specifies the required value (smith).

    pts creategroup -name smith:team-members -owner smith

=head1 PRIVILEGE REQUIRED

The issuer must belong to the system:administrators group to create
prefix-less groups or include the B<-id> argument.
To create a regular group, the issuer must

=over

=item *

Be authenticated. The command fails if the B<-noauth> flag is
provided.

=item *

Have a group-creation quota greater than zero. The C<pts examine>
command displays this quota.

=back

=head1 CAVEATS

Although using the -owner argument to designate a machine entry as a
group's owner does not generate an error, it is not recommended. The
Protection Server does not extend the usual privileges of group
ownership to users logged onto the machine.

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.

=head1 SEE ALSO

L<pts(1)>,
L<pts_examine(1)>,
L<pts_listmax(1)>,
L<pts_setfields(1)>,
L<pts_setmax(1)>

=cut
