Print this page
293 useradd/del/mod should be ZFS-aware
   1 '\" te
   2 .\" Copyright (c) 2013 Gary Mills
   3 .\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved.
   4 .\" Copyright 1989 AT&T
   5 .\" 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.
   6 .\" 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.
   7 .\" 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]
   8 .TH USERADD 1M "Apr 16, 2013"
   9 .SH NAME
  10 useradd \- administer a new user login on the system
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 \fBuseradd\fR [\fB-A\fR \fIauthorization\fR [,\fIauthorization...\fR]]
  15      [\fB-b\fR \fIbase_dir\fR] [\fB-c\fR \fIcomment\fR] [\fB-d\fR \fIdir\fR] [\fB-e\fR \fIexpire\fR]
  16      [\fB-f\fR \fIinactive\fR] [\fB-g\fR \fIgroup\fR] [\fB-G\fR \fIgroup\fR [,\fIgroup\fR]...]
  17      [\fB-K\fR \fIkey=value\fR] [\fB-m\fR [\fB-k\fR \fIskel_dir\fR]] [\fB-p\fR \fIprojname\fR]
  18      [\fB-P\fR \fIprofile\fR [,\fIprofile...\fR]] [\fB-R\fR \fIrole\fR [,\fIrole...\fR]]
  19      [\fB-s\fR \fIshell\fR] [\fB-u\fR \fIuid\fR [\fB-o\fR]] \fIlogin\fR
  20 .fi
  21 
  22 .LP
  23 .nf
  24 \fBuseradd\fR \fB-D\fR [\fB-A\fR \fIauthorization\fR [,\fIauthorization...\fR]]
  25      [\fB-b\fR \fIbase_dir\fR] [\fB-s\fR \fIshell\fR [\fB-k\fR \fIskel_dir\fR]] [\fB-e\fR \fIexpire\fR]
  26      [\fB-f\fR \fIinactive\fR] [\fB-g\fR \fIgroup\fR] [\fB-K\fR \fIkey=value\fR] [\fB-p\fR \fIprojname\fR]
  27      [\fB-P\fR \fIprofile\fR [,\fIprofile...\fR]] [\fB-R\fR \fIrole\fR [,\fIrole...\fR]]
  28 .fi
  29 
  30 .SH DESCRIPTION
  31 .sp
  32 .LP
  33 \fBuseradd\fR adds a new user to the \fB/etc/passwd\fR and \fB/etc/shadow\fR
  34 and \fB/etc/user_attr\fR files. The \fB-A\fR and \fB-P\fR options respectively
  35 assign authorizations and profiles to the user. The \fB-R\fR option assigns
  36 roles to a user. The \fB-p\fR option associates a project with a user. The
  37 \fB-K\fR option adds a \fIkey=value\fR pair to \fB/etc/user_attr\fR for the
  38 user. Multiple \fIkey=value\fR pairs may be added with multiple \fB-K\fR
  39 options.
  40 .sp
  41 .LP
  42 \fBuseradd\fR also creates supplementary group memberships for the user
  43 (\fB-G\fR option) and creates the home directory (\fB-m\fR option) for the user
  44 if requested. The new login remains locked until the \fBpasswd\fR(1) command is
  45 executed.
  46 .sp
  47 .LP
  48 Specifying \fBuseradd\fR \fB-D\fR with the \fB-s\fR, \fB-k\fR,\fB-g\fR,
  49 \fB-b\fR, \fB-f\fR, \fB-e\fR, \fB-A\fR, \fB-P\fR, \fB-p\fR, \fB-R\fR, or
  50 \fB-K\fR option (or any combination of these options) sets the default values
  51 for the respective fields. See the \fB-D\fR option, below. Subsequent
  52 \fBuseradd\fR commands without the \fB-D\fR option use these arguments.
  53 .sp
  54 .LP
  55 The system file entries created with this command have a limit of 2048
  56 characters per line. Specifying long arguments to several options can exceed
  57 this limit.
  58 .sp
  59 .LP
  60 \fBuseradd\fR requires that usernames be in the format described in
  61 \fBpasswd\fR(4). A warning message is displayed if these restrictions are not
  62 met. See \fBpasswd\fR(4) for the requirements for usernames.
  63 .LP
  64 To change the action of \fBuseradd\fR when the traditional login name
  65 length limit of eight characters is exceeded, edit the file
  66 \fB/etc/default/useradd\fR by removing the \fB#\fR (pound sign) before the
  67 appropriate \fBEXCEED_TRAD=\fR entry, and adding it before the others.
  68 .SH OPTIONS
  69 .sp
  70 .LP
  71 The following options are supported:
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fB-A\fR \fIauthorization\fR\fR
  76 .ad
  77 .sp .6
  78 .RS 4n
  79 One or more comma separated authorizations defined in \fBauth_attr\fR(4). Only
  80 a user or role who has \fBgrant\fR rights to the authorization can assign it to
  81 an account.
  82 .RE
  83 
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fB-b\fR \fIbase_dir\fR\fR
  88 .ad
  89 .sp .6


 324 list of valid \fIkey=value\fR pairs. The "type" key is not a valid key for this
 325 option. Keys may not be repeated.
 326 .RE
 327 
 328 .sp
 329 .ne 2
 330 .na
 331 \fB\fB-k\fR \fIskel_dir\fR\fR
 332 .ad
 333 .sp .6
 334 .RS 4n
 335 A directory that contains skeleton information (such as \fB\&.profile\fR) that
 336 can be copied into a new user's home directory. This directory must already
 337 exist. The system provides the \fB/etc/skel\fR directory that can be used for
 338 this purpose.
 339 .RE
 340 
 341 .sp
 342 .ne 2
 343 .na
 344 \fB\fB-m\fR\fR
 345 .ad
 346 .sp .6
 347 .RS 4n
 348 Create the new user's home directory if it does not already exist. If the
 349 directory already exists, it must have read, write, and execute permissions by
 350 \fIgroup\fR, where \fIgroup\fR is the user's primary group.






 351 .RE
 352 
 353 .sp
 354 .ne 2
 355 .na
 356 \fB\fB-o\fR\fR
 357 .ad
 358 .sp .6
 359 .RS 4n
 360 This option allows a \fBUID\fR to be duplicated (non-unique).
 361 .RE
 362 
 363 .sp
 364 .ne 2
 365 .na
 366 \fB\fB-P\fR \fIprofile\fR\fR
 367 .ad
 368 .sp .6
 369 .RS 4n
 370 One or more comma-separated execution profiles defined in \fBprof_attr\fR(4).


 403 an empty field causing the system to use \fB/bin/sh\fR as the default. The
 404 value of \fIshell\fR must be a valid executable file.
 405 .RE
 406 
 407 .sp
 408 .ne 2
 409 .na
 410 \fB\fB-u\fR \fIuid\fR\fR
 411 .ad
 412 .sp .6
 413 .RS 4n
 414 The \fBUID\fR of the new user. This \fBUID\fR must be a non-negative decimal
 415 integer below \fBMAXUID\fR as defined in \fB<sys/param.h>\fR\&. The \fBUID\fR
 416 defaults to the next available (unique) number above the highest number
 417 currently assigned. For example, if \fBUID\fRs 100, 105, and 200 are assigned,
 418 the next default \fBUID\fR number will be 201. \fBUID\fRs \fB0\fR-\fB99\fR are
 419 reserved for allocation by the Solaris Operating System.
 420 .RE
 421 
 422 .SH FILES
 423 .sp
 424 .LP
 425 \fB/etc/default/useradd\fR
 426 .sp
 427 .LP
 428 \fB/etc/datemsk\fR
 429 .sp
 430 .LP
 431 \fB/etc/passwd\fR
 432 .sp
 433 .LP
 434 \fB/etc/shadow\fR
 435 .sp
 436 .LP
 437 \fB/etc/group\fR
 438 .sp
 439 .LP
 440 \fB/etc/skel\fR
 441 .sp
 442 .LP
 443 \fB/usr/include/limits.h\fR
 444 .sp
 445 .LP
 446 \fB/etc/user_attr\fR
 447 .SH ATTRIBUTES
 448 .sp
 449 .LP
 450 See \fBattributes\fR(5) for descriptions of the following attributes:
 451 .sp
 452 
 453 .sp
 454 .TS
 455 box;
 456 c | c
 457 l | l .
 458 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 459 _
 460 Interface Stability     Committed
 461 .TE
 462 
 463 .SH SEE ALSO
 464 .sp
 465 .LP
 466 \fBpasswd\fR(1), \fBprofiles\fR(1), \fBroles\fR(1), \fBusers\fR(1B),
 467 \fBgroupadd\fR(1M), \fBgroupdel\fR(1M), \fBgroupmod\fR(1M), \fBgrpck\fR(1M),
 468 \fBlogins\fR(1M), \fBpwck\fR(1M), \fBuserdel\fR(1M), \fBusermod\fR(1M),
 469 \fBgetdate\fR(3C), \fBauth_attr\fR(4), \fBpasswd\fR(4), \fBprof_attr\fR(4),
 470 \fBproject\fR(4), \fBuser_attr\fR(4), \fBattributes\fR(5)
 471 .SH DIAGNOSTICS
 472 .sp
 473 .LP
 474 In case of an error, \fBuseradd\fR prints an error message and exits with a
 475 non-zero status.
 476 .sp
 477 .LP
 478 The following indicates that \fBlogin\fR specified is already in use:
 479 .sp
 480 .in +2
 481 .nf
 482 UX: useradd: ERROR: login is already in use. Choose another.
 483 .fi
 484 .in -2
 485 .sp
 486 
 487 .sp
 488 .LP
 489 The following indicates that the \fIuid\fR specified with the \fB-u\fR option
 490 is not unique:
 491 .sp
 492 .in +2


 528 .in +2
 529 .nf
 530 UX: useradd: ERROR: uid \fIuid\fR is too big. Choose another.
 531 .fi
 532 .in -2
 533 .sp
 534 
 535 .sp
 536 .LP
 537 The following indicates that the \fB/etc/passwd\fR or \fB/etc/shadow\fR files
 538 do not exist:
 539 .sp
 540 .in +2
 541 .nf
 542 UX: useradd: ERROR: Cannot update system files - login cannot be created.
 543 .fi
 544 .in -2
 545 .sp
 546 
 547 .SH NOTES
 548 .sp
 549 .LP
 550 The \fBuseradd\fR utility adds definitions to only the local \fB/etc/group\fR,
 551 \fBetc/passwd\fR, \fB/etc/passwd\fR, \fB/etc/shadow\fR, \fB/etc/project\fR, and
 552 \fB/etc/user_attr\fR files. If a network name service such as \fBNIS\fR or
 553 \fBNIS+\fR is being used to supplement the local \fB/etc/passwd\fR file with
 554 additional entries, \fBuseradd\fR cannot change information supplied by the
 555 network name service. However \fBuseradd\fR will verify the uniqueness of the
 556 user name (or role) and user id and the existence of any group names specified
 557 against the external name service.
   1 '\" te
   2 .\" Copyright (c) 2013 Gary Mills
   3 .\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved.
   4 .\" Copyright 1989 AT&T
   5 .\" 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.
   6 .\" 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.
   7 .\" 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]
   8 .TH USERADD 1M "Apr 16, 2013"
   9 .SH NAME
  10 useradd \- administer a new user login on the system
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 \fBuseradd\fR [\fB-A\fR \fIauthorization\fR [,\fIauthorization...\fR]]
  15      [\fB-b\fR \fIbase_dir\fR] [\fB-c\fR \fIcomment\fR] [\fB-d\fR \fIdir\fR] [\fB-e\fR \fIexpire\fR]
  16      [\fB-f\fR \fIinactive\fR] [\fB-g\fR \fIgroup\fR] [\fB-G\fR \fIgroup\fR [,\fIgroup\fR]...]
  17      [\fB-K\fR \fIkey=value\fR] [\fB-m\fR [\fB-z|-Z\fR] [\fB-k\fR \fIskel_dir\fR]] [\fB-p\fR \fIprojname\fR]
  18      [\fB-P\fR \fIprofile\fR [,\fIprofile...\fR]] [\fB-R\fR \fIrole\fR [,\fIrole...\fR]]
  19      [\fB-s\fR \fIshell\fR] [\fB-u\fR \fIuid\fR [\fB-o\fR]] \fIlogin\fR
  20 .fi
  21 
  22 .LP
  23 .nf
  24 \fBuseradd\fR \fB-D\fR [\fB-A\fR \fIauthorization\fR [,\fIauthorization...\fR]]
  25      [\fB-b\fR \fIbase_dir\fR] [\fB-s\fR \fIshell\fR [\fB-k\fR \fIskel_dir\fR]] [\fB-e\fR \fIexpire\fR]
  26      [\fB-f\fR \fIinactive\fR] [\fB-g\fR \fIgroup\fR] [\fB-K\fR \fIkey=value\fR] [\fB-p\fR \fIprojname\fR]
  27      [\fB-P\fR \fIprofile\fR [,\fIprofile...\fR]] [\fB-R\fR \fIrole\fR [,\fIrole...\fR]]
  28 .fi
  29 
  30 .SH DESCRIPTION

  31 .LP
  32 \fBuseradd\fR adds a new user to the \fB/etc/passwd\fR and \fB/etc/shadow\fR
  33 and \fB/etc/user_attr\fR files. The \fB-A\fR and \fB-P\fR options respectively
  34 assign authorizations and profiles to the user. The \fB-R\fR option assigns
  35 roles to a user. The \fB-p\fR option associates a project with a user. The
  36 \fB-K\fR option adds a \fIkey=value\fR pair to \fB/etc/user_attr\fR for the
  37 user. Multiple \fIkey=value\fR pairs may be added with multiple \fB-K\fR
  38 options.
  39 .sp
  40 .LP
  41 \fBuseradd\fR also creates supplementary group memberships for the user
  42 (\fB-G\fR option) and creates the home directory (\fB-m\fR option) for the user
  43 if requested. The new login remains locked until the \fBpasswd\fR(1) command is
  44 executed.
  45 .sp
  46 .LP
  47 Specifying \fBuseradd\fR \fB-D\fR with the \fB-s\fR, \fB-k\fR,\fB-g\fR,
  48 \fB-b\fR, \fB-f\fR, \fB-e\fR, \fB-A\fR, \fB-P\fR, \fB-p\fR, \fB-R\fR, or
  49 \fB-K\fR option (or any combination of these options) sets the default values
  50 for the respective fields. See the \fB-D\fR option, below. Subsequent
  51 \fBuseradd\fR commands without the \fB-D\fR option use these arguments.
  52 .sp
  53 .LP
  54 The system file entries created with this command have a limit of 2048
  55 characters per line. Specifying long arguments to several options can exceed
  56 this limit.
  57 .sp
  58 .LP
  59 \fBuseradd\fR requires that usernames be in the format described in
  60 \fBpasswd\fR(4). A warning message is displayed if these restrictions are not
  61 met. See \fBpasswd\fR(4) for the requirements for usernames.
  62 .LP
  63 To change the action of \fBuseradd\fR when the traditional login name
  64 length limit of eight characters is exceeded, edit the file
  65 \fB/etc/default/useradd\fR by removing the \fB#\fR (pound sign) before the
  66 appropriate \fBEXCEED_TRAD=\fR entry, and adding it before the others.
  67 .SH OPTIONS

  68 .LP
  69 The following options are supported:
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fB-A\fR \fIauthorization\fR\fR
  74 .ad
  75 .sp .6
  76 .RS 4n
  77 One or more comma separated authorizations defined in \fBauth_attr\fR(4). Only
  78 a user or role who has \fBgrant\fR rights to the authorization can assign it to
  79 an account.
  80 .RE
  81 
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fB-b\fR \fIbase_dir\fR\fR
  86 .ad
  87 .sp .6


 322 list of valid \fIkey=value\fR pairs. The "type" key is not a valid key for this
 323 option. Keys may not be repeated.
 324 .RE
 325 
 326 .sp
 327 .ne 2
 328 .na
 329 \fB\fB-k\fR \fIskel_dir\fR\fR
 330 .ad
 331 .sp .6
 332 .RS 4n
 333 A directory that contains skeleton information (such as \fB\&.profile\fR) that
 334 can be copied into a new user's home directory. This directory must already
 335 exist. The system provides the \fB/etc/skel\fR directory that can be used for
 336 this purpose.
 337 .RE
 338 
 339 .sp
 340 .ne 2
 341 .na
 342 \fB\fB-m\fR\fR [\fB-z|-Z\fR]
 343 .ad
 344 .sp .6
 345 .RS 4n
 346 Create the new user's home directory if it does not already exist. If the
 347 directory already exists, it must have read, write, and execute permissions by
 348 \fIgroup\fR, where \fIgroup\fR is the user's primary group.
 349 CHANGE_ZFS_FS option in /etc/default/useradd file determines if ZFS filesystem
 350 will be created for new user. If this option is set to yes and parent directory
 351 of user's home directory is ZFS filesystem mount point, a new ZFS filesystem is
 352 created. \fB-z\fR and \fB-Z\fR options allow overwrite default behavior.
 353 If \fB-z\fR option is specified, \fBuseradd\fR tries to create new file system
 354 for user. If \fB-Z\fR option is specified, new file system is not created.
 355 .RE
 356 
 357 .sp
 358 .ne 2
 359 .na
 360 \fB\fB-o\fR\fR
 361 .ad
 362 .sp .6
 363 .RS 4n
 364 This option allows a \fBUID\fR to be duplicated (non-unique).
 365 .RE
 366 
 367 .sp
 368 .ne 2
 369 .na
 370 \fB\fB-P\fR \fIprofile\fR\fR
 371 .ad
 372 .sp .6
 373 .RS 4n
 374 One or more comma-separated execution profiles defined in \fBprof_attr\fR(4).


 407 an empty field causing the system to use \fB/bin/sh\fR as the default. The
 408 value of \fIshell\fR must be a valid executable file.
 409 .RE
 410 
 411 .sp
 412 .ne 2
 413 .na
 414 \fB\fB-u\fR \fIuid\fR\fR
 415 .ad
 416 .sp .6
 417 .RS 4n
 418 The \fBUID\fR of the new user. This \fBUID\fR must be a non-negative decimal
 419 integer below \fBMAXUID\fR as defined in \fB<sys/param.h>\fR\&. The \fBUID\fR
 420 defaults to the next available (unique) number above the highest number
 421 currently assigned. For example, if \fBUID\fRs 100, 105, and 200 are assigned,
 422 the next default \fBUID\fR number will be 201. \fBUID\fRs \fB0\fR-\fB99\fR are
 423 reserved for allocation by the Solaris Operating System.
 424 .RE
 425 
 426 .SH FILES

 427 .LP
 428 \fB/etc/default/useradd\fR
 429 .sp
 430 .LP
 431 \fB/etc/datemsk\fR
 432 .sp
 433 .LP
 434 \fB/etc/passwd\fR
 435 .sp
 436 .LP
 437 \fB/etc/shadow\fR
 438 .sp
 439 .LP
 440 \fB/etc/group\fR
 441 .sp
 442 .LP
 443 \fB/etc/skel\fR
 444 .sp
 445 .LP
 446 \fB/usr/include/limits.h\fR
 447 .sp
 448 .LP
 449 \fB/etc/user_attr\fR
 450 .SH ATTRIBUTES

 451 .LP
 452 See \fBattributes\fR(5) for descriptions of the following attributes:
 453 .sp
 454 
 455 .sp
 456 .TS
 457 box;
 458 c | c
 459 l | l .
 460 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 461 _
 462 Interface Stability     Committed
 463 .TE
 464 
 465 .SH SEE ALSO

 466 .LP
 467 \fBpasswd\fR(1), \fBprofiles\fR(1), \fBroles\fR(1), \fBusers\fR(1B),
 468 \fBgroupadd\fR(1M), \fBgroupdel\fR(1M), \fBgroupmod\fR(1M), \fBgrpck\fR(1M),
 469 \fBlogins\fR(1M), \fBpwck\fR(1M), \fBuserdel\fR(1M), \fBusermod\fR(1M),
 470 \fBgetdate\fR(3C), \fBauth_attr\fR(4), \fBpasswd\fR(4), \fBprof_attr\fR(4),
 471 \fBproject\fR(4), \fBuser_attr\fR(4), \fBattributes\fR(5)
 472 .SH DIAGNOSTICS

 473 .LP
 474 In case of an error, \fBuseradd\fR prints an error message and exits with a
 475 non-zero status.
 476 .sp
 477 .LP
 478 The following indicates that \fBlogin\fR specified is already in use:
 479 .sp
 480 .in +2
 481 .nf
 482 UX: useradd: ERROR: login is already in use. Choose another.
 483 .fi
 484 .in -2
 485 .sp
 486 
 487 .sp
 488 .LP
 489 The following indicates that the \fIuid\fR specified with the \fB-u\fR option
 490 is not unique:
 491 .sp
 492 .in +2


 528 .in +2
 529 .nf
 530 UX: useradd: ERROR: uid \fIuid\fR is too big. Choose another.
 531 .fi
 532 .in -2
 533 .sp
 534 
 535 .sp
 536 .LP
 537 The following indicates that the \fB/etc/passwd\fR or \fB/etc/shadow\fR files
 538 do not exist:
 539 .sp
 540 .in +2
 541 .nf
 542 UX: useradd: ERROR: Cannot update system files - login cannot be created.
 543 .fi
 544 .in -2
 545 .sp
 546 
 547 .SH NOTES

 548 .LP
 549 The \fBuseradd\fR utility adds definitions to only the local \fB/etc/group\fR,
 550 \fBetc/passwd\fR, \fB/etc/passwd\fR, \fB/etc/shadow\fR, \fB/etc/project\fR, and
 551 \fB/etc/user_attr\fR files. If a network name service such as \fBNIS\fR or
 552 \fBNIS+\fR is being used to supplement the local \fB/etc/passwd\fR file with
 553 additional entries, \fBuseradd\fR cannot change information supplied by the
 554 network name service. However \fBuseradd\fR will verify the uniqueness of the
 555 user name (or role) and user id and the existence of any group names specified
 556 against the external name service.