illumos SMB Administration Guide

https://illumos.org/books/smb-admin/
Admin
The illumos SMB Administration Guide is a comprehensive resource for configuring and integrating the...
Tokens:23,280
Snippets:236
Trust Score:9.5
Update:7 months ago
Show doc for...
Tokens:
Raw
### Illumos SMB Autohome Example Entries

Source: https://illumos.org/books/smb-admin/smboverview.html

Example entries for the `/etc/smbautohome` file, demonstrating how to map users to home directories using naming services and specific user paths. These entries define rules for automatic home directory sharing when an SMB client connects.

```shell
+nsswitch	dn=ads,dn=sun,dn=com,ou=users
jane	/home/?/&	dn=ads,dn=sun,dn=com,ou=users
```

--------------------------------

### Diagnose idmap Mappings

Source: https://illumos.org/books/smb-admin/troubleshooting.html

Commands to inspect and troubleshoot idmap configurations using the dump and show utilities with verbose output.

```shell
# idmap dump -v
# idmap show -v
```

--------------------------------

### Illumos SMB Autohome Key Substitution Examples

Source: https://illumos.org/books/smb-admin/smboverview.html

Illustrates how special characters '&' and '?' are used for key substitution within autohome map entries. '&' expands to the key itself, while '?' expands to the first character of the key.

```shell
jane /home/&
jane /home/??/&
```

--------------------------------

### Get Current SMB Configuration

Source: https://illumos.org/books/smb-admin/smbclienttasks.html

This command retrieves the current SMB configuration settings, including any configured default domains. The output shows the active configuration parameters for the SMB service.

```bash
# `sharectl get smbfs`
[default]
domain=AAA
```

--------------------------------

### Configure User-Specific SMB Domain

Source: https://illumos.org/books/smb-admin/smbclienttasks.html

This example demonstrates how a user can configure a specific SMB domain by creating or modifying the `~/.nsmbrc` file. The system prioritizes domains from SMF, then user-specific `.nsmbrc` files, and finally system defaults.

```bash
$ `cat ~/.nsmbrc`
[default]
domain=MYDOMAIN
$ `ls -l ~/.nsmbrc`
-rw-r--r--   1 terry  staff         26 Feb 13 10:15 /home/terry/.nsmbrc
```

--------------------------------

### LDIF User Mapping Update Example

Source: https://illumos.org/books/smb-admin/modifyadschema.html

An example LDIF file used to map Windows user objects to their corresponding UNIX usernames.

```ldif
dn: CN=Terry Walters,CN=Users,DC=example,DC=com
changetype: modify
add: unixUserName
unixUserName: tmw

dn: CN=Cal Jamieson,CN=Users,DC=example,DC=com
changetype: modify
add: unixUserName
unixUserName: crj

dn: CN=Dana Bloom,CN=Users,DC=example,DC=com
changetype: modify
add: unixUserName
unixUserName: dab
```

--------------------------------

### List and Restore idmap Mappings

Source: https://illumos.org/books/smb-admin/troubleshooting.html

Methods for listing current mappings to a file and restoring them by executing the resulting file as a shell script.

```shell
# idmap list > output-file
# sh ./output-file
```

--------------------------------

### Add Bidirectional Rule-Based Mappings with `idmap`

Source: https://illumos.org/books/smb-admin/idmappingtasks.html

Creates bidirectional rule-based mappings using the `idmap add` command. These mappings associate Windows users and groups with corresponding Unix users and groups by name. The examples show mapping all users and groups from a Windows domain to Unix users and groups with the same names.

```shell
# `idmap add 'winuser:*@example.com' 'unixuser:*'`
# `idmap add 'wingroup:*@example.com' 'unixgroup:*'`
```

--------------------------------

### Configure ZFS Case-Sensitivity for SMB

Source: https://illumos.org/books/smb-admin/troubleshooting.html

Creates a ZFS file system with mixed-case sensitivity to ensure compatibility with SMB client expectations for case-insensitive file operations.

