'\" te
.\"  Copyright 1989 AT&T Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH ROLEADD 1M "Feb 21, 2006"
.SH NAME
roleadd \- administer a new role account on the system
.SH SYNOPSIS
.LP
.nf
\fBroleadd\fR [\fB-c\fR \fIcomment\fR] [\fB-d\fR \fIdir\fR] [\fB-e\fR \fIexpire\fR] [\fB-f\fR \fIinactive\fR]
     [\fB-g\fR \fIgroup\fR] [\fB-G\fR \fIgroup\fR [, \fIgroup\fR...]] [\fB-m\fR [\fB-k\fR \fIskel_dir\fR]]
     [\fB-u\fR \fIuid\fR [\fB-o\fR]] [\fB-s\fR \fIshell\fR]
     [\fB-A\fR \fIauthorization\fR [,\fIauthorization...\fR]] [\fB-K\fR \fIkey=value\fR] \fIrole\fR
.fi

.LP
.nf
\fBroleadd\fR \fB-D\fR [\fB-b\fR \fIbase_dir\fR] [\fB-e\fR \fIexpire\fR] [\fB-f\fR \fIinactive\fR]
     [\fB-g\fR \fIgroup\fR] [\fB-A\fR \fIauthorization\fR [,\fIauthorization...\fR]]
     [\fB-P\fR \fIprofile\fR [,\fIprofile...\fR] [\fB-K\fR \fIkey=value\fR]]
.fi

.SH DESCRIPTION
.sp
.LP
\fBroleadd\fR adds a role entry to the \fB/etc/passwd\fR and \fB/etc/shadow\fR
and \fB/etc/user_attr\fR files. The \fB-A\fR and \fB-P\fR options respectively
assign authorizations and profiles to the role. Roles cannot be assigned to
other roles. The \fB-K\fR option adds a \fIkey=value\fR pair to
\fB/etc/user_attr\fR for a role. Multiple \fIkey=value\fR pairs can be added
with multiple \fB-K\fR options.
.sp
.LP
\fBroleadd\fR also creates supplementary group memberships for the role
(\fB-G\fR option) and creates the home directory (\fB-m\fR option) for the role
if requested. The new role account remains locked until the \fBpasswd\fR(1)
command is executed.
.sp
.LP
Specifying \fBroleadd\fR \fB-D\fR with the \fB-g\fR, \fB-b\fR, \fB-f\fR,
\fB-e\fR, or \fB-K\fR option (or any combination of these option) sets the
default values for the respective fields. See the \fB-D\fR option. Subsequent
\fBroleadd\fR commands without the \fB-D\fR option use these arguments.
.sp
.LP
The system file entries created with this command have a limit of 512
characters per line. Specifying long arguments to several options can exceed
this limit.
.sp
.LP
The role (\fBrole\fR) field accepts a string of no more than eight bytes
consisting of characters from the set of alphabetic characters, numeric
characters, period (\fB\&.\fR), underscore (\fB_\fR), and hyphen (\fB-\fR). The
first character should be alphabetic and the field should contain at least one
lower case alphabetic character. A warning message is written if these
restrictions are not met. A future Solaris release might refuse to accept role
fields that do not meet these requirements.
.sp
.LP
The \fBrole\fR field must contain at least one character and must not contain a
colon (\fB:\fR) or a newline (\fB\en\fR).
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-A\fR \fIauthorization\fR\fR
.ad
.RS 20n
One or more comma separated authorizations defined in \fBauth_attr\fR(4). Only
a user or role who has grant rights to the authorization can assign it to an
account
.RE

.sp
.ne 2
.na
\fB\fB-b\fR \fIbase_dir\fR\fR
.ad
.RS 20n
The default base directory for the system if \fB-d\fR\fI dir\fR is not
specified. \fIbase_dir\fR is concatenated with the account name to define the
home directory. If the \fB-m\fR option is not used, \fIbase_dir\fR must exist.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR \fIcomment\fR\fR
.ad
.RS 20n
Any text string. It is generally a short description of the role. This
information is stored in the role's \fB/etc/passwd\fR entry.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR \fIdir\fR\fR
.ad
.RS 20n
The home directory of the new role. It defaults to
\fIbase_dir\fR/\fIaccount_name\fR, where \fIbase_dir\fR is the base directory
for new login home directories and \fIaccount_name\fR is the new role name.
.RE

