Import Upstream version 1.8.5

[hcoop/debian/openafs.git] / doc / man-pages / pod1 / pts_creategroup.pod.in

=head1 NAME

pts_creategroup - Creates an (empty) Protection Database group entry

=head1 SYNOPSIS

=for html
<div class="synopsis">

B<pts creategroup> S<<< B<-name> <I<group name>>+ >>>
    S<<< [B<-owner> <I<owner of the group>>] >>>
    S<<< [B<-id> <I<id (negated) for the group>>+] >>> S<<< [B<-cell> <I<cell name>>] >>>
    [B<-noauth>] [B<-localauth>] [B<-force>] [B<-help>]
    [B<-auth>] [B<-encrypt>] S<<< [B<-config> <I<config directory>>] >>>

B<pts createg> S<<< B<-na> <I<group name>>+ >>>  S<<< [B<-o> <I<owner of the group>>] >>>
    S<<< [B<-i> <I<id (negated) for the group>>+] >>> S<<< [B<-c> <I<cell name>>] >>>
    [B<-no>] [B<-l>] [B<-f>] [B<-h>]
    [B<-a>] [B<-e>] S<<< [B<-co> <I<config directory>>] >>>

B<pts cg> S<<< B<-na> <I<group name>>+ >>> S<<< [B<-o> <I<owner of the group>>] >>>
    S<<< [B<-i> <I<id (negated) for the group>>+] >>> S<<< [B<-c> <I<cell name>>] >>>
    [B<-no>] [B<-l>] [B<-f>] [B<-h>]
    [B<-a>] [B<-e>] S<<< [B<-co> <I<config directory>>] >>>

=for html
</div>

=head1 DESCRIPTION

The B<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 *

I<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 *

I<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
B<pts examine> command; to set it, use the B<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 C<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 C<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 C<max group id> counter, use the B<pts listmax> or B<pts
setmax> command, respectively.

=head1 OUTPUT

The command generates the following string to confirm creation of each
group:

   group <name> has id <AFS GID>

=head1 CAUTIONS

Although using the B<-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 OPTIONS

=over 4

=item B<-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
(C<:>) 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 B<pts chown> command after issuing this
command, if desired.

=item B<-id> <I<id 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 (C<->) 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 C<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 C<max
group id> counter, the counter is reset to that value.

=include fragments/pts-common.pod

=back

=head1 EXAMPLES

In the following example, the user pat creates groups called
C<pat:friends> and C<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 C<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
C<smith:team-members>, which is allowed because the B<-owner> argument
specifies the required value (C<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 4

=item *

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

=item *

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

=back

=head1 SEE ALSO

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

=head1 COPYRIGHT

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

This documentation is covered by the IBM Public License Version 1.0.  It was
converted from HTML to POD by software written by Chas Williams and Russ
Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.