1USERMOD(8)                System Management Commands                USERMOD(8)
2
3
4

NAME

6       usermod - modify a user account
7

SYNOPSIS

9       usermod [options] LOGIN
10

DESCRIPTION

12       The usermod command modifies the system account files.
13

OPTIONS

15       The options which apply to the usermod command are:
16
17       -a, --append
18           Add the user to the supplementary group(s). Use only with the -G
19           option.
20
21       -b, --badname
22           Allow names that do not conform to standards.
23
24       -c, --comment COMMENT
25           update the comment field of the user in /etc/passwd, which is
26           normally modified using the chfn(1) utility.
27
28       -d, --home HOME_DIR
29           The user's new login directory.
30
31           If the -m option is given, the contents of the current home
32           directory will be moved to the new home directory, which is created
33           if it does not already exist. If the current home directory does
34           not exist the new home directory will not be created.
35
36       -e, --expiredate EXPIRE_DATE
37           The date on which the user account will be disabled. The date is
38           specified in the format YYYY-MM-DD. Integers as input are
39           interpreted as days after 1970-01-01.
40
41           An input of -1 or an empty string will blank the account expiration
42           field in the shadow password file. The account will remain
43           available with no date limit.
44
45           This option requires a /etc/shadow file. A /etc/shadow entry will
46           be created if there were none.
47
48       -f, --inactive INACTIVE
49           defines the number of days after the password exceeded its maximum
50           age during which the user may still login by immediately replacing
51           the password. This grace period before the account becomes inactive
52           is stored in the shadow password file. An input of 0 will disable
53           an expired password with no delay. An input of -1 will blank the
54           respective field in the shadow password file. See shadow(5) for
55           more information.
56
57           This option requires a /etc/shadow file. A /etc/shadow entry will
58           be created if there were none.
59
60       -g, --gid GROUP
61           The name or numerical ID of the user's new primary group. The group
62           must exist.
63
64           Any file from the user's home directory owned by the previous
65           primary group of the user will be owned by this new group.
66
67           The group ownership of files outside of the user's home directory
68           must be fixed manually.
69
70           The change of the group ownership of files inside of the user's
71           home directory is also not done if the home dir owner uid is
72           different from the current or new user id. This is a safety measure
73           for special home directories such as /.
74
75       -G, --groups GROUP1[,GROUP2,...[,GROUPN]]]
76           A list of supplementary groups which the user is also a member of.
77           Each group is separated from the next by a comma, with no
78           intervening whitespace. The groups must exist.
79
80           If the user is currently a member of a group which is not listed,
81           the user will be removed from the group. This behaviour can be
82           changed via the -a option, which appends the user to the current
83           supplementary group list.
84
85       -l, --login NEW_LOGIN
86           The name of the user will be changed from LOGIN to NEW_LOGIN.
87           Nothing else is changed. In particular, the user's home directory
88           or mail spool should probably be renamed manually to reflect the
89           new login name.
90
91       -L, --lock
92           Lock a user's password. This puts a '!' in front of the encrypted
93           password, effectively disabling the password. You can't use this
94           option with -p or -U.
95
96           Note: if you wish to lock the account (not only access with a
97           password), you should also set the EXPIRE_DATE to 1.
98
99       -m, --move-home
100           moves the content of the user's home directory to the new location.
101           If the current home directory does not exist the new home directory
102           will not be created.
103
104           This option is only valid in combination with the -d (or --home)
105           option.
106
107           usermod will try to adapt the ownership of the files and to copy
108           the modes, ACL and extended attributes, but manual changes might be
109           needed afterwards.
110
111       -o, --non-unique
112           allows to change the user ID to a non-unique value.
113
114           This option is only valid in combination with the -u option. As a
115           user identity serves as key to map between users on one hand and
116           permissions, file ownerships and other aspects that determine the
117           system's behavior on the other hand, more than one login name will
118           access the account of the given UID.
119
120       -p, --password PASSWORD
121           defines a new password for the user. PASSWORD is expected to be
122           encrypted, as returned by crypt (3).
123
124           Note: Avoid this option on the command line because the password
125           (or encrypted password) will be visible by users listing the
126           processes.
127
128           You should make sure the password respects the system's password
129           policy.
130
131       -r, --remove
132           Remove the user from named supplementary group(s). Use only with
133           the -G option.
134
135       -R, --root CHROOT_DIR
136           Apply changes in the CHROOT_DIR directory and use the configuration
137           files from the CHROOT_DIR directory. Only absolute paths are
138           supported.
139
140       -P, --prefix PREFIX_DIR
141           Apply changes within the directory tree starting with PREFIX_DIR
142           and use as well the configuration files located there. This option
143           does not chroot and is intended for preparing a cross-compilation
144           target. Some limitations: NIS and LDAP users/groups are not
145           verified. PAM authentication is using the host files. No SELINUX
146           support.
147
148       -s, --shell SHELL
149           changes the user's login shell. An empty string for SHELL blanks
150           the field in /etc/passwd and logs the user into the system's
151           default shell.
152
153       -u, --uid UID
154           The new value of the user's ID.
155
156           This value must be unique, unless the -o option is used. The value
157           must be non-negative.
158
159           The user's mailbox, and any files which the user owns and which are
160           located in the user's home directory will have the file user ID
161           changed automatically.
162
163           The ownership of files outside of the user's home directory must be
164           fixed manually.
165
166           The change of the user ownership of files inside of the user's home
167           directory is also not done if the home dir owner uid is different
168           from the current or new user id. This is a safety measure for
169           special home directories such as /.
170
171           No checks will be performed with regard to the UID_MIN, UID_MAX,
172           SYS_UID_MIN, or SYS_UID_MAX from /etc/login.defs.
173
174       -U, --unlock
175           Unlock a user's password. This removes the '!' in front of the
176           encrypted password. You can't use this option with -p or -L.
177
178           Note: if you wish to unlock the account (not only access with a
179           password), you should also set the EXPIRE_DATE (for example to
180           99999, or to the EXPIRE value from /etc/default/useradd).
181
182       -v, --add-subuids FIRST-LAST
183           Add a range of subordinate uids to the user's account.
184
185           This option may be specified multiple times to add multiple ranges
186           to a user's account.
187
188           No checks will be performed with regard to SUB_UID_MIN,
189           SUB_UID_MAX, or SUB_UID_COUNT from /etc/login.defs.
190
191       -V, --del-subuids FIRST-LAST
192           Remove a range of subordinate uids from the user's account.
193
194           This option may be specified multiple times to remove multiple
195           ranges to a user's account. When both --del-subuids and
196           --add-subuids are specified, the removal of all subordinate uid
197           ranges happens before any subordinate uid range is added.
198
199           No checks will be performed with regard to SUB_UID_MIN,
200           SUB_UID_MAX, or SUB_UID_COUNT from /etc/login.defs.
201
202       -w, --add-subgids FIRST-LAST
203           Add a range of subordinate gids to the user's account.
204
205           This option may be specified multiple times to add multiple ranges
206           to a user's account.
207
208           No checks will be performed with regard to SUB_GID_MIN,
209           SUB_GID_MAX, or SUB_GID_COUNT from /etc/login.defs.
210
211       -W, --del-subgids FIRST-LAST
212           Remove a range of subordinate gids from the user's account.
213
214           This option may be specified multiple times to remove multiple
215           ranges to a user's account. When both --del-subgids and
216           --add-subgids are specified, the removal of all subordinate gid
217           ranges happens before any subordinate gid range is added.
218
219           No checks will be performed with regard to SUB_GID_MIN,
220           SUB_GID_MAX, or SUB_GID_COUNT from /etc/login.defs.
221
222       -Z, --selinux-user SEUSER
223           defines the SELinux user to be mapped with LOGIN. An empty string
224           ("") will remove the respective entry (if any). Note that the
225           shadow system doesn't store the selinux-user, it uses semanage(8)
226           for that.
227