.sp
.ne 2
.na
\fB\fB-D\fR\fR
.ad
.RS 20n
Display the default values for \fIgroup\fR, \fIbase_dir\fR, \fIskel_dir\fR,
\fIshell\fR, \fIinactive\fR, \fIexpire\fR and \fIkey=value\fR pairs. When used
with the \fB-g\fR, \fB-b\fR, \fB-f\fR, or \fB-K\fR, options, the \fB-D\fR
option sets the default values for the specified fields. The default values
are:
.sp
.ne 2
.na
\fBgroup\fR
.ad
.sp .6
.RS 4n
\fBother\fR (\fBGID\fR of 1)
.RE

.sp
.ne 2
.na
\fBbase_dir\fR
.ad
.sp .6
.RS 4n
\fB/home\fR
.RE

.sp
.ne 2
.na
\fBskel_dir\fR
.ad
.sp .6
.RS 4n
\fB/etc/skel\fR
.RE

.sp
.ne 2
.na
\fBshell\fR
.ad
.sp .6
.RS 4n
\fB/bin/pfsh\fR
.RE

.sp
.ne 2
.na
\fBinactive\fR
.ad
.sp .6
.RS 4n
\fB0\fR
.RE

.sp
.ne 2
.na
\fBexpire\fR
.ad
.sp .6
.RS 4n
Null
.RE

.sp
.ne 2
.na
\fBauths\fR
.ad
.sp .6
.RS 4n
Null
.RE

.sp
.ne 2
.na
\fBprofiles\fR
.ad
.sp .6
.RS 4n
Null
.RE

