commands/storage/network-mounts/setup-smb-mounts.md

# SMB/CIFS Mount Setup Assistant

You are helping the user set up SMB/CIFS (Windows/Samba) mounts to remote systems.

## Your tasks:

1. **Check SMB client prerequisites:**
   - Check if CIFS utilities are installed: `dpkg -l | grep cifs-utils`
   - If not installed:
     ```bash
     sudo apt update
     sudo apt install cifs-utils
     ```

2. **Gather mount information from the user:**
   Ask the user for:
   - Remote SMB server IP or hostname (e.g., `10.0.0.100` or `nas.local`)
   - Share name (e.g., `shared` or `documents`)
   - Username for authentication
   - Domain (if applicable, otherwise use `WORKGROUP`)
   - Local mount point (e.g., `/mnt/smb/remote-share`)
   - Whether they want to store credentials securely

3. **Test SMB server accessibility:**
   - Check if remote server is reachable: `ping -c 3 <remote-ip>`
   - List available shares (if credentials are available):
     ```bash
     smbclient -L //<remote-ip> -U <username>
     ```
   - If this fails, troubleshoot:
     - Check if SMB ports are open (445, 139)
     - Verify firewall settings

4. **Set up credentials file (recommended for security):**
   Create a credentials file to avoid storing passwords in /etc/fstab:

   ```bash
   sudo mkdir -p /etc/samba/credentials
   sudo touch /etc/samba/credentials/<share-name>
   sudo chmod 700 /etc/samba/credentials
   sudo chmod 600 /etc/samba/credentials/<share-name>
   ```

   Edit the credentials file:
   ```
   username=<username>
   password=<password>
   domain=<domain>
   ```

   Secure it:
   ```bash
   sudo chown root:root /etc/samba/credentials/<share-name>
   sudo chmod 600 /etc/samba/credentials/<share-name>
   ```

5. **Create local mount point:**
   ```bash
   sudo mkdir -p <local-mount-point>
   ```

6. **Test mount temporarily:**
   Before making it permanent, test the mount:
   ```bash
   sudo mount -t cifs //<remote-ip>/<share-name> <local-mount-point> \
     -o credentials=/etc/samba/credentials/<share-name>,uid=$(id -u),gid=$(id -g)
   ```

   Verify the mount:
   ```bash
   df -h | grep <local-mount-point>
   ls -la <local-mount-point>
   ```

7. **Configure mount options:**
   Discuss common CIFS mount options with the user:
   - `credentials=<file>` - Use credentials file
   - `uid=<uid>` - Set file owner (use `id -u`)
   - `gid=<gid>` - Set file group (use `id -g`)
   - `file_mode=0644` - File permissions
   - `dir_mode=0755` - Directory permissions
   - `vers=3.0` - SMB protocol version (2.0, 2.1, 3.0, 3.1.1)
   - `iocharset=utf8` - Character set
   - `_netdev` - Required for network filesystems
   - `nofail` - Don't fail boot if mount unavailable
   - `noauto` - Don't mount automatically (use with autofs)
   - `rw` / `ro` - Read-write or read-only

   Recommended default options:
   ```
   credentials=/etc/samba/credentials/<share-name>,uid=<uid>,gid=<gid>,file_mode=0644,dir_mode=0755,vers=3.0,iocharset=utf8,_netdev,nofail
   ```

8. **Detect SMB version:**
   Help determine the best SMB version to use:
   ```bash
   smbclient -L //<remote-ip> -U <username> --option='client max protocol=SMB3'
   ```

   Common versions:
   - SMB 1.0 - Legacy, insecure (avoid)
   - SMB 2.0 - Windows Vista/Server 2008
   - SMB 2.1 - Windows 7/Server 2008 R2
   - SMB 3.0 - Windows 8/Server 2012
   - SMB 3.1.1 - Windows 10/Server 2016+ (recommended)

9. **Make mount permanent via /etc/fstab:**
   - Backup current fstab:
     ```bash
     sudo cp /etc/fstab /etc/fstab.backup.$(date +%Y%m%d_%H%M%S)
     ```

   - Add entry to /etc/fstab:
     ```
     //<remote-ip>/<share-name> <local-mount-point> cifs <options> 0 0
     ```

   - Test fstab entry without rebooting:
     ```bash
     sudo umount <local-mount-point>
     sudo mount -a
     df -h | grep <local-mount-point>
     ```

10. **Set up automount with systemd (alternative to fstab):**
    If the user prefers automount, create systemd mount units:

    Create `/etc/systemd/system/mnt-smb-remote\x2dshare.mount`:
    ```
    [Unit]
    Description=SMB Mount for remote-share
    After=network-online.target
    Wants=network-online.target

    [Mount]
    What=//<remote-ip>/<share-name>
    Where=<local-mount-point>
    Type=cifs
    Options=<options>

    [Install]
    WantedBy=multi-user.target
    ```

    Enable and start:
    ```bash
    sudo systemctl daemon-reload
    sudo systemctl enable mnt-smb-remote\\x2dshare.mount
    sudo systemctl start mnt-smb-remote\\x2dshare.mount
    sudo systemctl status mnt-smb-remote\\x2dshare.mount
    ```

11. **Configure for Windows Active Directory (if applicable):**
    If connecting to AD domain:
    - May need to install additional packages:
      ```bash
      sudo apt install krb5-user
      ```
    - Use domain credentials in credentials file
    - May need to configure Kerberos (`/etc/krb5.conf`)
    - Use `sec=krb5` option if Kerberos is configured

12. **Test and verify:**
    - Create a test file:
      ```bash
      touch <local-mount-point>/test-file
      ls -la <local-mount-point>/test-file
      ```
    - Check permissions and ownership
    - Verify mount survives reboot (ask user to test)

13. **Troubleshooting guidance:**
    If issues occur, check:
    - Network connectivity: `ping <remote-ip>`
    - SMB service on remote: `smbclient -L //<remote-ip> -N` (null session)
    - Firewall rules on both client and server
    - SMB version compatibility: try different `vers=` options
    - Credentials: test with `smbclient //<remote-ip>/<share-name> -U <username>`
    - Mount logs: `sudo journalctl -u <mount-unit>` or `dmesg | grep cifs`
    - Permissions issues: check `uid`, `gid`, `file_mode`, `dir_mode`
    - Check kernel logs: `dmesg | tail -20`

14. **Provide best practices:**
    - Store credentials in `/etc/samba/credentials/` with 600 permissions
    - Use SMB 3.0+ when possible (better security and performance)
    - Use `_netdev` and `nofail` options to prevent boot issues
    - Set appropriate `uid` and `gid` for file access
    - Avoid SMB 1.0 (deprecated and insecure)
    - Consider using autofs for on-demand mounting
    - Document all SMB mounts
    - Regular monitoring of SMB mount health
    - Keep credentials files secure (root ownership, 600 permissions)

## Important notes:
- Always backup /etc/fstab before editing
- Never store passwords directly in /etc/fstab
- Use credentials files with proper permissions (600, root:root)
- Test mounts before making them permanent
- Use `_netdev` and `nofail` options to prevent boot issues
- Systemd mount units need escaped names (replace / with \x2d)
- SMB 1.0 is deprecated and should be avoided