CAVEATS

229       You must make certain that the named user is not executing any
230       processes when this command is being executed if the user's numerical
231       user ID, the user's name, or the user's home directory is being
232       changed.  usermod checks this on Linux. On other operating systems it
233       only uses utmp to check if the user is logged in.
234
235       You must change the owner of any crontab files or at jobs manually.
236
237       You must make any changes involving NIS on the NIS server.
238

CONFIGURATION

240       The following configuration variables in /etc/login.defs change the
241       behavior of this tool:
242
243       LASTLOG_UID_MAX (number)
244           Highest user ID number for which the lastlog entries should be
245           updated. As higher user IDs are usually tracked by remote user
246           identity and authentication services there is no need to create a
247           huge sparse lastlog file for them.
248
249           No LASTLOG_UID_MAX option present in the configuration means that
250           there is no user ID limit for writing lastlog entries.
251
252       MAIL_DIR (string)
253           The mail spool directory. This is needed to manipulate the mailbox
254           when its corresponding user account is modified or deleted. If not
255           specified, a compile-time default is used. The parameter
256           CREATE_MAIL_SPOOL in /etc/default/useradd determines whether the
257           mail spool should be created.
258
259       MAIL_FILE (string)
260           Defines the location of the users mail spool files relatively to
261           their home directory.
262
263       The MAIL_DIR and MAIL_FILE variables are used by useradd, usermod, and
264       userdel to create, move, or delete the user's mail spool.
265
266       If MAIL_CHECK_ENAB is set to yes, they are also used to define the MAIL
267       environment variable.
268
269       MAX_MEMBERS_PER_GROUP (number)
270           Maximum members per group entry. When the maximum is reached, a new
271           group entry (line) is started in /etc/group (with the same name,
272           same password, and same GID).
273
274           The default value is 0, meaning that there are no limits in the
275           number of members in a group.
276
277           This feature (split group) permits to limit the length of lines in
278           the group file. This is useful to make sure that lines for NIS
279           groups are not larger than 1024 characters.
280
281           If you need to enforce such limit, you can use 25.
282
283           Note: split groups may not be supported by all tools (even in the
284           Shadow toolsuite). You should not use this variable unless you
285           really need it.
286
287       SUB_GID_MIN (number), SUB_GID_MAX (number), SUB_GID_COUNT (number)
288           If /etc/subuid exists, the commands useradd and newusers (unless
289           the user already have subordinate group IDs) allocate SUB_GID_COUNT
290           unused group IDs from the range SUB_GID_MIN to SUB_GID_MAX for each
291           new user.
292
293           The default values for SUB_GID_MIN, SUB_GID_MAX, SUB_GID_COUNT are
294           respectively 100000, 600100000 and 65536.
295
296       SUB_UID_MIN (number), SUB_UID_MAX (number), SUB_UID_COUNT (number)
297           If /etc/subuid exists, the commands useradd and newusers (unless
298           the user already have subordinate user IDs) allocate SUB_UID_COUNT
299           unused user IDs from the range SUB_UID_MIN to SUB_UID_MAX for each
300           new user.
301
302           The default values for SUB_UID_MIN, SUB_UID_MAX, SUB_UID_COUNT are
303           respectively 100000, 600100000 and 65536.
304

FILES

306       /etc/group
307           Group account information
308
309       /etc/gshadow
310           Secure group account informatio.
311
312       /etc/login.defs
313           Shadow password suite configuration
314
315       /etc/passwd
316           User account information
317
318       /etc/shadow
319           Secure user account information
320
321       /etc/subgid
322           Per user subordinate group IDs
323
324       /etc/subuid
325           Per user subordinate user IDs
326

SEE ALSO

328       chfn(1), chsh(1), passwd(1), crypt(3), gpasswd(8), groupadd(8),
329       groupdel(8), groupmod(8), login.defs(5), subgid(5), subuid(5),
330       useradd(8), userdel(8).
331
332
333
334shadow-utils 4.13                 03/06/2023                        USERMOD(8)
Impressum