1 .\"
   2 .\" The contents of this file are subject to the terms of the
   3 .\" Common Development and Distribution License (the "License").
   4 .\" You may not use this file except in compliance with the License.
   5 .\"
   6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   7 .\" or http://www.opensolaris.org/os/licensing.
   8 .\" See the License for the specific language governing permissions
   9 .\" and limitations under the License.
  10 .\"
  11 .\" When distributing Covered Code, include this CDDL HEADER in each
  12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  13 .\" If applicable, add the following below this CDDL HEADER, with the
  14 .\" fields enclosed by brackets "[]" replaced with your own identifying
  15 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  16 .\"
  17 .\"
  18 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
  19 .\" Copyright 2017 Nexenta Systems, Inc.
  20 .\"
  21 .Dd November 18, 2017
  22 .Dt SMBADM 1M
  23 .Os
  24 .Sh NAME
  25 .Nm smbadm
  26 .Nd configure and manage SMB local groups and users, and manage domain
  27 membership
  28 .Sh SYNOPSIS
  29 .Nm
  30 .Cm create
  31 .Op Fl d Ar description
  32 .Ar group
  33 .Nm
  34 .Cm delete
  35 .Ar group
  36 .Nm
  37 .Cm rename
  38 .Ar group new-group
  39 .Nm
  40 .Cm show
  41 .Op Fl mp
  42 .Op Ar group
  43 .Nm
  44 .Cm get
  45 .Oo Fl p Ar property Oc Ns ...
  46 .Ar group
  47 .Nm
  48 .Cm set
  49 .Fl p Ar property Ns = Ns Ar value
  50 .Oo Fl p Ar property Ns = Ns Ar value Oc Ns ...
  51 .Ar group
  52 .Nm
  53 .Cm add-member
  54 .Fl m Ar member Oo Fl m Ar member Oc Ns ...
  55 .Ar group
  56 .Nm
  57 .Cm remove-member
  58 .Fl m Ar member Oo Fl m Ar member Oc Ns ...
  59 .Ar group
  60 .Nm
  61 .Cm delete-user
  62 .Ar username
  63 .Nm
  64 .Cm disable-user
  65 .Ar username
  66 .Nm
  67 .Cm enable-user
  68 .Ar username
  69 .Nm
  70 .Cm join
  71 .Op Fl y
  72 .Fl u Ar username
  73 .Ar domain
  74 .Nm
  75 .Cm join
  76 .Op Fl y
  77 .Fl w Ar workgroup
  78 .Nm
  79 .Cm list
  80 .Nm
  81 .Cm lookup
  82 .Ar account-name Oo Ar account-name Oc Ns ...
  83 .Sh DESCRIPTION
  84 The
  85 .Nm
  86 command is used to configure SMB local groups and users, and to manage domain
  87 membership.
  88 You can also use the
  89 .Nm
  90 command to enable or disable SMB password generation for individual local users.
  91 .Pp
  92 SMB local groups can be used when Windows accounts must be members of some local
  93 groups and when Windows style privileges must be granted.
  94 System local groups cannot provide these functions.
  95 .Pp
  96 There are two types of local groups: user defined and built-in.
  97 Built-in local groups are predefined local groups to support common
  98 administration tasks.
  99 .Pp
 100 In order to provide proper identity mapping between SMB local groups and
 101 system groups, a SMB local group must have a corresponding system group.
 102 This requirement has two consequences: first, the group name must conform to the
 103 intersection of the Windows and system group name rules.
 104 Thus, a SMB local group name can be up to eight (8) characters long and contain
 105 only lowercase characters and numbers.
 106 Second, a system local group has to be created before a SMB local group can
 107 be created.
 108 .Pp
 109 Built-in groups are standard Windows groups and are predefined by the SMB
 110 service.
 111 The built-in groups cannot be added, removed, or renamed, and these groups do
 112 not follow the SMB local group naming conventions.
 113 .Pp
 114 When the SMB server is started, the following built-in groups are available:
 115 .Bl -tag -width "Backup Operators"
 116 .It Sy Administrators
 117 Group members can administer the system.
 118 .It Sy Backup Operators
 119 Group members can bypass file access controls to back up and restore files.
 120 .It Sy Power Users
 121 Group members can share directories.
 122 .El
 123 .Pp
 124 System local users must have an SMB password for authentication and to gain
 125 access to SMB resources.
 126 This password is created by using the
 127 .Xr passwd 1
 128 command when the
 129 .Sy pam_smb_password
 130 module is added to the system's PAM configuration.
 131 See the
 132 .Xr pam_smb_passwd 5
 133 man page.
 134 .Pp
 135 The
 136 .Cm disable-user
 137 and
 138 .Cm enable-user
 139 subcommands control SMB password-generation for a specified local user.
 140 When disabled, the user is prevented from connecting to the SMB service.
 141 By default, SMB password-generation is enabled for all local users.
 142 .Pp
 143 To reenable a disabled user, you must use the
 144 .Cm enable-user
 145 subcommand and then reset the user's password by using the
 146 .Nm passwd
 147 command.
 148 The
 149 .Pa pam_smb_passwd.so.1
 150 module must be added to the system's PAM configuration to generate an SMB
 151 password.
 152 .Ss Escaping Backslash Character
 153 For the
 154 .Cm add-member ,
 155 .Cm remove-member ,
 156 and
 157 .Cm join
 158 .Po with
 159 .Fl u
 160 .Pc
 161 subcommands, the backslash character
 162 .Pq Qq \e
 163 is a valid separator between member or user names and domain names.
 164 The backslash character is a shell special character and must be quoted.
 165 For example, you might escape the backslash character with another backslash
 166 character:
 167 .Ar domain Ns \e\e Ns Ar username .
 168 For more information about handling shell special characters, see the man page
 169 for your shell.
 170 .Sh OPERANDS
 171 The
 172 .Nm
 173 command uses the following operands:
 174 .Bl -tag -width "username"
 175 .It Ar domain
 176 Specifies the name of an existing Windows domain to join.
 177 .It Ar group
 178 Specifies the name of the SMB local group.
 179 .It Ar username
 180 Specifies the name of a system local user.
 181 .El
 182 .Sh SUBCOMMANDS
 183 The
 184 .Nm
 185 command includes these subcommands:
 186 .Bl -tag -width Ds
 187 .It Xo
 188 .Cm create
 189 .Op Fl d Ar description
 190 .Ar group
 191 .Xc
 192 Creates a SMB local group with the specified name.
 193 You can optionally specify a description of the group by using the
 194 .Fl d
 195 option.
 196 .It Xo
 197 .Cm delete
 198 .Ar group
 199 .Xc
 200 Deletes the specified SMB local group.
 201 The built-in groups cannot be deleted.
 202 .It Xo
 203 .Cm rename
 204 .Ar group new-group
 205 .Xc
 206 Renames the specified SMB local group.
 207 The group must already exist.
 208 The built-in groups cannot be renamed.
 209 .It Xo
 210 .Cm show
 211 .Op Fl mp
 212 .Op Ar group
 213 .Xc
 214 Shows information about the specified SMB local group or groups.
 215 If no group is specified, information is shown for all groups.
 216 If the
 217 .Fl m
 218 option is specified, the group members are also shown.
 219 If the
 220 .Fl p
 221 option is specified, the group privileges are also shown.
 222 .It Xo
 223 .Cm get
 224 .Oo Fl p Ar property Ns = Ns Ar value Oc Ns ...
 225 .Ar group
 226 .Xc
 227 Retrieves property values for the specified group.
 228 If no property is specified, all property values are shown.
 229 .It Xo
 230 .Cm set
 231 .Fl p Ar property Ns = Ns Ar value
 232 .Oo Fl p Ar property Ns = Ns Ar value Oc Ns ...
 233 .Ar group
 234 .Xc
 235 Sets configuration properties for a SMB local group.
 236 The description and the privileges for the built-in groups cannot be changed.
 237 .Pp
 238 The
 239 .Fl p Ar property Ns = Ns Ar value
 240 option specifies the list of properties to be set on the specified group.
 241 .Pp
 242 The group-related properties are as follows:
 243 .Bl -tag -width Ds
 244 .It Cm backup Ns = Ns Cm on Ns | Ns Cm off
 245 Specifies whether members of the SMB local group can bypass file access controls
 246 to back up file system objects.
 247 .It Cm description Ns = Ns Ar description-text
 248 Specifies a text description for the SMB local group.
 249 .It Cm restore Ns = Ns Cm on Ns | Ns Cm off
 250 Specifies whether members of the SMB local group can bypass file access controls
 251 to restore file system objects.
 252 .It Cm take-ownership Ns = Ns Cm on Ns | Ns Cm off
 253 Specifies whether members of the SMB local group can take ownership of file
 254 system objects.
 255 .El
 256 .It Xo
 257 .Cm add-member
 258 .Fl m Ar member Oo Fl m Ar member Oc Ns ...
 259 .Ar group
 260 .Xc
 261 Adds the specified member to the specified SMB local group.
 262 The
 263 .Fl m Ar member
 264 option specifies the name of a SMB local group member.
 265 The member name must include an existing user name and an optional domain name.
 266 .Pp
 267 Specify the member name in either of the following formats:
 268 .Bd -literal -offset indent
 269 [domain\e]username
 270 [domain/]username
 271 .Ed
 272 .Pp
 273 For example, a valid member name might be
 274 .Sy sales\eterry
 275 or
 276 .Sy sales/terry ,
 277 where
 278 .Sy sales
 279 is the Windows domain name and
 280 .Sy terry
 281 is the name of a user in the
 282 .Sy sales
 283 domain.
 284 .It Xo
 285 .Cm remove-member
 286 .Fl m Ar member Oo Fl m Ar member Oc Ns ...
 287 .Ar group
 288 .Xc
 289 Removes the specified member from the specified SMB local group.
 290 The
 291 .Fl m Ar member
 292 option specifies the name of a SMB local group member.
 293 The member name must include an existing user name and an optional domain name.
 294 .Pp
 295 Specify the member name in either of the following formats:
 296 .Bd -literal -offset indent
 297 [domain\e]username
 298 [domain/]username
 299 .Ed
 300 .Pp
 301 For example, a valid member name might be
 302 .Sy sales\eterry
 303 or
 304 .Sy sales/terry ,
 305 where
 306 .Sy sales
 307 is the Windows domain name and
 308 .Sy terry
 309 is the name of a user in the
 310 .Sy sales
 311 domain.
 312 .It Xo
 313 .Cm delete-user
 314 .Ar username
 315 .Xc
 316 Deletes SMB password for the specified local user effectively preventing the
 317 access by means of the SMB service.
 318 Use
 319 .Nm passwd
 320 command to create the SMB password and re-enable access.
 321 .It Xo
 322 .Cm disable-user
 323 .Ar username
 324 .Xc
 325 Disables SMB password-generation capabilities for the specified local user
 326 effectively preventing access by means of the SMB service.
 327 When a local user account is disabled, you cannot use the
 328 .Nm passwd
 329 command to modify the user's SMB password until the user account is re-enabled.
 330 .It Xo
 331 .Cm enable-user
 332 .Ar username
 333 .Xc
 334 Enables SMB password-generation capabilities for the specified local user and
 335 re-enables access.
 336 After the password-generation capabilities are re-enabled, use the
 337 .Nm passwd
 338 command to generate the SMB password for the local user.
 339 .Pp
 340 The
 341 .Nm passwd
 342 command manages both the system password and SMB password for this user if the
 343 .Pa pam_smb_passwd
 344 module has been added to the system's PAM configuration.
 345 .It Xo
 346 .Cm join
 347 .Op Fl y
 348 .Fl u Ar username
 349 .Ar domain
 350 .Xc
 351 Joins a Windows domain.
 352 .Pp
 353 An authenticated user account is required to join a domain, so you must specify
 354 the Windows administrative user name with the
 355 .Fl u
 356 option.
 357 If the password is not specified on the command line, the user is prompted for
 358 it.
 359 This user should be the domain administrator or any user who has administrative
 360 privileges for the target domain.
 361 .Pp
 362 .Ar username
 363 and
 364 .Ar domain
 365 can be entered in any of the following formats:
 366 .Bd -literal -offset indent
 367 username[+password] domain
 368 domain\eusername[+password]
 369 domain/username[+password]
 370 username@domain
 371 .Ed
 372 .Pp
 373 \&...where
 374 .Ar domain
 375 can be the NetBIOS or DNS domain name.
 376 .Pp
 377 If a machine trust account for the system already exists on a domain controller,
 378 any authenticated user account can be used when joining the domain.
 379 However, if the machine trust account does
 380 .Em not
 381 already exist, an account that has administrative privileges on the domain is
 382 required to join the domain.
 383 Specifying
 384 .Fl y
 385 will bypass the SMB service restart prompt.
 386 .It Xo
 387 .Cm join
 388 .Op Fl y
 389 .Fl w Ar workgroup
 390 .Xc
 391 Joins a Windows workgroup.
 392 .Pp
 393 The default mode for the SMB service is workgroup mode, which uses the default
 394 workgroup name,
 395 .Qq WORKGROUP .
 396 .Pp
 397 The
 398 .Fl w Ar workgroup
 399 option specifies the name of the workgroup to join when using the
 400 .Cm join
 401 subcommand.
 402 Specifying
 403 .Fl y
 404 will bypass the SMB service restart prompt.
 405 .It Cm list
 406 Shows information about the current workgroup or domain.
 407 The information typically includes the workgroup name or the primary domain
 408 name.
 409 When in domain mode, the information includes domain controller names and
 410 trusted domain names.
 411 .Pp
 412 Each entry in the ouput is identified by one of the following tags:
 413 .Bl -tag -width "[*]"
 414 .It Sy [*]
 415 Primary domain
 416 .It Sy [.]
 417 Local domain
 418 .It Sy [-]
 419 Other domains
 420 .It Sy [+]
 421 Selected domain controller
 422 .El
 423 .It Xo
 424 .Cm lookup
 425 .Ar account-name Oo Ar account-name Oc Ns ...
 426 .Xc
 427 Lookup the SID for the given
 428 .Ar account-name ,
 429 or lookup the
 430 .Ar account-name
 431 for the given SID.
 432 This subcommand is primarily for diagnostic use, to confirm whether the server
 433 can lookup domain accounts and/or SIDs.
 434 .El
 435 .Sh EXIT STATUS
 436 .Ex -std
 437 .Sh INTERFACE STABILITY
 438 Utility name and options are
 439 .Sy Uncommitted .
 440 Utility output format is
 441 .Sy Not-An-Interface .
 442 .Sh SEE ALSO
 443 .Xr passwd 1 ,
 444 .Xr groupadd 1M ,
 445 .Xr idmap 1M ,
 446 .Xr idmapd 1M ,
 447 .Xr kclient 1M ,
 448 .Xr share 1M ,
 449 .Xr sharectl 1M ,
 450 .Xr sharemgr 1M ,
 451 .Xr smbd 1M ,
 452 .Xr smbstat 1M ,
 453 .Xr smb 4 ,
 454 .Xr smbautohome 4 ,
 455 .Xr attributes 5 ,
 456 .Xr pam_smb_passwd 5 ,
 457 .Xr smf 5