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