usr/src/man/man1m/roleadd.1m

   1 '\" te
   2 .\" Copyright (c) 2018 Peter Tribble.
   3 .\"  Copyright 1989 AT&T Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved.
   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 ROLEADD 1M "Jan 7, 2018"
   8 .SH NAME
   9 roleadd \- administer a new role account on the system
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBroleadd\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-z|-Z\fR] [\fB-k\fR \fIskel_dir\fR]] [\fB-p\fR \fIprojname\fR]
  17      [\fB-P\fR \fIprofile\fR[,\fIprofile\fR]...] [\fB-s\fR \fIshell\fR] [\fB-u\fR \fIuid\fR [\fB-o\fR]] \fIrole\fR
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBroleadd\fR \fB-D\fR [\fB-A\fR \fIauthorization\fR[,\fIauthorization\fR]...]
  23      [\fB-b\fR \fIbase_dir\fR] [\fB-e\fR \fIexpire\fR] [\fB-f\fR \fIinactive\fR] [\fB-g\fR \fIgroup\fR]
  24      [\fB-k\fR \fIskel_dir\fR] [\fB-K\fR \fIkey=value\fR] [\fB-p\fR \fIprojname\fR]
  25      [\fB-P\fR \fIprofile\fR[,\fIprofile\fR]...] [\fB-s\fR \fIshell\fR]
  26 .fi
  27
  28 .SH DESCRIPTION
  29 .LP
  30 \fBroleadd\fR adds a role entry to the \fB/etc/passwd\fR and \fB/etc/shadow\fR
  31 and \fB/etc/user_attr\fR files. The \fB-A\fR and \fB-P\fR options respectively
  32 assign authorizations and profiles to the role. The \fB-p\fR option associates
  33 a project with the role. The \fB-K\fR option adds a \fIkey=value\fR pair to
  34 \fB/etc/user_attr\fR for the role. Multiple \fIkey=value\fR pairs can be added
  35 with multiple \fB-K\fR options.
  36 .sp
  37 .LP
  38 \fBroleadd\fR also creates supplementary group memberships for the role
  39 (\fB-G\fR option) and creates the home directory (\fB-m\fR option) for the role
  40 if requested. The new role account remains locked until the \fBpasswd\fR(1)
  41 command is executed.
  42 .sp
  43 .LP
  44 Specifying \fBroleadd\fR \fB-D\fR with the \fB-A\fR, \fB-b\fR, \fB-e\fR,
  45 \fB-f\fR, \fB-g\fR, \fB-k\fR, \fB-K\fR, \fB-p\fR, \fB-P\fR, or
  46 \fB-s\fR option (or any combination of these options) sets the default values
  47 for the respective fields. See the \fB-D\fR option. Subsequent
  48 \fBroleadd\fR commands without the \fB-D\fR option use these arguments.
  49 .sp
  50 .LP
  51 The system file entries created with this command have a limit of 512
  52 characters per line. Specifying long arguments to several options can exceed
  53 this limit.
  54 .sp
  55 .LP
  56 \fBroleadd\fR requires that usernames be in the format described in
  57 \fBpasswd\fR(4). A warning message is displayed if these restrictions are not
  58 met. See \fBpasswd\fR(4) for the requirements for usernames.
  59 .LP
  60 To change the action of \fBroleadd\fR when the traditional login name
  61 length limit of eight characters is exceeded, edit the file
  62 \fB/etc/default/useradd\fR by removing the \fB#\fR (pound sign) before the
  63 appropriate \fBEXCEED_TRAD=\fR entry, and adding it before the others.
  64 .SH OPTIONS
  65 .LP
  66 The following options are supported:
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fB-A\fR \fIauthorization\fR\fR
  71 .ad
  72 .sp .6
  73 .RS 4n
  74 One or more comma separated authorizations defined in \fBauth_attr\fR(4). Only
  75 a user or role who has \fBgrant\fR rights to the authorization can assign it to
  76 a role.
  77 .RE
  78
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fB-b\fR \fIbase_dir\fR\fR
  83 .ad
  84 .sp .6
  85 .RS 4n
  86 The base directory for new role home directories (see the \fB-d\fR option
  87 below). The directory named by \fIbase_dir\fR must already exist and be an
  88 absolute path.
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fB-c\fR \fIcomment\fR\fR
  95 .ad
  96 .sp .6
  97 .RS 4n
  98 A text string. It is generally a short description of the role. This
  99 information is stored in the role'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 role. If not supplied, 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 role 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-A\fR, \fB-b\fR, \fB-e\fR,
 124 \fB-f\fR, \fB-g\fR, \fB-P\fR, \fB-p\fR, or \fB-K\fR, options, the \fB-D\fR
 125 option sets the default values for the specified fields. The default values
 126 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/pfsh\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\fR (pairs defined in \fBuser_attr\fR(4))
 231 .ad
 232 .sp .6
 233 .RS 4n
 234 not present
 235 .RE
 236
 237 .RE
 238
 239 .sp
 240 .ne 2
 241 .na
 242 \fB\fB-e\fR \fIexpire\fR\fR
 243 .ad
 244 .sp .6
 245 .RS 4n
 246 Specify the expiration date for a role. After this date, no user is able to
 247 access this role. The expire option argument is a date entered using one of
 248 the date formats included in the template file \fB/etc/datemsk\fR. See
 249 \fBgetdate\fR(3C).
 250 .sp
 251 If the date format that you choose includes spaces, it must be quoted. For
 252 example, you can enter \fB10/6/90\fR or \fBOctober 6, 1990\fR. A null value
 253 (\fB" "\fR) defeats the status of the expired date. This option is useful for
 254 creating temporary roles.
 255 .RE
 256
 257 .sp
 258 .ne 2
 259 .na
 260 \fB\fB-f\fR \fIinactive\fR\fR
 261 .ad
 262 .sp .6
 263 .RS 4n
 264 The maximum number of days allowed between uses of a role ID before that
 265 \fBID\fR is declared invalid. Normal values are positive integers. A value of
 266 \fB0\fR defeats the status.
 267 .RE
 268
 269 .sp
 270 .ne 2
 271 .na
 272 \fB\fB-g\fR \fIgroup\fR\fR
 273 .ad
 274 .sp .6
 275 .RS 4n
 276 An existing group's integer \fBID\fR or character-string name. Without the
 277 \fB-D\fR option, it defines the new role's primary group membership and
 278 defaults to the default group. You can reset this default value by invoking
 279 \fBroleadd\fR \fB-D\fR \fB-g\fR \fIgroup\fR. GIDs 0-99 are reserved for
 280 allocation by the Operating System.
 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 One or more comma-separated existing groups, specified by integer \fBID\fR or
 291 character-string name. It defines the new role's supplementary group
 292 membership. Any duplicate groups between the \fB-g\fR and \fB-G\fR options are
 293 ignored. No more than \fBNGROUPS_MAX\fR groups can be specified. GIDs 0-99 are
 294 reserved for allocation by the Operating System.
 295 .RE
 296
 297 .sp
 298 .ne 2
 299 .na
 300 \fB\fB-k\fR \fIskel_dir\fR\fR
 301 .ad
 302 .sp .6
 303 .RS 4n
 304 A directory that contains skeleton information (such as \fB\&.profile\fR) that
 305 can be copied into a new role's home directory. This directory must already
 306 exist. The system provides the \fB/etc/skel\fR directory that can be used for
 307 this purpose.
 308 .RE
 309
 310 .sp
 311 .ne 2
 312 .na
 313 \fB\fB-K\fR \fIkey=value\fR\fR
 314 .ad
 315 .sp .6
 316 .RS 4n
 317 A \fIkey=value\fR pair to add to the role's attributes. Multiple \fB-K\fR
 318 options may be used to add multiple \fIkey=value\fR pairs. The generic \fB-K\fR
 319 option with the appropriate key may be used instead of the specific implied key
 320 options (\fB-A\fR, \fB-p\fR, \fB-P\fR). See \fBuser_attr\fR(4) for a
 321 list of valid \fIkey=value\fR pairs. The "type" key is not a valid key for this
 322 option. Keys cannot be repeated.
 323 .RE
 324
 325 .sp
 326 .ne 2
 327 .na
 328 \fB\fB-m\fR\fR [\fB-z|-Z\fR]
 329 .ad
 330 .sp .6
 331 .RS 4n
 332 Create the new role's home directory if it does not already exist. If the
 333 directory already exists, it must have read, write, and execute permissions by
 334 \fIgroup\fR, where \fIgroup\fR is the role's primary group.
 335 .sp
 336 If the parent directory of the role's home directory is located on a separate
 337 \fBZFS\fR file system and the \fB/etc/default/useradd\fR file contains the
 338 parameter \fBMANAGE_ZFS\fR set to the value \fBYES\fR, a new \fBZFS\fR
 339 file system will be created for the role.
 340 .sp
 341 If the \fB-z\fR option is specified, \fBroleadd\fR will always try to create
 342 a new file system for the home directory.
 343 .sp
 344 If the \fB-Z\fR option is specified, a new file system will never be created.
 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 \fIprojname\fR\fR
 361 .ad
 362 .sp .6
 363 .RS 4n
 364 Name of the project with which the added role is associated. See the
 365 \fIprojname\fR field as defined in \fBproject\fR(4).
 366 .RE
 367
 368 .sp
 369 .ne 2
 370 .na
 371 \fB\fB-P\fR \fIprofile\fR\fR
 372 .ad
 373 .sp .6
 374 .RS 4n
 375 One or more comma-separated execution profiles defined in \fBprof_attr\fR(4).
 376 .RE
 377
 378 .sp
 379 .ne 2
 380 .na
 381 \fB\fB-s\fR \fIshell\fR\fR
 382 .ad
 383 .sp .6
 384 .RS 4n
 385 Full pathname of the program used as the role's shell on login. It defaults to
 386 an empty field causing the system to use \fB/bin/pfsh\fR as the default. The
 387 value of \fIshell\fR must be a valid executable file.
 388 .RE
 389
 390 .sp
 391 .ne 2
 392 .na
 393 \fB\fB-u\fR \fIuid\fR\fR
 394 .ad
 395 .sp .6
 396 .RS 4n
 397 The \fBUID\fR of the new role. This \fBUID\fR must be a non-negative decimal
 398 integer below \fBMAXUID\fR as defined in \fB<sys/param.h>\fR\&. The \fBUID\fR
 399 defaults to the next available (unique) number above the highest number
 400 currently assigned. For example, if \fBUID\fRs 100, 105, and 200 are assigned,
 401 the next default \fBUID\fR number will be 201. \fBUID\fRs \fB0\fR-\fB99\fR are
 402 reserved for allocation by the Operating System.
 403 .RE
 404
 405 .SH FILES
 406 .LP
 407 \fB/etc/default/useradd\fR
 408 .sp
 409 .LP
 410 \fB/etc/datemsk\fR
 411 .sp
 412 .LP
 413 \fB/etc/passwd\fR
 414 .sp
 415 .LP
 416 \fB/etc/shadow\fR
 417 .sp
 418 .LP
 419 \fB/etc/group\fR
 420 .sp
 421 .LP
 422 \fB/etc/skel\fR
 423 .sp
 424 .LP
 425 \fB/usr/include/limits.h\fR
 426 .sp
 427 .LP
 428 \fB/etc/user_attr\fR
 429 .SH ATTRIBUTES
 430 .LP
 431 See \fBattributes\fR(5) for descriptions of the following attributes:
 432 .sp
 433
 434 .sp
 435 .TS
 436 box;
 437 c | c
 438 l | l .
 439 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 440 _
 441 Interface Stability     Evolving
 442 .TE
 443
 444 .SH SEE ALSO
 445 .LP
 446 \fBpasswd\fR(1), \fBpfsh\fR(1), \fBprofiles\fR(1), \fBroles\fR(1),
 447 \fBgroupadd\fR(1M), \fBgroupdel\fR(1M), \fBgroupmod\fR(1M),
 448 \fBgrpck\fR(1M), \fBlogins\fR(1M), \fBpwck\fR(1M), \fBuserdel\fR(1M),
 449 \fBusermod\fR(1M), \fBzfs\fR(1M), \fBgetdate\fR(3C), \fBauth_attr\fR(4),
 450 \fBpasswd\fR(4), \fBprof_attr\fR(4), \fBuser_attr\fR(4), \fBattributes\fR(5)
 451 .SH DIAGNOSTICS
 452 .LP
 453 In case of an error, \fBroleadd\fR prints an error message and exits with a
 454 non-zero status.
 455 .sp
 456 .LP
 457 The following indicates that \fBlogin\fR specified is already in use:
 458 .sp
 459 .in +2
 460 .nf
 461 UX: roleadd: ERROR: login is already in use. Choose another.
 462 .fi
 463 .in -2
 464 .sp
 465
 466 .sp
 467 .LP
 468 The following indicates that the \fIuid\fR specified with the \fB-u\fR option
 469 is not unique:
 470 .sp
 471 .in +2
 472 .nf
 473 UX: roleadd: ERROR: uid \fIuid\fR is already in use. Choose another.
 474 .fi
 475 .in -2
 476 .sp
 477
 478 .sp
 479 .LP
 480 The following indicates that the \fIgroup\fR specified with the \fB-g\fR option
 481 is already in use:
 482 .sp
 483 .in +2
 484 .nf
 485 UX: roleadd: ERROR: group \fIgroup\fR does not exist. Choose another.
 486 .fi
 487 .in -2
 488 .sp
 489
 490 .sp
 491 .LP
 492 The following indicates that the \fIuid\fR specified with the \fB-u\fR option
 493 is in the range of reserved \fBUID\fRs (from \fB0\fR-\fB99\fR):
 494 .sp
 495 .in +2
 496 .nf
 497 UX: roleadd: WARNING: uid \fIuid\fR is reserved.
 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 exceeds \fBMAXUID\fR as defined in \fB<sys/param.h>\fR:
 506 .sp
 507 .in +2
 508 .nf
 509 UX: roleadd: ERROR: uid \fIuid\fR is too big. Choose another.
 510 .fi
 511 .in -2
 512 .sp
 513
 514 .sp
 515 .LP
 516 The following indicates that the \fB/etc/passwd\fR or \fB/etc/shadow\fR files
 517 do not exist:
 518 .sp
 519 .in +2
 520 .nf
 521 UX: roleadd: ERROR: Cannot update system files - login cannot be created.
 522 .fi
 523 .in -2
 524 .sp
 525
 526 .SH NOTES
 527 .LP
 528 If a network nameservice is being used to supplement the local
 529 \fB/etc/passwd\fR file with additional entries, \fBroleadd\fR cannot change
 530 information supplied by the network nameservice.