```shell
zfs create -o casesensitivity=mixed fsname
```

--------------------------------

### LDIF Schema Definition Example

Source: https://illumos.org/books/smb-admin/modifyadschema.html

An example LDIF file content used to define new attributes and an auxiliary class for storing UNIX name information in the AD schema.

```ldif
dn: CN=unixUserName, CN=Schema, CN=Configuration, DC=example, DC=com
changetype: add
attributeID: 1.3.6.1.4.1.42.2.27.5.1.60
attributeSyntax: 2.5.5.3
isSingleValued: TRUE
searchFlags: 1
lDAPDisplayName: unixUserName
adminDescription: This attribute contains the object's UNIX username
objectClass: attributeSchema
oMSyntax: 27

dn: CN=unixGroupName, CN=Schema, CN=Configuration, DC=example, DC=com
changetype: add
attributeID: 1.3.6.1.4.1.42.2.27.5.1.61
attributeSyntax: 2.5.5.3
isSingleValued: TRUE
searchFlags: 1
lDAPDisplayName: unixGroupName
adminDescription: This attribute contains the object's UNIX groupname
objectClass: attributeSchema
oMSyntax: 27

dn:
changetype: modify
add: schemaUpdateNow
schemaUpdateNow: 1
-

dn: CN=unixNameInfo, CN=Schema, CN=Configuration, DC=example, DC=com
changetype: add
governsID: 1.3.6.1.4.1.42.2.27.5.2.15
lDAPDisplayName: unixNameInfo
adminDescription: Auxiliary class to store UNIX name info in AD
mayContain: unixUserName
mayContain: unixGroupName
objectClass: classSchema
objectClassCategory: 3
subClassOf: top
```

--------------------------------

### Get idmap Name Mapping Information (Shell)

Source: https://illumos.org/books/smb-admin/idmappingtasks.html

Retrieves the directory-based name mapping information for a specified user. This command queries the `idmap` service for mapping details.

```shell
# `idmap get-namemap `_username_``
```

--------------------------------

### Get Group Name Mapping Information

Source: https://illumos.org/books/smb-admin/idmappingtasks.html

Retrieves and displays the directory-based name mapping information for a specified group. This command helps in viewing current mappings.

```shell
# idmap get-namemap <group-name>
```

--------------------------------

### Export and Import idmap Mappings

Source: https://illumos.org/books/smb-admin/troubleshooting.html

Commands to back up current idmap rule-based mappings to a file and restore them using the import utility. These operations require specifying the file path and format.

```shell
# idmap export -f output-file format
# idmap import -f input-file format
```

--------------------------------

### Troubleshoot Domain Join Authentication Errors

Source: https://illumos.org/books/smb-admin/troubleshooting.html

Displays common error messages encountered during the domain join process, specifically regarding incorrect passwords or insufficient administrative privileges.

```shell
# smbadm join -y -u administrator@westsales.example.com
# smbd: failed joining domain-name (UNSUCCESSFUL)
```

--------------------------------

### Troubleshoot Domain Join Clock Skew

Source: https://illumos.org/books/smb-admin/troubleshooting.html

Demonstrates the error output when system clocks are out of sync and provides the command to synchronize the illumos system time with a domain controller using ntpdate.

```shell
# smbadm join -y -u administrator@westsales.example.com
# ntpdate dc.westsales.example.com
```

--------------------------------

### Configure Directory-Based Mapping with `svccfg`

Source: https://illumos.org/books/smb-admin/idmappingtasks.html

Enables directory-based mapping on the illumos system using the `svccfg` command. This is often used with the `idmap` service to inform it about AD or LDAP attributes for user and group objects. The example shows setting the `idmap` strategy to `idmu`.

```shell
# `svccfg -s idmap setprop config/directory_based_mapping = astring: idmu`
```

--------------------------------

### List Mounted SMB Shares using `df`

Source: https://illumos.org/books/smb-admin/smbclienttasks.html

