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
  88 .RS 4n
  89 The base directory for new login home directories (see the \fB-d\fR option
  90 below. When a new user account is being created, \fIbase_dir\fR must already
  91 exist unless the \fB-m\fR option or the \fB-d\fR option is also specified.
  92 .RE
  93 
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fB-c\fR \fIcomment\fR\fR
  98 .ad
  99 .sp .6
 100 .RS 4n
 101 Any text string. It is generally a short description of the login, and is
 102 currently used as the field for the user's full name. This information is
 103 stored in the user's \fB/etc/passwd\fR entry.
 104 .RE
 105 
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fB-d\fR \fIdir\fR\fR
 110 .ad
 111 .sp .6
 112 .RS 4n
 113 The home directory of the new user. It defaults to
 114 \fIbase_dir\fR/\fIaccount_name\fR, where \fIbase_dir\fR is the base directory
 115 for new login home directories and \fIaccount_name\fR is the new login name.
 116 .RE
 117 
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fB-D\fR\fR
 122 .ad
 123 .sp .6
 124 .RS 4n
 125 Display the default values for \fBgroup\fR, \fBbase_dir\fR, \fBskel_dir\fR,
 126 \fBshell\fR, \fBinactive\fR, \fBexpire\fR, \fBproj\fR, \fBprojname\fR and
 127 \fBkey=value\fR pairs. When used with the \fB-g\fR, \fB-b\fR, \fB-f\fR,
 128 \fB-e\fR, \fB-A\fR, \fB-P\fR, \fB-p\fR, \fB-R\fR, or \fB-K\fR options, the
 129 \fB-D\fR option sets the default values for the specified fields. The default
 130 values are:
 131 .sp
 132 .ne 2
 133 .na
 134 \fBgroup\fR
 135 .ad
 136 .sp .6
 137 .RS 4n
 138 \fBother\fR (\fBGID\fR of 1)
 139 .RE
 140 
 141 .sp
 142 .ne 2
 143 .na
 144 \fBbase_dir\fR
 145 .ad
 146 .sp .6
 147 .RS 4n
 148 \fB/home\fR
 149 .RE
 150 
 151 .sp
 152 .ne 2
 153 .na
 154 \fBskel_dir\fR
 155 .ad
 156 .sp .6
 157 .RS 4n
 158 \fB/etc/skel\fR
 159 .RE
 160 
 161 .sp
 162 .ne 2
 163 .na
 164 \fBshell\fR
 165 .ad
 166 .sp .6
 167 .RS 4n
 168 \fB/bin/sh\fR
 169 .RE
 170 
 171 .sp
 172 .ne 2
 173 .na
 174 \fBinactive\fR
 175 .ad
 176 .sp .6
 177 .RS 4n
 178 \fB0\fR
 179 .RE
 180 
 181 .sp
 182 .ne 2
 183 .na
 184 \fBexpire\fR
 185 .ad
 186 .sp .6
 187 .RS 4n
 188 null
 189 .RE
 190 
 191 .sp
 192 .ne 2
 193 .na
 194 \fBauths\fR
 195 .ad
 196 .sp .6
 197 .RS 4n
 198 null
 199 .RE
 200 
 201 .sp
 202 .ne 2
 203 .na
 204 \fBprofiles\fR
 205 .ad
 206 .sp .6
 207 .RS 4n
 208 null
 209 .RE
 210 
 211 .sp
 212 .ne 2
 213 .na
 214 \fBproj\fR
 215 .ad
 216 .sp .6
 217 .RS 4n
 218 \fB3\fR
 219 .RE
 220 
 221 .sp
 222 .ne 2
 223 .na
 224 \fBprojname\fR
 225 .ad
 226 .sp .6
 227 .RS 4n
 228 \fBdefault\fR
 229 .RE
 230 
 231 .sp
 232 .ne 2
 233 .na
 234 \fBkey=value (pairs defined in \fBuser_attr\fR(4)\fR
 235 .ad
 236 .sp .6
 237 .RS 4n
 238 not present
 239 .RE
 240 
 241 .sp
 242 .ne 2
 243 .na
 244 \fBroles\fR
 245 .ad
 246 .sp .6
 247 .RS 4n
 248 null
 249 .RE
 250 
 251 .RE
 252 
 253 .sp
 254 .ne 2
 255 .na
 256 \fB\fB-e\fR \fIexpire\fR\fR
 257 .ad
 258 .sp .6
 259 .RS 4n
 260 Specify the expiration date for a login. After this date, no user will be able
 261 to access this login. The expire option argument is a date entered using one of
 262 the date formats included in the template file \fB/etc/datemsk\fR. See
 263 \fBgetdate\fR(3C).
 264 .sp
 265 If the date format that you choose includes spaces, it must be quoted. For
 266 example, you can enter \fB10/6/90\fR or \fBOctober 6, 1990\fR. A null value
 267 (\fB" "\fR) defeats the status of the expired date. This option is useful for
 268 creating temporary logins.
 269 .RE
 270 
 271 .sp
 272 .ne 2
 273 .na
 274 \fB\fB-f\fR \fIinactive\fR\fR
 275 .ad
 276 .sp .6
 277 .RS 4n
 278 The maximum number of days allowed between uses of a login ID before that
 279 \fBID\fR is declared invalid. Normal values are positive integers. A value of
 280 \fB0\fR defeats the status.
 281 .RE
 282 
 283 .sp
 284 .ne 2
 285 .na
 286 \fB\fB-g\fR \fIgroup\fR\fR
 287 .ad
 288 .sp .6
 289 .RS 4n
 290 An existing group's integer \fBID\fR or character-string name. Without the
 291 \fB-D\fR option, it defines the new user's primary group membership and
 292 defaults to the default group. You can reset this default value by invoking
 293 \fBuseradd\fR \fB-D\fR \fB-g\fR \fIgroup\fR. GIDs 0-99 are reserved for
 294 allocation by the Solaris Operating System.
 295 .RE
 296 
 297 .sp
 298 .ne 2
 299 .na
 300 \fB\fB-G\fR \fIgroup\fR\fR
 301 .ad
 302 .sp .6
 303 .RS 4n
 304 An existing group's integer \fBID\fR or character-string name. It defines the
 305 new user's supplementary group membership. Duplicates between \fIgroup\fR with
 306 the \fB-g\fR and \fB-G\fR options are ignored. No more than \fBNGROUPS_MAX\fR
 307 groups can be specified. GIDs 0-99 are reserved for allocation by the Solaris
 308 Operating System.
 309 .RE
 310 
 311 .sp
 312 .ne 2
 313 .na
 314 \fB\fB-K\fR \fIkey=value\fR\fR
 315 .ad
 316 .sp .6
 317 .RS 4n
 318 A \fIkey=value\fR pair to add to the user's attributes. Multiple \fB-K\fR
 319 options may be used to add multiple \fIkey=value\fR pairs. The generic \fB-K\fR
 320 option with the appropriate key may be used instead of the specific implied key
 321 options (\fB-A\fR, \fB-P\fR, \fB-R\fR, \fB-p\fR). See \fBuser_attr\fR(4) for a
 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).
 375 .RE
 376 
 377 .sp
 378 .ne 2
 379 .na
 380 \fB\fB-p\fR \fIprojname\fR\fR
 381 .ad
 382 .sp .6
 383 .RS 4n
 384 Name of the project with which the added user is associated. See the
 385 \fIprojname\fR field as defined in \fBproject\fR(4).
 386 .RE
 387 
 388 .sp
 389 .ne 2
 390 .na
 391 \fB\fB-R\fR \fIrole\fR\fR
 392 .ad
 393 .sp .6
 394 .RS 4n
 395 One or more comma-separated execution profiles defined in \fBuser_attr\fR(4).
 396 Roles cannot be assigned to other roles.
 397 .RE
 398 
 399 .sp
 400 .ne 2
 401 .na
 402 \fB\fB-s\fR \fIshell\fR\fR
 403 .ad
 404 .sp .6
 405 .RS 4n
 406 Full pathname of the program used as the user's shell on login. It defaults to
 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
 493 .nf
 494 UX: useradd: ERROR: uid \fIuid\fR is already in use. Choose another.
 495 .fi
 496 .in -2
 497 .sp
 498 
 499 .sp
 500 .LP
 501 The following indicates that the \fIgroup\fR specified with the \fB-g\fR option
 502 is already in use:
 503 .sp
 504 .in +2
 505 .nf
 506 UX: useradd: ERROR: group \fIgroup\fR does not exist. Choose another.
 507 .fi
 508 .in -2
 509 .sp
 510 
 511 .sp
 512 .LP
 513 The following indicates that the \fIuid\fR specified with the \fB-u\fR option
 514 is in the range of reserved \fBUID\fRs (from \fB0\fR-\fB99\fR):
 515 .sp
 516 .in +2
 517 .nf
 518 UX: useradd: WARNING: uid \fIuid\fR is reserved.
 519 .fi
 520 .in -2
 521 .sp
 522 
 523 .sp
 524 .LP
 525 The following indicates that the \fIuid\fR specified with the \fB-u\fR option
 526 exceeds \fBMAXUID\fR as defined in \fB<sys/param.h>\fR:
 527 .sp
 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.