1 USERMOD(1M)                  Maintenance Commands                  USERMOD(1M)
   2 
   3 
   4 
   5 NAME
   6        usermod - modify a user's login information on the system
   7 
   8 SYNOPSIS
   9        usermod [-u uid [-o]] [-g group] [-G group [, group...]]
  10             [-d dir [-m [-z|-Z]]] [-s shell] [-c comment] [-l new_name]
  11             [-f inactive] [-e expire]
  12             [-A authorization [, authorization]]
  13             [-P profile [, profile]] [-R role [, role]]
  14             [-K key=value] login
  15 
  16 
  17 DESCRIPTION
  18        The usermod utility modifies a user's login definition on the system.
  19        It changes the definition of the specified login and makes the
  20        appropriate login-related system file and file system changes.
  21 
  22 
  23        The system file entries created with this command have a limit of 512
  24        characters per line. Specifying long arguments to several options might
  25        exceed this limit.
  26 
  27 OPTIONS
  28        The following options are supported:
  29 
  30        -A authorization
  31            One or more comma separated authorizations as defined in
  32            auth_attr(4).  Only a user or role who has grant rights to the
  33            authorization can assign it to an account. This replaces any
  34            existing authorization setting. If no authorization list is
  35            specified, the existing setting is removed.
  36 
  37 
  38        -c comment
  39            Specify a comment string. comment can be any text string. It is
  40            generally a short description of the login, and is currently used
  41            as the field for the user's full name. This information is stored
  42            in the user's /etc/passwd entry.
  43 
  44 
  45        -d dir
  46            Specify the new home directory of the user. It defaults to
  47            base_dir/login, where base_dir is the base directory for new login
  48            home directories, and login is the new login.
  49 
  50 
  51        -e expire
  52            Specify the expiration date for a login. After this date, no user
  53            will be able to access this login. The expire option argument is a
  54            date entered using one of the date formats included in the template
  55            file /etc/datemsk. See getdate(3C).
  56 
  57            For example, you may enter 10/6/90 or October 6, 1990. A value of
  58            `` '' defeats the status of the expired date.
  59 
  60 
  61        -f inactive
  62            Specify the maximum number of days allowed between uses of a login
  63            ID before that login ID is declared invalid. Normal values are
  64            positive integers. A value of 0 defeats the status.
  65 
  66 
  67        -g group
  68            Specify an existing group's integer ID or character-string name. It
  69            redefines the user's primary group membership.
  70 
  71 
  72        -G group
  73            Specify an existing group's integer "ID" "," or character string
  74            name. It redefines the user's supplementary group membership.
  75            Duplicates between group with the -g and -G options are ignored. No
  76            more than NGROUPS_UMAX groups may be specified as defined in
  77            <param.h>.
  78 
  79 
  80        -K key=value
  81            Replace existing or add to a user's key=value pair attributes.
  82            Multiple -K options can be used to replace or add multiple
  83            key=value pairs.  However, keys must not be repeated. The generic
  84            -K option with the appropriate key can be used instead of the
  85            specific implied key options (-A, -P, -R, -p). See user_attr(4) for
  86            a list of valid keys. Values for these keys are usually found in
  87            man pages or other sources related to those keys. For example, see
  88            project(4) for guidance on values for the project key. Use the
  89            command ppriv(1) with the -v and -l options for a list of values
  90            for the keys defaultpriv and limitpriv.
  91 
  92            The keyword type can be specified with the value role or the value
  93            normal.  When using the value role, the account changes from a
  94            normal user to a role; using the value normal keeps the account a
  95            normal user.
  96 
  97            As a role account, no roles (-R or roles=value) can be present.
  98 
  99 
 100        -l new_logname
 101            Specify the new login name for the user. See passwd(4) for the
 102            requirements for usernames.
 103 
 104 
 105        -m [-z|-Z]
 106            Move the user's home directory to the new directory specified with
 107            the -d option. If the directory already exists, it must have
 108            permissions read/write/execute by group, where group is the user's
 109            primary group.  CHANGE_ZFS_FS option in /etc/default/useradd file
 110            determines if ZFS filesystem will be created or destroyed during
 111            this action. If this option is set to yes and parent directory of
 112            user's home directory is ZFS filesystem mount point, a new ZFS
 113            filesystem is created. If old user's home directory is a ZFS file
 114            system and CHANGE_ZFS_FS is set to yes, the filesystem will be
 115            destroyed.  -z and -Z options allow overwrite default behavior. If
 116            -z option is specified, usermod tries to create new file system and
 117            destroy the old one. If -Z option is specified, new filesystem is
 118            not created and the old one is not destroyed.
 119 
 120 
 121        -o
 122            This option allows the specified UID to be duplicated (non-unique).
 123 
 124 
 125        -P profile
 126            One or more comma-separated rights profiles defined in
 127            prof_attr(4). This replaces any existing profile setting in
 128            user_attr(4). If an empty profile list is specified, the existing
 129            setting is removed.
 130 
 131 
 132        -R role
 133            One or more comma-separated roles (see roleadd(1M)). This replaces
 134            any existing role setting. If no role list is specified, the
 135            existing setting is removed.
 136 
 137 
 138        -s shell
 139            Specify the full pathname of the program that is used as the user's
 140            shell on login. The value of shell must be a valid executable file.
 141 
 142 
 143        -u uid
 144            Specify a new UID for the user. It must be a non-negative decimal
 145            integer less than MAXUID as defined in <param.h>. The UID
 146            associated with the user's home directory is not modified with this
 147            option; a user will not have access to their home directory until
 148            the UID is manually reassigned using chown(1).
 149 
 150 
 151 OPERANDS
 152        The following operands are supported:
 153 
 154        login
 155            An existing login name to be modified.
 156 
 157 
 158 EXAMPLES
 159        Example 1 Assigning Privileges to a User
 160 
 161 
 162        The following command adds the privilege that affects high resolution
 163        times to a user's initial, inheritable set of privileges.
 164 
 165 
 166          # usermod -K defaultpriv=basic,proc_clock_highres jdoe
 167 
 168 
 169 
 170 
 171        This command results in the following entry in user_attr:
 172 
 173 
 174          jdoe::::type=normal;defaultpriv=basic,proc_clock_highres
 175 
 176 
 177        Example 2 Removing a Privilege from a User's Limit Set
 178 
 179 
 180        The following command removes the privilege that allows the specified
 181        user to create hard links to directories and to unlink directories.
 182 
 183 
 184          # usermod -K limitpriv=all,!sys_linkdir jdoe
 185 
 186 
 187 
 188 
 189        This command results in the following entry in user_attr:
 190 
 191 
 192          jdoe::::type=normal;defaultpriv=basic,limitpriv=all,!sys_linkdir
 193 
 194 
 195        Example 3 Removing a Privilege from a User's Basic Set
 196 
 197 
 198        The following command removes the privilege that allows the specified
 199        user to examine processes outside the user's session.
 200 
 201 
 202          # usermod -K defaultpriv=basic,!proc_session jdoe
 203 
 204 
 205 
 206 
 207        This command results in the following entry in user_attr:
 208 
 209 
 210          jdoe::::type=normal;defaultpriv=basic,!proc_session;limitpriv=all
 211 
 212 
 213        Example 4 Assigning a Role to a User
 214 
 215 
 216        The following command assigns a role to a user. The role must have been
 217        created prior to this command, either through use of the Solaris
 218        Management Console GUI or through roleadd(1M).
 219 
 220 
 221          # usermod -R mailadm jdoe
 222 
 223 
 224 
 225 
 226        This command results in the following entry in user_attr:
 227 
 228 
 229          jdoe::::type=normal;roles=mailadm;defaultpriv=basic;limitpriv=all
 230 
 231 
 232        Example 5 Removing All Profiles from a User
 233 
 234 
 235        The following command removes all profiles that were granted to a user
 236        directly. The user will still have any rights profiles that are granted
 237        by means of the PROFS_GRANTED key in policy.conf(4).
 238 
 239 
 240          # usermod -P "" jdoe
 241 
 242 
 243 
 244 EXIT STATUS
 245        In case of an error, usermod prints an error message and exits with one
 246        of the following values:
 247 
 248        2
 249            The command syntax was invalid. A usage message for the usermod
 250            command is displayed.
 251 
 252 
 253        3
 254            An invalid argument was provided to an option.
 255 
 256 
 257        4
 258            The uid given with the -u option is already in use.
 259 
 260 
 261        5
 262            The password files contain an error. pwconv(1M) can be used to
 263            correct possible errors. See passwd(4).
 264 
 265 
 266        6
 267            The login to be modified does not exist, the group does not exist,
 268            or the login shell does not exist.
 269 
 270 
 271        8
 272            The login to be modified is in use.
 273 
 274 
 275        9
 276            The new_logname is already in use.
 277 
 278 
 279        10
 280            Cannot update the /etc/group or /etc/user_attr file. Other update
 281            requests will be implemented.
 282 
 283 
 284        11
 285            Insufficient space to move the home directory (-m option). Other
 286            update requests will be implemented.
 287 
 288 
 289        12
 290            Unable to complete the move of the home directory to the new home
 291            directory.
 292 
 293 
 294 FILES
 295        /etc/default/useradd
 296            useradd, usermod and userdel configuration file
 297 
 298 
 299        /etc/group
 300            system file containing group definitions
 301 
 302 
 303        /etc/datemsk
 304            system file of date formats
 305 
 306 
 307        /etc/passwd
 308            system password file
 309 
 310 
 311        /etc/shadow
 312            system file containing users' encrypted passwords and related
 313            information
 314 
 315 
 316        /etc/user_attr
 317            system file containing additional user and role attributes
 318 
 319 
 320 ATTRIBUTES
 321        See attributes(5) for descriptions of the following attributes:
 322 
 323 
 324 
 325 
 326        +--------------------+-----------------+
 327        |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
 328        +--------------------+-----------------+
 329        |Interface Stability | Committed       |
 330        +--------------------+-----------------+
 331 
 332 SEE ALSO
 333        chown(1), passwd(1), users(1B), groupadd(1M), groupdel(1M),
 334        groupmod(1M), logins(1M), pwconv(1M), roleadd(1M), roledel(1M),
 335        rolemod(1M), useradd(1M), userdel(1M), getdate(3C), auth_attr(4),
 336        passwd(4), policy.conf(4), prof_attr(4), user_attr(4), attributes(5)
 337 
 338 NOTES
 339        The usermod utility modifies passwd definitions only in the local
 340        /etc/passwd and /etc/shadow files. If a network nameservice such as NIS
 341        or NIS+ is being used to supplement the local files with additional
 342        entries, usermod cannot change information supplied by the network
 343        nameservice. However usermod will verify the uniqueness of user name
 344        and user ID against the external nameservice.
 345 
 346 
 347        The usermod utility uses the /etc/datemsk file, available with
 348        SUNWaccr, for date formatting.
 349 
 350 
 351 
 352                                February 22, 2008                   USERMOD(1M)