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:

     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):

     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:

   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:

   sudo chown root:root /etc/samba/credentials/<share-name>
   sudo chmod 600 /etc/samba/credentials/<share-name>
   

5. Create local mount point:

   sudo mkdir -p <local-mount-point>
   

6. Test mount temporarily: Before making it permanent, test the mount:

   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:

   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:

   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:

     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:

     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:

    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:

      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:

      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