1 '\" te
   2 .\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH USERADD 1M "Feb 19, 2008"
   8 .SH NAME
   9 useradd \- administer a new user login on the system
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBuseradd\fR [\fB-A\fR \fIauthorization\fR [,\fIauthorization...\fR]]
  14      [\fB-b\fR \fIbase_dir\fR] [\fB-c\fR \fIcomment\fR] [\fB-d\fR \fIdir\fR] [\fB-e\fR \fIexpire\fR]
  15      [\fB-f\fR \fIinactive\fR] [\fB-g\fR \fIgroup\fR] [\fB-G\fR \fIgroup\fR [,\fIgroup\fR]...]
  16      [\fB-K\fR \fIkey=value\fR] [\fB-m\fR [\fB-k\fR \fIskel_dir\fR]] [\fB-p\fR \fIprojname\fR]
  17      [\fB-P\fR \fIprofile\fR [,\fIprofile...\fR]] [\fB-R\fR \fIrole\fR [,\fIrole...\fR]]
  18      [\fB-s\fR \fIshell\fR] [\fB-u\fR \fIuid\fR [\fB-o\fR]] \fIlogin\fR
  19 .fi
  20 
  21 .LP
  22 .nf
  23 \fBuseradd\fR \fB-D\fR [\fB-A\fR \fIauthorization\fR [,\fIauthorization...\fR]]
  24      [\fB-b\fR \fIbase_dir\fR] [\fB-s\fR \fIshell\fR [\fB-k\fR \fIskel_dir\fR]] [\fB-e\fR \fIexpire\fR]
  25      [\fB-f\fR \fIinactive\fR] [\fB-g\fR \fIgroup\fR] [\fB-K\fR \fIkey=value\fR] [\fB-p\fR \fIprojname\fR]
  26      [\fB-P\fR \fIprofile\fR [,\fIprofile...\fR]] [\fB-R\fR \fIrole\fR [,\fIrole...\fR]]
  27 .fi
  28 
  29 .SH DESCRIPTION
  30 .sp
  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 .SH OPTIONS
  63 .sp
  64 .LP
  65 The following options are supported:
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fB-A\fR \fIauthorization\fR\fR
  70 .ad
  71 .sp .6
  72 .RS 4n
  73 One or more comma separated authorizations defined in \fBauth_attr\fR(4). Only
  74 a user or role who has \fBgrant\fR rights to the authorization can assign it to
  75 an account.
  76 .RE
  77 
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fB-b\fR \fIbase_dir\fR\fR
  82 .ad
  83 .sp .6
  84 .RS 4n
  85 The base directory for new login home directories (see the \fB-d\fR option
  86 below. When a new user account is being created, \fIbase_dir\fR must already
  87 exist unless the \fB-m\fR option or the \fB-d\fR option is also specified.
  88 .RE
  89 
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fB-c\fR \fIcomment\fR\fR
  94 .ad
  95 .sp .6
  96 .RS 4n
  97 Any text string. It is generally a short description of the login, and is
  98 currently used as the field for the user's full name. This information is
  99 stored in the user's \fB/etc/passwd\fR entry.
 100 .RE
 101 
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fB-d\fR \fIdir\fR\fR
 106 .ad
 107 .sp .6
 108 .RS 4n
 109 The home directory of the new user. It defaults to
 110 \fIbase_dir\fR/\fIaccount_name\fR, where \fIbase_dir\fR is the base directory
 111 for new login home directories and \fIaccount_name\fR is the new login name.
 112 .RE
 113 
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fB-D\fR\fR
 118 .ad
 119 .sp .6
 120 .RS 4n
 121 Display the default values for \fBgroup\fR, \fBbase_dir\fR, \fBskel_dir\fR,
 122 \fBshell\fR, \fBinactive\fR, \fBexpire\fR, \fBproj\fR, \fBprojname\fR and
 123 \fBkey=value\fR pairs. When used with the \fB-g\fR, \fB-b\fR, \fB-f\fR,
 124 \fB-e\fR, \fB-A\fR, \fB-P\fR, \fB-p\fR, \fB-R\fR, or \fB-K\fR options, the
 125 \fB-D\fR option sets the default values for the specified fields. The default
 126 values are:
 127 .sp
 128 .ne 2
 129 .na
 130 \fBgroup\fR
 131 .ad
 132 .sp .6
 133 .RS 4n
 134 \fBother\fR (\fBGID\fR of 1)
 135 .RE
 136 
 137 .sp
 138 .ne 2
 139 .na
 140 \fBbase_dir\fR
 141 .ad
 142 .sp .6
 143 .RS 4n
 144 \fB/home\fR
 145 .RE
 146 
 147 .sp
 148 .ne 2
 149 .na
 150 \fBskel_dir\fR
 151 .ad
 152 .sp .6
 153 .RS 4n
 154 \fB/etc/skel\fR
 155 .RE
 156 
 157 .sp
 158 .ne 2
 159 .na
 160 \fBshell\fR
 161 .ad
 162 .sp .6
 163 .RS 4n
 164 \fB/bin/sh\fR
 165 .RE
 166 
 167 .sp
 168 .ne 2
 169 .na
 170 \fBinactive\fR
 171 .ad
 172 .sp .6
 173 .RS 4n
 174 \fB0\fR
 175 .RE
 176 
 177 .sp
 178 .ne 2
 179 .na
 180 \fBexpire\fR
 181 .ad
 182 .sp .6
 183 .RS 4n
 184 null
 185 .RE
 186 
 187 .sp
 188 .ne 2
 189 .na
 190 \fBauths\fR
 191 .ad
 192 .sp .6
 193 .RS 4n
 194 null
 195 .RE
 196 
 197 .sp
 198 .ne 2
 199 .na
 200 \fBprofiles\fR
 201 .ad
 202 .sp .6
 203 .RS 4n
 204 null
 205 .RE
 206 
 207 .sp
 208 .ne 2
 209 .na
 210 \fBproj\fR
 211 .ad
 212 .sp .6
 213 .RS 4n
 214 \fB3\fR
 215 .RE
 216 
 217 .sp
 218 .ne 2
 219 .na
 220 \fBprojname\fR
 221 .ad
 222 .sp .6
 223 .RS 4n
 224 \fBdefault\fR
 225 .RE
 226 
 227 .sp
 228 .ne 2
 229 .na
 230 \fBkey=value (pairs defined in \fBuser_attr\fR(4)\fR
 231 .ad
 232 .sp .6
 233 .RS 4n
 234 not present
 235 .RE
 236 
 237 .sp
 238 .ne 2
 239 .na
 240 \fBroles\fR
 241 .ad
 242 .sp .6
 243 .RS 4n
 244 null
 245 .RE
 246 
 247 .RE
 248 
 249 .sp
 250 .ne 2
 251 .na
 252 \fB\fB-e\fR \fIexpire\fR\fR
 253 .ad
 254 .sp .6
 255 .RS 4n
 256 Specify the expiration date for a login. After this date, no user will be able
 257 to access this login. The expire option argument is a date entered using one of
 258 the date formats included in the template file \fB/etc/datemsk\fR. See
 259 \fBgetdate\fR(3C).
 260 .sp
 261 If the date format that you choose includes spaces, it must be quoted. For
 262 example, you can enter \fB10/6/90\fR or \fBOctober 6, 1990\fR. A null value
 263 (\fB" "\fR) defeats the status of the expired date. This option is useful for
 264 creating temporary logins.
 265 .RE
 266 
 267 .sp
 268 .ne 2
 269 .na
 270 \fB\fB-f\fR \fIinactive\fR\fR
 271 .ad
 272 .sp .6
 273 .RS 4n
 274 The maximum number of days allowed between uses of a login ID before that
 275 \fBID\fR is declared invalid. Normal values are positive integers. A value of
 276 \fB0\fR defeats the status.
 277 .RE
 278 
 279 .sp
 280 .ne 2
 281 .na
 282 \fB\fB-g\fR \fIgroup\fR\fR
 283 .ad
 284 .sp .6
 285 .RS 4n
 286 An existing group's integer \fBID\fR or character-string name. Without the
 287 \fB-D\fR option, it defines the new user's primary group membership and
 288 defaults to the default group. You can reset this default value by invoking
 289 \fBuseradd\fR \fB-D\fR \fB-g\fR \fIgroup\fR. GIDs 0-99 are reserved for
 290 allocation by the Solaris Operating System.
 291 .RE
 292 
 293 .sp
 294 .ne 2
 295 .na
 296 \fB\fB-G\fR \fIgroup\fR\fR
 297 .ad
 298 .sp .6
 299 .RS 4n
 300 An existing group's integer \fBID\fR or character-string name. It defines the
 301 new user's supplementary group membership. Duplicates between \fIgroup\fR with
 302 the \fB-g\fR and \fB-G\fR options are ignored. No more than \fBNGROUPS_MAX\fR
 303 groups can be specified. GIDs 0-99 are reserved for allocation by the Solaris
 304 Operating System.
 305 .RE
 306 
 307 .sp
 308 .ne 2
 309 .na
 310 \fB\fB-K\fR \fIkey=value\fR\fR
 311 .ad
 312 .sp .6
 313 .RS 4n
 314 A \fIkey=value\fR pair to add to the user's attributes. Multiple \fB-K\fR
 315 options may be used to add multiple \fIkey=value\fR pairs. The generic \fB-K\fR
 316 option with the appropriate key may be used instead of the specific implied key
 317 options (\fB-A\fR, \fB-P\fR, \fB-R\fR, \fB-p\fR). See \fBuser_attr\fR(4) for a
 318 list of valid \fIkey=value\fR pairs. The "type" key is not a valid key for this
 319 option. Keys may not be repeated.
 320 .RE
 321 
 322 .sp
 323 .ne 2
 324 .na
 325 \fB\fB-k\fR \fIskel_dir\fR\fR
 326 .ad
 327 .sp .6
 328 .RS 4n
 329 A directory that contains skeleton information (such as \fB\&.profile\fR) that
 330 can be copied into a new user's home directory. This directory must already
 331 exist. The system provides the \fB/etc/skel\fR directory that can be used for
 332 this purpose.
 333 .RE
 334 
 335 .sp
 336 .ne 2
 337 .na
 338 \fB\fB-m\fR\fR
 339 .ad
 340 .sp .6
 341 .RS 4n
 342 Create the new user's home directory if it does not already exist. If the
 343 directory already exists, it must have read, write, and execute permissions by
 344 \fIgroup\fR, where \fIgroup\fR is the user's primary group.
 345 .RE
 346 
 347 .sp
 348 .ne 2
 349 .na
 350 \fB\fB-o\fR\fR
 351 .ad
 352 .sp .6
 353 .RS 4n
 354 This option allows a \fBUID\fR to be duplicated (non-unique).
 355 .RE
 356 
 357 .sp
 358 .ne 2
 359 .na
 360 \fB\fB-P\fR \fIprofile\fR\fR
 361 .ad
 362 .sp .6
 363 .RS 4n
 364 One or more comma-separated execution profiles defined in \fBprof_attr\fR(4).
 365 .RE
 366 
 367 .sp
 368 .ne 2
 369 .na
 370 \fB\fB-p\fR \fIprojname\fR\fR
 371 .ad
 372 .sp .6
 373 .RS 4n
 374 Name of the project with which the added user is associated. See the
 375 \fIprojname\fR field as defined in \fBproject\fR(4).
 376 .RE
 377 
 378 .sp
 379 .ne 2
 380 .na
 381 \fB\fB-R\fR \fIrole\fR\fR
 382 .ad
 383 .sp .6
 384 .RS 4n
 385 One or more comma-separated execution profiles defined in \fBuser_attr\fR(4).
 386 Roles cannot be assigned to other roles.
 387 .RE
 388 
 389 .sp
 390 .ne 2
 391 .na
 392 \fB\fB-s\fR \fIshell\fR\fR
 393 .ad
 394 .sp .6
 395 .RS 4n
 396 Full pathname of the program used as the user's shell on login. It defaults to
 397 an empty field causing the system to use \fB/bin/sh\fR as the default. The
 398 value of \fIshell\fR must be a valid executable file.
 399 .RE
 400 
 401 .sp
 402 .ne 2
 403 .na
 404 \fB\fB-u\fR \fIuid\fR\fR
 405 .ad
 406 .sp .6
 407 .RS 4n
 408 The \fBUID\fR of the new user. This \fBUID\fR must be a non-negative decimal
 409 integer below \fBMAXUID\fR as defined in \fB<sys/param.h>\fR\&. The \fBUID\fR
 410 defaults to the next available (unique) number above the highest number
 411 currently assigned. For example, if \fBUID\fRs 100, 105, and 200 are assigned,
 412 the next default \fBUID\fR number will be 201. \fBUID\fRs \fB0\fR-\fB99\fR are
 413 reserved for allocation by the Solaris Operating System.
 414 .RE
 415 
 416 .SH FILES
 417 .sp
 418 .LP
 419 \fB/etc/datemsk\fR
 420 .sp
 421 .LP
 422 \fB/etc/passwd\fR
 423 .sp
 424 .LP
 425 \fB/etc/shadow\fR
 426 .sp
 427 .LP
 428 \fB/etc/group\fR
 429 .sp
 430 .LP
 431 \fB/etc/skel\fR
 432 .sp
 433 .LP
 434 \fB/usr/include/limits.h\fR
 435 .sp
 436 .LP
 437 \fB/etc/user_attr\fR
 438 .SH ATTRIBUTES
 439 .sp
 440 .LP
 441 See \fBattributes\fR(5) for descriptions of the following attributes:
 442 .sp
 443 
 444 .sp
 445 .TS
 446 box;
 447 c | c
 448 l | l .
 449 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 450 _
 451 Interface Stability     Committed
 452 .TE
 453 
 454 .SH SEE ALSO
 455 .sp
 456 .LP
 457 \fBpasswd\fR(1), \fBprofiles\fR(1), \fBroles\fR(1), \fBusers\fR(1B),
 458 \fBgroupadd\fR(1M), \fBgroupdel\fR(1M), \fBgroupmod\fR(1M), \fBgrpck\fR(1M),
 459 \fBlogins\fR(1M), \fBpwck\fR(1M), \fBuserdel\fR(1M), \fBusermod\fR(1M),
 460 \fBgetdate\fR(3C), \fBauth_attr\fR(4), \fBpasswd\fR(4), \fBprof_attr\fR(4),
 461 \fBproject\fR(4), \fBuser_attr\fR(4), \fBattributes\fR(5)
 462 .SH DIAGNOSTICS
 463 .sp
 464 .LP
 465 In case of an error, \fBuseradd\fR prints an error message and exits with a
 466 non-zero status.
 467 .sp
 468 .LP
 469 The following indicates that \fBlogin\fR specified is already in use:
 470 .sp
 471 .in +2
 472 .nf
 473 UX: useradd: ERROR: login is already in use. Choose another.
 474 .fi
 475 .in -2
 476 .sp
 477 
 478 .sp
 479 .LP
 480 The following indicates that the \fIuid\fR specified with the \fB-u\fR option
 481 is not unique:
 482 .sp
 483 .in +2
 484 .nf
 485 UX: useradd: ERROR: uid \fIuid\fR is already in use. Choose another.
 486 .fi
 487 .in -2
 488 .sp
 489 
 490 .sp
 491 .LP
 492 The following indicates that the \fIgroup\fR specified with the \fB-g\fR option
 493 is already in use:
 494 .sp
 495 .in +2
 496 .nf
 497 UX: useradd: ERROR: group \fIgroup\fR does not exist. Choose another.
 498 .fi
 499 .in -2
 500 .sp
 501 
 502 .sp
 503 .LP
 504 The following indicates that the \fIuid\fR specified with the \fB-u\fR option
 505 is in the range of reserved \fBUID\fRs (from \fB0\fR-\fB99\fR):
 506 .sp
 507 .in +2
 508 .nf
 509 UX: useradd: WARNING: uid \fIuid\fR is reserved.
 510 .fi
 511 .in -2
 512 .sp
 513 
 514 .sp
 515 .LP
 516 The following indicates that the \fIuid\fR specified with the \fB-u\fR option
 517 exceeds \fBMAXUID\fR as defined in \fB<sys/param.h>\fR:
 518 .sp
 519 .in +2
 520 .nf
 521 UX: useradd: ERROR: uid \fIuid\fR is too big. Choose another.
 522 .fi
 523 .in -2
 524 .sp
 525 
 526 .sp
 527 .LP
 528 The following indicates that the \fB/etc/passwd\fR or \fB/etc/shadow\fR files
 529 do not exist:
 530 .sp
 531 .in +2
 532 .nf
 533 UX: useradd: ERROR: Cannot update system files - login cannot be created.
 534 .fi
 535 .in -2
 536 .sp
 537 
 538 .SH NOTES
 539 .sp
 540 .LP
 541 The \fBuseradd\fR utility adds definitions to only the local \fB/etc/group\fR,
 542 \fBetc/passwd\fR, \fB/etc/passwd\fR, \fB/etc/shadow\fR, \fB/etc/project\fR, and
 543 \fB/etc/user_attr\fR files. If a network name service such as \fBNIS\fR or
 544 \fBNIS+\fR is being used to supplement the local \fB/etc/passwd\fR file with
 545 additional entries, \fBuseradd\fR cannot change information supplied by the
 546 network name service. However \fBuseradd\fR will verify the uniqueness of the
 547 user name (or role) and user id and the existence of any group names specified
 548 against the external name service.