This command lists mounted SMB shares and their disk usage statistics by filtering the `df -k` command for file systems of type `smbfs`. It provides information on total size, used space, available space, and percentage used for each share.

```bash
$ `df -k -F smbfs`
//root@solarsystem/tmp      1871312   70864 1800448     4%    /mnt
//root@solarsystem/files    8067749    8017 7979055     1%    /files
```

--------------------------------

### List and Remove User Mappings with idmap list and idmap remove

Source: https://illumos.org/books/smb-admin/idmappingtasks.html

Demonstrates how to list existing user mappings using `idmap list` and then remove specific user mappings or all user mappings using `idmap remove`. Requires superuser privileges or specific RBAC authorizations.

```bash
# `idmap list`
# `idmap list | grep pat`
# `idmap remove `_username_``
```

```bash
# `idmap remove `_username1_` `_username2_``
# `idmap remove -a`
```

--------------------------------

### Show Verbose SID Mapping with idmap show -v

Source: https://illumos.org/books/smb-admin/idmappingtasks.html

Displays detailed information about a specific SID-to-UID mapping from the cache. It shows the source and method used for the mapping, useful for troubleshooting.

```bash
# `idmap show -v sid:S-1-5-21-2949573101-2750415176-3223191819-884217`
sid:S-1-5-21-2949573101-2750415176-3223191819-884217 -> uid:2175201213
Source: Cache
Method: Ephemeral
```

--------------------------------

### Reset idmap Service Database

Source: https://illumos.org/books/smb-admin/troubleshooting.html

Procedure to disable the idmap service and remove existing database files to perform a clean reset of the mapping configuration.

```shell
# svcadm disable idmap
# rm /var/idmap/idmap.db /var/run/idmap/idmap.db
```

--------------------------------

### List Mounted SMB Shares using `mount`

Source: https://illumos.org/books/smb-admin/smbclienttasks.html

This command lists all currently mounted SMB shares by filtering the output of the `mount -v` command for entries of type `smbfs`. It displays details such as the remote share path, local mount point, and mount options.

```bash
$ `mount -v | grep 'type smbfs'`
//root@solarsystem/tmp on /mnt type smbfs read/write/setuid/devices/dev=5080000
  on Tue Feb 12 11:40:18 2008
//root@solarsystem/files on /files type smbfs read/write/setuid/devices/dev=4800000
  on Mon Feb 11 22:17:56 2008
```

--------------------------------

### Configure Rule-Based Identity Mappings using idmap

Source: https://illumos.org/books/smb-admin/idmappingtasks.html

Demonstrates how to define bidirectional and unidirectional identity mappings between Windows users and Unix users. These rules allow the idmapd service to translate identities for consistent access control across environments.

```text
dana@example.com == danas

dana@example.com == danas
danasan@example.com => danas
```

--------------------------------

### Illumos SMB Autohome nsswitch Map

Source: https://illumos.org/books/smb-admin/smboverview.html

Shows the '+nsswitch' entry, which instructs the SMB service to obtain home directory information from a password database like local, NIS, or LDAP. It can also be used to publish shares in AD if an AD path is appended.

```shell
+nsswitch
```

--------------------------------

### Store Persistent SMB Password using `smbutil login`

Source: https://illumos.org/books/smb-admin/smbclienttasks.html

This command stores a persistent password for authenticating with an SMB server. It prompts for the user's password and stores it for future automatic authentication. This is useful when Kerberos is not configured.

```bash
$ `smbutil login `_user_``
Password:
```

```bash
$ `smbutil login terry@solarsystem`
Password:
```

--------------------------------

### Configure PAM for SMB Password Storage

Source: https://illumos.org/books/smb-admin/smbclienttasks.html

This configuration adds the `pam_smbfs_login.so.1` module to the PAM stack for the `login` service. This allows users to store persistent passwords for SMB authentication via the PAM system, typically used in environments without Active Directory or Kerberos.

```bash
login   auth optional           pam_smbfs_login.so.1
```

--------------------------------

### Set Default SMB Domain via `sharectl`

