netshare-mounter

Synced from the repo

This page is generated from packages/debian-ubuntu/scripts/netshare-mounter/README.md. Edit it there — changes here are overwritten on the next build.

A production-ready CLI utility to automatically configure SMB/CIFS share mounting on Linux systems using systemd mount units.

Features

• ✅ Systemd mount units - Most reliable approach for automatic mounting
• ✅ Interactive & CLI modes - Flexible credential input (prompts or command-line args)
• ✅ Secure credentials - Automatic permissions (600) for credentials files
• ✅ Auto-dependency installation - Automatically installs cifs-utils if needed
• ✅ Comprehensive validation - Network connectivity, credentials, and system checks
• ✅ Status monitoring - Check mount status with detailed or JSON output
• ✅ Clean unmounting - Remove configurations and cleanup with confirmation prompts
• ✅ Color-coded output - Clear visual feedbacks for success, warnings, and errors

Installation

Prerequisites

• Linux system with systemd
• Root/sudo access
• Ruby (for Bashly framework)

Using Bashly (Ruby)

1. Install Bashly (if not already installed):

   gem install bashly

2. Generate the executable:

   cd packages/debian-ubuntu/scripts/netshare-mounter
   bashly generate

3. Make executable (if needed):

   chmod +x netshare-mounter

4. Install system-wide (optional):

   sudo cp netshare-mounter /usr/local/bin/

Using Docker (recommended if Ruby not installed)

If you don’t want to install Ruby/Bashly:

Linux/macOS:

cd packages/debian-ubuntu/scripts/netshare-mounter
docker run --rm --user $(id -u):$(id -g) --volume "$PWD:/app" dannyben/bashly generate

Windows (Git Bash/WSL):

cd packages/debian-ubuntu/scripts/netshare-mounter
docker run --rm --volume "/${PWD}:/app" dannyben/bashly generate

Usage

Quick Start

# Interactive mode (will prompt for username/password)
sudo netshare-mounter mount //192.168.1.29/plex_storage /mnt/plex_storage

# Full CLI mode (all parameters specified)
sudo netshare-mounter mount //192.168.1.29/plex_storage /mnt/plex_storage \
  --username myuser \
  --password mypass \
  --uid 1000 \
  --gid 1000

# Check status
netshare-mounter status /mnt/plex_storage

# Unmount and cleanup
sudo netshare-mounter unmount /mnt/plex_storage

Commands

mount - Configure and mount SMB share

netshare-mounter mount <share> <mountpoint> [options]

Arguments:

• share - SMB share path (e.g., //192.168.1.29/plex_storage)
• mountpoint - Local mount point (e.g., /mnt/plex_storage)

Options:

• -u, --username <username> - SMB username (prompts if not provided)
• -p, --password <password> - SMB password (prompts if not provided)
• -d, --domain <domain> - SMB domain (optional)
• --uid <uid> - User ID for file ownership (default: 1000)
• --gid <gid> - Group ID for file ownership (default: 1000)
• --file-mode <mode> - File permissions in octal (default: 0644)
• --dir-mode <mode> - Directory permissions in octal (default: 0755)
• --cifs-version <version> - CIFS protocol version (default: 3.0)
  • Allowed: 1.0, 2.0, 2.1, 3.0, 3.1.1
• -c, --credentials-file <path> - Credentials file path (auto-generated as ~/.netshare-mounter/<unit-name>.credentials in the user’s home directory if not specified)
• --auto-install - Automatically install cifs-utils without prompting
• --enable-only - Only enable mount unit without starting it (mount on next boot)

Examples:

# Basic mount with interactive credentials
sudo netshare-mounter mount //server/share /mnt/share

# Full automation (no prompts)
sudo netshare-mounter mount //nas/media /mnt/media \
  -u admin -p secretpass \
  --auto-install

# Custom CIFS version and permissions
sudo netshare-mounter mount //old-server/data /mnt/data \
  --cifs-version 2.0 \
  --uid 1001 \
  --gid 1001 \
  --file-mode 0640

# Enable for next boot without immediate mount
sudo netshare-mounter mount //server/backup /mnt/backup \
  -u backup -p pass123 \
  --enable-only

unmount - Remove mount configuration

netshare-mounter unmount <mountpoint> [options]

Arguments:

• mountpoint - Mount point to unmount (e.g., /mnt/plex_storage)

Options:

• -k, --keep-credentials - Keep credentials file (don’t delete)
• -m, --keep-mountpoint - Keep mount point directory (don’t delete)
• -f, --force - Force unmount even if busy (umount -f)
• --purge - Remove all mount dependencies without prompting (credentials, mount point, systemd unit)

Examples:

# Basic unmount (prompts for cleanup confirmations)
sudo netshare-mounter unmount /mnt/plex_storage

# Keep credentials for later use
sudo netshare-mounter unmount /mnt/share --keep-credentials

# Force unmount if share is busy
sudo netshare-mounter unmount /mnt/media --force

# Keep everything, only stop the mount
sudo netshare-mounter unmount /mnt/data -k -m

# Complete cleanup without prompts (purge mode)
sudo netshare-mounter unmount /mnt/plex_storage --purge

status - Check mount status

netshare-mounter status [mountpoint] [options]

Arguments:

• mountpoint - Mount point to check (optional, shows all if omitted)

Options:

• -v, --verbose - Show detailed systemd unit information
• -j, --json - Output in JSON format

Examples:

# Show all CIFS mounts
netshare-mounter status

# Check specific mount
netshare-mounter status /mnt/plex_storage

# Detailed information
netshare-mounter status /mnt/share --verbose

# JSON output for scripting
netshare-mounter status /mnt/data --json

validate - Validate share and system

netshare-mounter validate <share> [options]

Arguments:

• share - SMB share path to validate (e.g., //server/share)

Options:

• -c, --check-connectivity - Test network connectivity to SMB server
• --check-credentials <file> - Validate credentials file permissions

Examples:

# Basic validation
netshare-mounter validate //192.168.1.29/plex_storage

# Full validation with connectivity test
sudo netshare-mounter validate //server/share --check-connectivity

# Validate existing credentials
sudo netshare-mounter validate //nas/data \
  --check-credentials /root/.smbcredentials

How It Works

Architecture

netshare-mounter
├── Validates inputs (share path, mountpoint)
├── Installs dependencies (cifs-utils)
├── Creates dedicated credentials file (600 permissions)
│   └── ~/.netshare-mounter/<unit-name>.credentials (in user's home directory)
├── Generates systemd mount unit
│   ├── /etc/systemd/system/mnt-<name>.mount
│   └── Configured with After=network-online.target
├── Enables and starts mount unit
└── Verifies successful mount

Dedicated Credentials Files

Each mount gets its own credentials file automatically:

• Mount /mnt/plex_storage → ~/.netshare-mounter/mnt-plex_storage.credentials
• Mount /mnt/data → ~/.netshare-mounter/mnt-data.credentials
• Mount /media/share → ~/.netshare-mounter/media-share.credentials

(Stored in the user’s home directory, even when running with sudo)

Benefits:

• ✅ No credential conflicts between mounts
• ✅ Easy identification (credentials match mount point)
• ✅ Clean unmount (removes only that mount’s credentials)
• ✅ All credentials organized in one directory
• ✅ You can still override with --credentials-file if needed

Systemd Mount Units

The tool creates systemd .mount units which provide:

• Automatic mounting on boot (if enabled)
• Dependency management (waits for network)
• Logging via journalctl
• Service management via systemctl

Example generated unit (/etc/systemd/system/mnt-plex_storage.mount):

[Unit]
Description=Mount SMB Share: //192.168.1.29/plex_storage
After=network-online.target
Wants=network-online.target
RequiresMountsFor=/mnt

[Mount]
What=//192.168.1.29/plex_storage
Where=/mnt/plex_storage
Type=cifs
Options=credentials=/root/.smbcredentials,uid=1000,gid=1000,file_mode=0644,dir_mode=0755,vers=3.0,rw
TimeoutSec=30

[Install]
WantedBy=multi-user.target

Security

• Credentials files are created with 600 permissions (readable only by root)
• Passwords are never logged or displayed in plain text
• Secure deletion using shred when removing credentials files
• Validation of file permissions before mounting

Troubleshooting

Mount fails with “Permission denied”

Check credentials:

sudo cat /root/.smbcredentials
# Verify username and password are correct

Test credentials manually:

sudo mount -t cifs //server/share /mnt/test \
  -o credentials=/root/.smbcredentials

Mount fails with “Connection timed out”

Validate connectivity:

netshare-mounter validate //server/share --check-connectivity

Check firewall:

# SMB uses port 445
sudo nc -zv server 445

Mount unit fails to start

Check systemd status:

sudo systemctl status mnt-share_name.mount

View detailed logs:

sudo journalctl -xeu mnt-share_name.mount

Share is busy during unmount

Find what’s using the mount:

sudo lsof /mnt/share_name
sudo fuser -vm /mnt/share_name

Force unmount:

sudo netshare-mounter unmount /mnt/share_name --force

Credentials file has wrong permissions

Fix permissions:

sudo chmod 600 /root/.smbcredentials
sudo chown root:root /root/.smbcredentials

Or validate and auto-fix:

sudo netshare-mounter validate //server/share \
  --check-credentials /root/.smbcredentials

Common Issues

systemd mount unit naming

Systemd requires mount unit names to match the mount path:

• /mnt/plex_storage → mnt-plex_storage.mount
• /media/share → media-share.mount
• Spaces are NOT allowed in mount paths

CIFS version compatibility

If mount fails, try different CIFS versions:

# Old servers may require 1.0 or 2.0
sudo netshare-mounter mount //old-nas/share /mnt/old \
  --cifs-version 1.0

# Modern servers prefer 3.0 or 3.1.1
sudo netshare-mounter mount //new-nas/share /mnt/new \
  --cifs-version 3.1.1

Domain authentication

For Active Directory environments:

sudo netshare-mounter mount //server/share /mnt/share \
  --username DOMAIN\\user \
  --password pass \
  --domain DOMAIN

Advanced Usage

Multiple mounts (each gets dedicated credentials)

~/.netshare-mounter/mnt-share1.credentials

# Each mount automatically gets its own credentials file
sudo netshare-mounter mount //server/share1 /mnt/share1 -u user -p pass
sudo netshare-mounter mount //server/share2 /mnt/share2 -u user -p pass
# Creates: ~/.netshare-mounter/mnt-share2.credentials

Sharing credentials between mounts (optional)

If you want multiple mounts to use the same credentials file:

# Create shared credentials file
sudo netshare-mounter mount //server/share1 /mnt/share1 \
  -u user -p pass -c /root/.smb_server_shared

# Reuse the same credentials file
sudo netshare-mounter mount //server/share2 /mnt/share2 \
  -u user -p pass -c /root/.smb_server_shared

Scripted deployment

#!/bin/bash

# Validate first
if ! netshare-mounter validate //server/share --check-connectivity; then
  echo "Validation failed, aborting"
  exit 1
fi

# Mount with full automation
netshare-mounter mount //server/share /mnt/share \
  --username "$SMB_USER" \
  --password "$SMB_PASS" \
  --auto-install \
  --json

Monitoring with JSON output

# Get mount status as JSON
netshare-mounter status /mnt/share --json | jq '.mounted'

# Check if active
netshare-mounter status /mnt/share --json | jq -r '.active'

Development

Building from source

cd packages/debian-ubuntu/scripts/netshare-mounter

# Generate executable
bashly generate

# Run tests (if implemented)
./netshare-mounter --help

Project structure

netshare-mounter/
├── src/
│   ├── bashly.yml             # Bashly configuration
│   ├── mount_command.sh       # Mount implementation
│   ├── unmount_command.sh     # Unmount implementation
│   ├── status_command.sh      # Status check
│   ├── validate_command.sh    # Validation logic
│   └── lib/
│       ├── helpers.sh         # Common utilities
│       ├── systemd.sh         # Systemd operations
│       └── credentials.sh     # Credentials management
├── netshare-mounter           # Generated executable (after bashly generate)
├── README.md                  # This file
└── USAGE.md                   # Quick usage guide

Contributing

When contributing, ensure:

1. All shell scripts pass shellcheck
2. Code follows existing style conventions
3. Functions are well-documented
4. Test all commands before submitting

License

This tool is part of the ubuntu-server-config repository.

Related Documentation

• Systemd Mount Units
• CIFS Mount Options
• Bashly Framework

Support

For issues, questions, or contributions, please refer to the main repository documentation.