path: root/usr/src/man/man8/rolemod.8

'\" te
.\" Copyright (c) 2018 Peter Tribble.
.\"  Copyright 1989 AT&T Copyright (c) 2009, 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 ROLEMOD 8 "Jan 7, 2018"
.SH NAME
rolemod \- modify a role's login information on the system
.SH SYNOPSIS
.LP
.nf
\fBrolemod\fR [\fB-u\fR \fIuid\fR [\fB-o\fR]] [\fB-g\fR \fIgroup\fR] [\fB-G\fR \fIgroup\fR[,\fIgroup\fR]...]
     [\fB-d\fR \fIdir\fR [\fB-m\fR [\fB-z|-Z\fR]]] [\fB-s\fR \fIshell\fR] [\fB-c\fR \fIcomment\fR] [\fB-l\fR \fInew_name\fR]
     [\fB-f\fR \fIinactive\fR] [\fB-e\fR \fIexpire\fR]
     [\fB-A\fR \fIauthorization\fR[,\fIauthorization\fR]...]
     [\fB-P\fR \fIprofile\fR[,\fIprofile\fR]...] [\fB-K\fR \fIkey=value\fR] \fIrole\fR
.fi

.SH DESCRIPTION
.LP
The \fBrolemod\fR utility modifies a role's login information on the system. It
changes the definition of the specified login and makes the appropriate
login-related system file and file system changes.
.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.
.SH OPTIONS
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-A\fR \fIauthorization\fR\fR
.ad
.sp .6
.RS 4n
One or more comma separated authorizations as defined in \fBauth_attr\fR(5).
Only a user or role who has \fBgrant\fR rights to the \fBauthorization\fR can
assign it to an account. This replaces any existing authorization setting. If
an empty authorization list is specified, the existing setting is removed.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR \fIcomment\fR\fR
.ad
.sp .6
.RS 4n
Specify a comment string. \fIcomment\fR can be any text string. It is generally
a short description of the login, and is currently used as the field for the
role's full name. 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
.sp .6
.RS 4n
Specify the new home directory of the role. It defaults to
\fIbase_dir/login\fR, where \fIbase_dir\fR is the base directory for new login
home directories, and \fBlogin\fR is the new login.
.RE

.sp
.ne 2
.na
\fB\fB-e\fR \fIexpire\fR\fR
.ad
.sp .6
.RS 4n
Specify the expiration date for a role. After this date, no role will be able
to access this login. 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
For example, you may enter \fB10/6/90\fR or \fBOctober 6, 1990\fR. A value of
\fB`` ''\fR defeats the status of the expired date.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR \fIinactive\fR\fR
.ad
.sp .6
.RS 4n
Specify the maximum number of days allowed between uses of a login \fBID\fR
before that login \fBID\fR is declared invalid. Normal values are positive
integers. A value of \fB0\fR defeats the status.
.RE

.sp
.ne 2
.na
\fB\fB-g\fR \fIgroup\fR\fR
.ad
.sp .6
.RS 4n
Specify an existing group's integer \fBID\fR or character-string name. It
redefines the role's primary group membership.
.RE

.sp
.ne 2
.na
\fB\fB-G\fR \fIgroup\fR\fR
.ad
.sp .6
.RS 4n
One or more comma-separated existing groups, specified by integer \fBID\fR or
character-string name. It redefines the role's supplementary group membership.
Any duplicate groups between the \fB-g\fR and \fB-G\fR options are ignored.
No more than \fBNGROUPS_UMAX\fR groups may be specified as defined in
\fB<sys/param.h>\fR\&.
.RE