Source: https://illumos.org/books/smb-admin/smbclienttasks.html

This command sets the default SMB domain for the system or a specific user. It allows administrators to configure a default domain that will be used for SMB connections when not explicitly specified.

```bash
# `sharectl set -p section=default -p domain=AAA smbfs`
```

--------------------------------

### Define LDAP Schema and User Mappings in LDIF

Source: https://illumos.org/books/smb-admin/modifyadschema.html

LDIF format examples for extending LDAP schemas with custom attributes and mapping Unix users to Windows account names. These files are used as input for the ldapmodify tool.

```ldif
dn: cn=schema
changetype: modify
add: attributeTypes
attributeTypes: ( 1.3.6.1.4.1.42.2.27.5.1.62
   NAME 'winAccountName'
   DESC 'Windows user or group name corresponding to a Unix user or group'
   EQUALITY caseIgnoreMatch
   SUBSTRINGS caseIgnoreSubstringsMatch
   ORDERING caseIgnoreOrderingMatch
   SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )
-
add: objectClasses
objectClasses: ( 1.3.6.1.4.1.42.2.27.5.2.16
   NAME 'winAccount'
   DESC 'Auxiliary class to store Windows name mappings in Unix user/group objects'
   SUP top
   AUXILIARY
   MAY winAccountName )

dn: uid=tmw,ou=passwd,dc=example,dc=com
changetype: modify
add: winAccountName
winAccountName: terry@example.com
```

--------------------------------

### Illumos SMB Autohome Wildcard Rule

Source: https://illumos.org/books/smb-admin/smboverview.html

Demonstrates the use of the asterisk '*' character as a wildcard in the key field of an autohome map entry. This 'catch-all' entry matches any key not previously matched by other rules.

```shell
*	/home/&
```

--------------------------------

### Configure Active Directory UNIX User/Group Attributes (Shell)

Source: https://illumos.org/books/smb-admin/idmappingtasks.html

Configures the `idmap` service to use specific attributes in Active Directory for storing UNIX user and group names. Replace `_attribute-name_` with your chosen attribute names.

```shell
# `svccfg -s svc:/system/idmap setprop \
config/ad_unixuser_attr=astring: `_attribute-name_``
```

```shell
# `svccfg -s svc:/system/idmap setprop \
config/ad_unixgroup_attr=astring: `_attribute-name_``
```

```shell
# `svccfg -s svc:/system/idmap setprop \
config/ad_unixgroup_attr=astring: unixGroupName`
```

```shell
# `svccfg -s svc:/system/idmap setprop \
config/ad_unixuser_attr=astring: unixUserName`
```

--------------------------------

### Configure Native LDAP Windows Name Attribute (Shell)

Source: https://illumos.org/books/smb-admin/idmappingtasks.html

Configures the `idmap` service to use a specific attribute in native LDAP for storing Windows names. Replace `_attribute-name_` with your chosen attribute name.

```shell
# `svccfg -s svc:/system/idmap setprop 
config/nldap_winname_attr=astring: `_attribute-name_``
```

```shell
# `svccfg -s svc:/system/idmap setprop 
config/nldap_winname_attr=astring: winAccountName`
```

--------------------------------

### List and Remove Group Mappings with idmap list and idmap remove

Source: https://illumos.org/books/smb-admin/idmappingtasks.html

Illustrates how to list group mappings with `idmap list` and subsequently remove specific group mappings or all group mappings using `idmap remove`. This operation requires elevated privileges.

```bash
# `idmap list`
# `idmap list | grep staff`
# `idmap remove `_group-name_``
```

```bash
# `idmap remove `_group-name1_` `_group-name2_``
# `idmap remove -a`
```

--------------------------------

### Map Windows User to Unix User via AD (Shell)

Source: https://illumos.org/books/smb-admin/idmappingtasks.html

Maps a Windows user to a Unix user by adding the Unix user's name to the Active Directory object for the specified Windows user. Requires appropriate RBAC authorization.

