usermod(1M)															       usermod(1M)

NAME

       usermod - modify a user login on the system

SYNOPSIS

       uid group] groupgroup]...] dir shell] comment] inactive] new_logname] expire] encrypted_password] alternate_password_file] login

DESCRIPTION

       The command modifies a user login on the system by changing the appropriate login related files.

       The  command  requires  the  login argument.  login is the login name, specified as a string of printable characters.  It may not contain a
       colon or a newline

       Refer to usergroupname(5) to understand the functionality changes with the Numeric User Group Name feature.

   New Behavior
       If the primary group of a user is modified, then the user name is not added to the primary group entry in  file.   However,  if	option	is
       specified the user is added to the corresponding supplemental group.

   Options
       The command supports the following options:

	      Specify the	UID for the user.  uid must be a non-negative decimal integer less than as it is defined in the header file.

	      Allow the 	UID to be non-unique (that is, a duplicate).

	      Specify the integer group
				ID or character string name of an existing group.  This redefines the primary group membership of the login.

	      Specify the integer group
				ID or character string name of an existing group.  This redefines the supplemental group memberships of the login.
				Duplicates within group with the and options are ignored.

	      Specify the new home directory of the login.
				It defaults to base_dir/login, where login is the login and base_dir is the base  directory  for  new  login  home
				directories.

	      Move the user's home directory to the directory specified with the
				option.   The  operation  cannot  be performed if the user's home directory is the root directory or if the user's
				home directory is specified in the configuration file.	See usermod(4).  If the home directory exists, the  direc-
				tory  must  have read and execute permission by group, where group is the primary group of the login.  This condi-
				tion can be overridden using the option.

	      Inherit an existing home directory, regardless of its current access
				permissions. Typically use this option to inherit orphaned directories, that is, directories that are not owned by
				any  active  user  of  the  system.  Note that using the option will impact shared home directories; hence use the
				option with caution.  The permissions will be same as that of newly created home directory.

	      Specify the full pathname of the login shell.
				The value of shell must be a valid executable file.

	      Specify the comment field present in the
				entry of this login.  This can be any text string.  A short description of the login is suggested for this field.

	      Specify the maximum number of days of continuous
				inactivity of the login before the account is locked. For the valid values of inactive	refer  to  description	of
				inactivity field in shadow(4).

	      Specify the new login name for the user.
				It consists of a string of printable characters that does not contain a colon or a newline

	      Specify the date on which this login can no longer be used.
				After  the expire date occurs, no user will be able to access this login.  This option is used to create temporary
				logins.  expire, which is a date, may be typed in any desired format, except a Julian date.  For example,  a  date
				may be entered as either of the following:

				A value of (two single quotes) or (two double quotes) results in no expiration date.

	      Specify the encrypted password for the user.
				Before using the option, obtain the encrypted password by using or (see crypt(3C) or crypt2(3C)).

	      Force the changes, even if the login is currently in use.

	      Indicate that modifications are to be made to the alternate
				password file of NIS specified by the option.  The following options edit the password file and should not be used
				with the option:

	      Specify the path of the alternate password file of NIS.
				The option is used with the option.

       The and options are supported only if are in use. For details refer to pwconv(1M).

       In the event where a directory is shared by users of the same group and the owner of that directory is modified, then the ownership of that
       directory  is  propagated to the next user who is sharing that directory.  The new owner is determined by looking at the order in which the
       users sharing this directory are added to the file.  If there is only one user remaining then the directory is  brought	back  to  unshared
       mode by resetting the permissions to from

       If a directory is shared by users, then one cannot change the primary group of any of these users unless the home directory of that user is
       also changed.

   NIS
       The command is aware of NIS user and group entries.  Only local users and groups may be modified with this command.  Attempts to modify	an
       NIS user or group will result in an error.  NIS users and groups must be administered from the NIS server.  NIS users are checked when ver-
       ifying the uniqueness of the new UID or new user name, which may result in the following error messages:

       (return value 6) if the user specified is an NIS user (see passwd(4)).  Also, the error

       (return value 10) is returned if an NIS group is specified with either the option or the option (see group(4)).

   NFS
       Errors may occur with the option if either the source or the target directory is within an NFS mounted file system that does not allow root
       privileges across the NFS mount, and the directory or files within the directory do not have sufficient permissions.

RETURN VALUE

       exits with one of the following values:

	      Successful completion.

	      Invalid command syntax.

	      Invalid argument supplied to an option.

	      uid  is not unique (when is not used).

	      The  login to be modified or the group specified with the option does not exist.

	      The  login to be modified is in use.

	      new_logname
		   is not unique.

	      Cannot modify the
		   file.  The other parts of the update request will be performed.

	      There is insufficient space to move the home directory (with the
		   option).  The other parts of the update request will be performed.

	      Unable to complete the move of the home directory to the
		   new home directory.

	      Unable to open
		   file, or file is non-existent.

	      file or
		   file busy. Another command may be modifying the file.

	      Cannot modify the entry in the
		   file.

	      Out of memory.

	      Invalid template file.

	      Exceeding permissible limit of maximum members in a group.
		   The file is not modified.

EXAMPLES

       Change primary group to

       Change user ID to and change the login name to

WARNINGS

       A directory can be shared between the users belonging to the same group.  If the home directory is in unshared mode and a new user is allo-
       cated to that directory, then it will be put into shared mode by setting the permissions of that directory to (includes the  write  permis-
       sions  to  the group as well).  Also, the directory which will be shared should have and permissions for the group.  Otherwise, will report
       an error.

       Because many users may try to write the file simultaneously, a password locking mechanism was devised.	If  this  password  locking  fails
       after subsequent retrying, terminates.

       While  modifying  the  user login, the username is not added to the primary group entry in the file.  If a supplemental group is specified,
       the user is added to the supplemental group.  If the size of a group entry in file exceeds limit, a new entry of the same group is  created
       and a warning message is issued.  See limits(5) for the value of

FILES

       Shadow password file
       System password file
       System group file
       Lock file used when updating password file

SEE ALSO

       passwd(1),  users(1),  groupadd(1M),  groupdel(1M),  groupmod(1M), logins(1M), pwconv(1M), useradd(1M), userdel(1M), crypt(3C), crypt2(3C),
       group(4), shadow(4), usermod(4), limits(5), usergroupname(5).

STANDARDS CONFORMANCE

																       usermod(1M)