.sp
.ne 2
.na
\fB\fB-K\fR \fIkey=value\fR\fR
.ad
.sp .6
.RS 4n
Replace existing or add to a role's \fIkey=value\fR pair attributes. Multiple
\fB-K\fR options can be used to replace or add multiple \fIkey=value\fR pairs.
However, keys must not be repeated. The generic \fB-K\fR option with the
appropriate key may be used instead of the specific implied key options
(\fB-A\fR and \fB-P\fR). See \fBuser_attr\fR(5) for a list of valid
\fIkey=value\fR pairs.
.sp
The keyword \fBtype\fR can be specified with the value \fBrole\fR or the value
\fBnormal\fR. When using the value \fBnormal\fR, the account changes from a
role user to a normal user; using the value \fBrole\fR keeps the account a role
user.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR \fInew_logname\fR\fR
.ad
.sp .6
.RS 4n
Specify the new login name for the role. The \fInew_logname\fR argument is a
string of no more than eight bytes consisting of characters from the set of
alphabetic characters, numeric characters, period (\fB\&.\fR), underline
(\fB_\fR), and hyphen (\fB\(mi\fR). The first character should be alphabetic and
the field should contain at least one lower case alphabetic character. A
warning message will be written if these restrictions are not met. A future
release may refuse to accept login fields that do not meet these
requirements. The \fInew_logname\fR argument must contain at least one
character and must not contain a colon (\fB:\fR) or \fBNEWLINE\fR (\fB\en\fR).
.RE

.sp
.ne 2
.na
\fB\fB-m\fR\fR [\fB-z|-Z\fR]
.ad
.sp .6
.RS 4n
Move the role's home directory to the new directory specified with the \fB-d\fR
option. If the directory already exists, it must have permissions
read/write/execute by \fIgroup\fR, where \fIgroup\fR is the role's primary
group.
.sp
If the role's old home directory was located on a separate \fBZFS\fR file system
and the \fB/etc/default/useradd\fR file contains the parameter \fBMANAGE_ZFS\fR
set to the value \fBYES\fR, the file system will be destroyed after the home
directory is moved. If the parent directory of the role's new home directory is
located on a separate \fBZFS\fR filesystem and the \fB/etc/default/useradd\fR
file contains the parameter \fBMANAGE_ZFS\fR set to the value \fBYES\fR, a new
\fBZFS\fR file system will be created.
.sp
If the \fB-z\fR option is specified, \fBrolemod\fR will always try to create a
new file system for the home directory and destroy the old one.
.sp
If the \fB-Z\fR option is specified, a new file system will never be created,
and the old one will never be destroyed.
.RE

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

.sp
.ne 2
.na
\fB\fB-P\fR \fIprofile\fR\fR
.ad
.sp .6
.RS 4n
One or more comma-separated execution profiles defined in \fBprof_attr\fR(5).
This replaces any existing profile setting. If an empty profile list is
specified, the existing setting is removed.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIshell\fR\fR
.ad
.sp .6
.RS 4n
Specify the full pathname of the program that is used as the role's shell on
login. The value of \fIshell\fR must be a valid executable file.
.RE

.sp
.ne 2
.na
\fB\fB-u\fR \fIuid\fR\fR
.ad
.sp .6
.RS 4n
Specify a new \fBUID\fR for the role. It must be a non-negative decimal integer
less than \fBMAXUID\fR as defined in \fB<sys/param.h>\fR\&. The \fBUID\fR
associated with the role's home directory is not modified with this option; a
role will not have access to their home directory until the \fBUID\fR is
manually reassigned using \fBchown\fR(1).
.RE

.SH OPERANDS
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fBlogin\fR\fR
.ad
.sp .6
.RS 4n
An existing login name to be modified.
.RE

.SH EXIT STATUS
.LP
In case of an error, \fBrolemod\fR prints an error message and exits with one
of the following values:
.sp
.ne 2
.na
\fB\fB2\fR\fR
.ad
.sp .6
.RS 4n
The command syntax was invalid. A usage message for the \fBrolemod\fR command
is displayed.
.RE

.sp
.ne 2
.na
\fB\fB3\fR\fR
.ad
.sp .6
.RS 4n
An invalid argument was provided to an option.
.RE

.sp
.ne 2
.na
\fB\fB4\fR\fR
.ad
.sp .6
.RS 4n
The \fIuid\fR given with the \fB-u\fR option is already in use.
.RE

.sp
.ne 2
.na
\fB\fB5\fR\fR
.ad
.sp .6
.RS 4n
The password files contain an error. \fBpwconv\fR(8) can be used to correct
possible errors. See \fBpasswd\fR(5).
.RE

.sp
.ne 2
.na
\fB\fB6\fR\fR
.ad
.sp .6
.RS 4n
The login to be modified does not exist, the \fIgroup\fR does not exist, or the
login shell does not exist.
.RE

.sp
.ne 2
.na
\fB\fB8\fR\fR
.ad
.sp .6
.RS 4n
The login to be modified is in use.
.RE

.sp
.ne 2
.na
\fB\fB9\fR\fR
.ad
.sp .6
.RS 4n
The \fInew_logname\fR is already in use.
.RE

.sp
.ne 2
.na
\fB\fB10\fR\fR
.ad
.sp .6
.RS 4n
Cannot update the \fB/etc/group\fR or \fB/etc/user_attr\fR file. Other update
requests will be implemented.
.RE

.sp
.ne 2
.na
\fB\fB11\fR\fR
.ad
.sp .6
.RS 4n
Insufficient space to move the home directory (\fB-m\fR option). Other update
requests will be implemented.
.RE

.sp
.ne 2
.na
\fB\fB12\fR\fR
.ad
.sp .6
.RS 4n
Unable to complete the move of the home directory to the new home directory.
.RE

.SH FILES
.ne 2
.na
\fB\fB/etc/default/useradd\fR\fR
.ad
.sp .6
.RS 4n
configuration file for user and role administrative commands
.RE

.ne 2
.na
\fB\fB/etc/group\fR\fR
.ad
.sp .6
.RS 4n
system file containing group definitions
.RE

.sp
.ne 2
.na
\fB\fB/etc/datemsk\fR\fR
.ad
.sp .6
.RS 4n
system file of date formats
.RE

.sp
.ne 2
.na
\fB\fB/etc/passwd\fR\fR
.ad
.sp .6
.RS 4n
system password file
.RE

.sp
.ne 2
.na
\fB\fB/etc/shadow\fR\fR
.ad
.sp .6
.RS 4n
system file containing users' and roles' encrypted passwords and related
information
.RE

.sp
.ne 2
.na
\fB\fB/etc/user_attr\fR\fR
.ad
.sp .6
.RS 4n
system file containing additional user and role attributes
.RE

.SH ATTRIBUTES
.LP
See \fBattributes\fR(7) 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
.LP
.BR chown (1),
.BR passwd (1),
.BR getdate (3C),
.BR auth_attr (5),
.BR passwd (5),
.BR prof_attr (5),
.BR user_attr (5),
.BR attributes (7),
.BR groupadd (8),
.BR groupdel (8),
.BR groupmod (8),
.BR logins (8),
.BR pwconv (8),
.BR roleadd (8),
.BR roledel (8),
.BR useradd (8),
.BR userdel (8),
.BR usermod (8),
.BR zfs (8)