```shell
# `idmap set-namemap winuser:`_username_`@`_domain-name_` unixuser:`_username_``
```

```shell
# `idmap set-namemap winuser:danab@example.com unixuser:dana`
```

--------------------------------

### Illumos SMB Autohome Map Entry Format

Source: https://illumos.org/books/smb-admin/smboverview.html

Defines the standard format for entries in the autohome map file. It includes the key, location, and an optional container for publishing shares in Active Directory (AD).

```shell
`_key_` `_location_` [ `_container_` ]
```

--------------------------------

### Dump All SID Mappings with idmap dump

Source: https://illumos.org/books/smb-admin/idmappingtasks.html

Lists all SID-to-UID and SID-to-GID mappings stored in the identity mapping cache. The `-v` option provides additional details on how each mapping was generated.

```bash
$ `idmap dump`
sid:S-1-5-21-2949573101-2750415176-3223191800-2000    ==     uid:50000
sid:S-1-5-21-2949573101-2750415176-3223191800-2001    ==     uid:50001
sid:S-1-5-21-2949573101-2750415176-3223191800-2006    ==     uid:50010
sid:S-1-5-21-2949573101-2750415176-3223191900-3000    ==     uid:2147491840
sid:S-1-5-21-2949573101-2750415176-3223191900-3001    ==     gid:2147491342
sid:S-1-5-21-2949573101-2750415176-3223191700-4000    =>     uid:60001
sid:S-1-5-21-2949573101-2750415176-3223191700-4001    =>     gid:60001
sid:S-1-5-21-2949573101-2750415176-3223191800-5000    ==     gid:50000
sid:S-1-5-21-2949573101-2750415176-3223191800-5001    ==     gid:50001
```

--------------------------------

### Enable idmap Directory-Based Mapping (Shell)

Source: https://illumos.org/books/smb-admin/idmappingtasks.html

Enables directory-based mapping for the `idmap` service. This command sets the `config/ds_name_mapping_enabled` property to `true`. Further configuration is required for specific directory services.

```shell
# `svccfg -s svc:/system/idmap setprop config/ds_name_mapping_enabled=boolean: true`
```

--------------------------------

### Map Unix User to Windows User via Native LDAP (Shell)

Source: https://illumos.org/books/smb-admin/idmappingtasks.html

Maps a Unix user to a Windows user by adding the Windows user's name to the native LDAP object for the specified Unix user. Requires appropriate RBAC authorization.

```shell
# `idmap set-namemap unixuser:`_username_` winuser:`_username_`@`_domain-name_``
```

```shell
# `idmap set-namemap unixuser:dana winuser:danab@example.com`
```

--------------------------------

### Map Windows Group to Unix Group via AD (Shell)

Source: https://illumos.org/books/smb-admin/idmappingtasks.html

Maps a Windows group to a Unix group by adding the Unix group's name to the Active Directory object for the specified Windows group. Requires appropriate RBAC authorization.

```shell
# `idmap set-namemap wingroup:`_group-name_`@`_domain-name_` unixgroup:`_group-name_``
```

```shell
# `idmap set-namemap wingroup:salesgrp@example.com unixgroup:sales`
```

--------------------------------

### Unmount an SMB Share

Source: https://illumos.org/books/smb-admin/smbclienttasks.html

This command unmounts a previously mounted SMB share. The user must own the mount point to successfully unmount the share. The command requires the local mount point path as an argument.

```bash
$ `umount /mnt`
```

--------------------------------

### Map Unix Group to Windows Group via Native LDAP (Shell)

Source: https://illumos.org/books/smb-admin/idmappingtasks.html

Maps a Unix group to a Windows group by adding the Windows group's name to the native LDAP object for the specified Unix group. Requires appropriate RBAC authorization.

```shell
# `idmap set-namemap unixgroup:`_group-name_` wingroup:`_group-name_`@`_domain-name_``
```

```shell
# `idmap set-namemap unixgroup:sales wingroup:salesgrp@example.com`
```
Tokens:
Raw