.sp
.ne 2
.na
\fBkey=value (pairs defined in \fBuser_attr\fR(4)\fR
.ad
.sp .6
.RS 4n
not present
.RE

.RE

.sp
.ne 2
.na
\fB\fB-e\fR \fIexpire\fR\fR
.ad
.RS 20n
Specify the expiration date for a role. After this date, no user is able to
access this role. The expire option argument is a date entered using one of the
date formats included in the template file \fB/etc/datemsk\fR. See
\fBgetdate\fR(3C).
.sp
If the date format that you choose includes spaces, it must be quoted. For
example, you can enter \fB10/6/90\fR or \fBOctober 6, 1990\fR. A null value
(\fB" "\fR) defeats the status of the expired date. This option is useful for
creating temporary roles.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR \fIinactive\fR\fR
.ad
.RS 20n
The maximum number of days allowed between uses of a role ID before that ID is
declared invalid. Normal values are positive integers. A value of \fB 0\fR
defeats the status.
.RE

.sp
.ne 2
.na
\fB\fB-g\fR \fIgroup\fR\fR
.ad
.RS 20n
An existing group's integer ID or character-string name. Without the \fB-D\fR
option, it defines the new role's primary group membership and defaults to the
default group. You can reset this default value by invoking \fBroleadd
\fR\fB-D\fR\fB \fR\fB-g\fR\fB \fR\fIgroup.\fR
.RE

.sp
.ne 2
.na
\fB\fB-G\fR \fIgroup\fR\fR
.ad
.RS 20n
An existing group's integer \fBID\fR or character-string name. It defines the
new role's supplementary group membership. Duplicates between \fIgroup\fR with
the \fB-g\fR and \fB-G\fR options are ignored. No more than \fBNGROUPS_MAX\fR
groups can be specified.
.RE

.sp
.ne 2
.na
\fB\fB-k\fR \fIskel_dir\fR\fR
.ad
.RS 20n
A directory that contains skeleton information (such as \fB\&.profile\fR) that
can be copied into a new role's home directory. This directory must already
exist. The system provides the \fB/etc/skel\fR directory that can be used for
this purpose.
.RE

.sp
.ne 2
.na
\fB\fB-K\fR \fIkey=value\fR\fR
.ad
.RS 20n
A \fIkey=value\fR pair to add to the role's attributes. Multiple \fB-K\fR
options can be used to add multiple \fIkey=value\fR pairs. The generic \fB-K\fR
option with the appropriate key can be used instead of the specific implied key
options (\fB-A\fR and \fB-P\fR). See \fBuser_attr\fR(4) for a list of valid
\fIkey=value\fR pairs. The "type" key is not a valid key for this option. Keys
can not be repeated.
.RE

.sp
.ne 2
.na
\fB\fB-m\fR\fR
.ad
.RS 20n
Create the new role's home directory if it does not already exist. If the
directory already exists, it must have read, write, and execute permissions by
\fIgroup\fR, where \fIgroup\fR is the role's primary group.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR\fR
.ad
.RS 20n
This option allows a \fBUID\fR to be duplicated (non-unique).
.RE

.sp
.ne 2
.na
\fB\fB-P\fR \fIprofile\fR\fR
.ad
.RS 20n
One or more comma-separated execution profiles defined in \fBprof_attr\fR(4).
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIshell\fR\fR
.ad
.RS 20n
Full pathname of the program used as the user's shell on login. It defaults to
an empty field causing the system to use \fB/bin/pfsh\fR as the default. The
value of \fIshell\fR must be a valid executable file.
.RE

.sp
.ne 2
.na
\fB\fB-u\fR \fIuid\fR\fR
.ad
.RS 20n
The \fBUID\fR of the new role. This \fBUID\fR must be a non-negative decimal
integer below \fBMAXUID\fR as defined in \fB<sys/param.h>\fR\&. The \fBUID\fR
defaults to the next available (unique) number above the highest number
currently assigned. For example, if \fBUID\fRs 100, 105, and 200 are assigned,
the next default \fBUID\fR number is 201. (\fBUID\fRs from \fB0\fR-\fB99\fR are
reserved for possible use in future applications.)
.RE

.SH FILES
.sp
.LP
\fB/etc/datemsk\fR
.sp
.LP
\fB/etc/passwd\fR
.sp
.LP
\fB/etc/shadow\fR
.sp
.LP
\fB/etc/group\fR
.sp
.LP
\fB/etc/skel\fR
.sp
.LP
\fB/usr/include/limits.h\fR
.sp
.LP
\fB/etc/user_attr\fR
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Evolving
.TE

.SH SEE ALSO
.sp
.LP
\fBpasswd\fR(1), \fBpfsh\fR(1), \fBprofiles\fR(1), \fBroles\fR(1),
\fBusers\fR(1B), \fBgroupadd\fR(1M), \fBgroupdel\fR(1M), \fBgroupmod\fR(1M),
\fBgrpck\fR(1M), \fBlogins\fR(1M), \fBpwck\fR(1M), \fBuserdel\fR(1M),
\fBusermod\fR(1M), \fBgetdate\fR(3C), \fBauth_attr\fR(4), \fBpasswd\fR(4),
\fBprof_attr\fR(4), \fBuser_attr\fR(4), \fBattributes\fR(5)
.SH DIAGNOSTICS
.sp
.LP
In case of an error, \fBroleadd\fR prints an error message and exits with a
non-zero status.
.sp
.LP
The following indicates that \fBlogin\fR specified is already in use:
.sp
.in +2
.nf
UX: roleadd: ERROR: login is already in use. Choose another.
.fi
.in -2
.sp

.sp
.LP
The following indicates that the \fIuid\fR specified with the \fB-u\fR option
is not unique:
.sp
.in +2
.nf
UX: roleadd: ERROR: uid \fIuid\fR is already in use. Choose another.
.fi
.in -2
.sp

.sp
.LP
The following indicates that the \fIgroup\fR specified with the \fB-g\fR option
is already in use:
.sp
.in +2
.nf
UX: roleadd: ERROR: group \fIgroup\fR does not exist. Choose another.
.fi
.in -2
.sp

.sp
.LP
The following indicates that the \fIuid\fR specified with the \fB-u\fR option
is in the range of reserved \fBUID\fRs (from \fB0\fR-\fB99\fR):
.sp
.in +2
.nf
UX: roleadd: WARNING: uid \fIuid\fR is reserved.
.fi
.in -2
.sp

.sp
.LP
The following indicates that the \fIuid\fR specified with the \fB-u\fR option
exceeds \fBMAXUID\fR as defined in \fB<sys/param.h>\fR:
.sp
.in +2
.nf
UX: roleadd: ERROR: uid \fIuid\fR is too big. Choose another.
.fi
.in -2
.sp

.sp
.LP
The following indicates that the \fB/etc/passwd\fR or \fB/etc/shadow\fR files
do not exist:
.sp
.in +2
.nf
UX: roleadd: ERROR: Cannot update system files - login cannot be created.
.fi
.in -2
.sp

.SH NOTES
.sp
.LP
If a network nameservice such as \fBNIS\fR or \fBNIS+\fR is being used to
supplement the local \fB/etc/passwd\fR file with additional entries,
\fBroleadd\fR cannot change information supplied by the network nameservice.