{"id":46182057,"url":"https://github.com/winterweken/sambo","last_synced_at":"2026-03-02T20:35:22.077Z","repository":{"id":325552428,"uuid":"1101618357","full_name":"winterweken/sambo","owner":"winterweken","description":"CLI \u0026 TUI Network Share Manager","archived":false,"fork":false,"pushed_at":"2025-12-18T03:26:47.000Z","size":29525,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-18T03:30:45.870Z","etag":null,"topics":["golang","homelab","homelab-setup","linux","nas","network","nfs","nfs-server","samba","samba-server","tui"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/winterweken.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-22T00:05:17.000Z","updated_at":"2025-12-16T03:04:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/winterweken/sambo","commit_stats":null,"previous_names":["winterweken/sambo"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/winterweken/sambo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winterweken%2Fsambo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winterweken%2Fsambo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winterweken%2Fsambo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winterweken%2Fsambo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/winterweken","download_url":"https://codeload.github.com/winterweken/sambo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winterweken%2Fsambo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30018583,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T17:00:27.440Z","status":"ssl_error","status_checked_at":"2026-03-02T17:00:03.402Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","homelab","homelab-setup","linux","nas","network","nfs","nfs-server","samba","samba-server","tui"],"created_at":"2026-03-02T20:35:21.306Z","updated_at":"2026-03-02T20:35:22.054Z","avatar_url":"https://github.com/winterweken.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sambo - Linux Share Management CLI\n\nA command-line interface tool for managing Samba (SMB/CIFS) and NFS shares on Linux headless servers.\n\n## Features\n\n- **Samba Share Management**: Create, list, modify, and remove Samba shares\n- **NFS Export Management**: Create, list, modify, and remove NFS exports\n- **Network Mount Management**: Mount and manage remote CIFS/SMB and NFS shares\n- **User Management**: Add, remove, and manage Samba users with password control\n- **Simple CLI Interface**: Easy-to-use command structure with helpful output\n- **Interactive TUI**: Beautiful text-based interface for all operations\n- **Configuration Backup**: Automatic backup before making changes\n- **Validation**: Tests configuration before applying changes\n\n## Requirements\n\n### System Requirements\n\n- Linux-based operating system\n- Root access (sudo)\n\n### Samba Requirements\n\n- `samba` package installed\n- `smbpasswd` command available\n- `testparm` command available\n\n### NFS Requirements\n\n- `nfs-kernel-server` or `nfs-server` package installed\n- `exportfs` command available\n\n### macOS Client Requirements\n\nFor macOS clients connecting to sambo-managed shares, run the client setup script to verify all requirements:\n\n```bash\n# If sambo is installed\n/usr/local/share/sambo/macos-client-setup.sh\n\n# Or download and run directly\ncurl -fsSL https://raw.githubusercontent.com/winterweken/sambo/main/scripts/macos-client-setup.sh | bash\n```\n\nThe script checks:\n\n- SMB/CIFS tools (`mount_smbfs`, `smbutil`)\n- NFS tools (`mount_nfs`, `showmount`)\n- Network connectivity and firewall settings\n- Automount configuration\n\nAdditional options:\n\n```bash\n# Test connectivity to a specific SMB server\n./macos-client-setup.sh --test-smb 192.168.1.10\n\n# Test connectivity to a specific NFS server\n./macos-client-setup.sh --test-nfs 192.168.1.10\n\n# Setup automount for persistent NFS mounts\nsudo ./macos-client-setup.sh --setup-automount\n\n# Install optional tools (nmap, smbclient) via Homebrew\n./macos-client-setup.sh --install-optional\n```\n\n## Installation\n\n### One-Liner Install (Recommended)\n\nInstall sambo with a single command:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/winterweken/sambo/main/scripts/install.sh | bash\n```\n\nThis automatically:\n\n- Detects your OS (Linux/macOS) and architecture (amd64/arm64/arm)\n- Downloads the latest release\n- Installs the binary to `/usr/local/bin`\n- Installs helper scripts to `/usr/local/share/sambo`\n\n### Download Pre-built Binary\n\nDownload the latest release for your architecture:\n\n```bash\n# For AMD64 (most common Intel/AMD servers)\nwget https://github.com/winterweken/sambo/releases/latest/download/sambo-linux-amd64\nsudo mv sambo-linux-amd64 /usr/local/bin/sambo\nsudo chmod +x /usr/local/bin/sambo\n\n# For ARM64 (Raspberry Pi 4, AWS Graviton, etc.)\nwget https://github.com/winterweken/sambo/releases/latest/download/sambo-linux-arm64\nsudo mv sambo-linux-arm64 /usr/local/bin/sambo\nsudo chmod +x /usr/local/bin/sambo\n\n# For ARM (Raspberry Pi 3 and older)\nwget https://github.com/winterweken/sambo/releases/latest/download/sambo-linux-arm\nsudo mv sambo-linux-arm /usr/local/bin/sambo\nsudo chmod +x /usr/local/bin/sambo\n\n# Verify installation\nsudo sambo version\n```\n\n### Build from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/winterweken/sambo.git\ncd sambo\n\n# Build the binary\nmake build\n\n# Install to system path\nsudo make install\n\n# Or run directly\nsudo ./build/sambo\n```\n\n### Quick Install Script\n\n```bash\n# Build and install from source\nmake build \u0026\u0026 sudo make install\n```\n\n## Usage\n\nAll commands must be run with root privileges:\n\n```bash\nsudo sambo \u003ccommand\u003e [subcommand] [options]\n```\n\n### Interactive TUI Mode (Recommended)\n\nSambo includes a beautiful text-based user interface (TUI) similar to DockStarter, making it easy to manage shares interactively:\n\n```bash\nsudo sambo tui\n```\n\nThe TUI provides:\n\n- **Arrow key navigation** through menus\n- **Interactive lists** of shares, exports, and users\n- **Visual feedback** with color-coded output\n- **Easy navigation** - ESC to go back, Q to quit\n- **Real-time viewing** of configured shares\n\n**TUI Navigation:**\n\n- `↑/↓` or `j/k` - Move up/down\n- `Enter` - Select menu item\n- `ESC` - Go back one level\n- `Q` - Return to main menu or quit\n\nThis is the easiest way to use Sambo, especially for users who prefer interactive menus over CLI commands.\n\n### General Commands\n\n```bash\nsambo help              # Show help\nsambo version           # Show version\nsambo tui               # Launch interactive menu (requires sudo)\n```\n\n## Samba Share Management\n\n### List all Samba shares\n\n```bash\nsudo sambo samba list\n```\n\n### Create a new share\n\n```bash\n# Basic share\nsudo sambo samba create -name myshare -path /mnt/data\n\n# Share with options\nsudo sambo samba create \\\n  -name documents \\\n  -path /mnt/documents \\\n  -comment \"Team Documents\" \\\n  -users alice,bob,charlie\n\n# Read-only share\nsudo sambo samba create \\\n  -name readonly \\\n  -path /mnt/public \\\n  -readonly \\\n  -comment \"Public Files\"\n```\n\n### Show share details\n\n```bash\nsudo sambo samba show -name myshare\n```\n\n### Modify an existing share\n\n```bash\n# Add users to share\nsudo sambo samba modify -name myshare -users alice,bob\n\n# Change comment\nsudo sambo samba modify -name myshare -comment \"New description\"\n```\n\n### Remove a share\n\n```bash\nsudo sambo samba remove -name myshare\n```\n\n### Apple Time Machine Support\n\nSambo includes built-in support for Apple Time Machine backups. When enabled, the share is automatically configured with the necessary VFS modules and settings:\n\n```bash\n# Using the TUI (recommended)\nsudo sambo tui\n# Select \"Manage Samba Shares\" → \"Create Share\"\n# Cycle \"Share Type\" to \"Time Machine\"\n\n# Using CLI\nsudo sambo samba create \\\n  -name timemachine \\\n  -path /mnt/backup/timemachine \\\n  -type timemachine \\\n  -comment \"Time Machine Backup\"\n```\n\n**Time Machine Configuration:**\n\nSambo automatically configures both global and share-level settings:\n\n*Global Samba settings (added automatically):*\n\n- `min protocol = SMB2` - Required for macOS compatibility\n- `ea support = yes` - Extended attributes support\n- `vfs objects = catia fruit streams_xattr` - macOS file system modules\n\n*Share-level settings:*\n\n- `fruit:metadata = stream` - Metadata handling\n- `fruit:model = MacSamba` - Identifies as Mac-compatible server\n- `fruit:aapl = yes` - Apple file system support\n- `fruit:time machine = yes` - Time Machine discovery\n- `fruit:time machine max size = 500G` - Default quota (configurable in smb.conf)\n- Additional fruit module optimizations for macOS compatibility\n\n**Important Notes:**\n\n- The share path must exist and be writable\n- Users must be added with valid Samba passwords (`sambo user add`)\n- macOS will discover the share automatically in Time Machine preferences\n- Recommended to use a dedicated share for Time Machine backups\n- Requires Samba 4.8 or newer for full Time Machine support\n\n### Ubiquiti Protect Support\n\nSambo includes optimized presets for using your server as a network storage destination for **Ubiquiti Protect** (UniFi NVR).\n\n```bash\n# Using the TUI (recommended)\nsudo sambo tui\n# Select \"Manage Samba Shares\" → \"Create Share\"\n# Cycle \"Share Type\" to \"Ubiquiti Protect\"\n\n# Using CLI\nsudo sambo samba create \\\n  -name unifi-protect \\\n  -path /mnt/video \\\n  -type unifi-protect\n```\n\n**Protect Configuration:**\n\n- `create mask = 0660` / `directory mask = 0770`\n- `inherit permissions = yes`\n- `nt acl support = yes`\n- `vfs objects = streams_xattr`\n- Automatically sets `0770` directory permissions for the share path\n\n### Media Server Optimization\n\nFor streaming media (Plex, Jellyfin), use the `media` type to enable read-ahead and performance optimizations:\n\n```bash\nsudo sambo samba create -name movies -path /mnt/media -type media\n```\n\n**Media Settings:**\n\n- `use sendfile = yes`\n- `strict locking = no`\n- `aio read/write size = 16384`\n\n## NFS Export Management\n\n### List all NFS exports\n\n```bash\nsudo sambo nfs list\n```\n\n### Create a new export\n\n```bash\n# Basic export (all clients)\nsudo sambo nfs create -path /mnt/backup\n\n# Export to specific network\nsudo sambo nfs create \\\n  -path /mnt/data \\\n  -clients 192.168.1.0/24\n\n# Read-only export\nsudo sambo nfs create \\\n  -path /mnt/public \\\n  -clients \"*\" \\\n  -readonly\n\n# Export with no root squash\nsudo sambo nfs create \\\n  -path /mnt/secure \\\n  -clients 192.168.1.100 \\\n  -no-root-squash\n```\n\n### Show export details\n\n```bash\nsudo sambo nfs show -path /mnt/backup\n```\n\n### Modify an existing export\n\n```bash\n# Change client access\nsudo sambo nfs modify -path /mnt/backup -clients 192.168.1.50\n\n# Make read-only\nsudo sambo nfs modify -path /mnt/backup -readonly\n```\n\n### Remove an export\n\n```bash\nsudo sambo nfs remove -path /mnt/backup\n```\n\n### NFS Configuration Presets (TUI)\n\nThe TUI provides easy checkbox options for common NFS configurations:\n\n**✓ Read Only** - Mount as read-only\n\n- Perfect for: Media servers (Plex, Jellyfin), public file shares\n- Options: `ro` instead of `rw`\n\n**✓ No Root Squash** - Allow root access\n\n- Perfect for: Backup destinations, Time Machine, system administration\n- Options: `no_root_squash` instead of `root_squash`\n- Warning: Only enable for trusted clients\n\n**✓ Async Mode** - Faster performance\n\n- Perfect for: Non-critical data, temporary files, media streaming\n- Options: `async` instead of `sync`\n- Warning: Data may be lost in case of server crash\n\n**Common Use Cases:**\n\n| Use Case | Read Only | No Root Squash | Async Mode |\n|----------|-----------|----------------|------------|\n| **Media Server** (Plex/Jellyfin) | ✓ | ✗ | ✓ |\n| **Backup Target** (Time Machine/rsync) | ✗ | ✓ | ✗ |\n| **Public Files** (read-only share) | ✓ | ✗ | ✗ |\n| **Development** (fast, not critical) | ✗ | ✗ | ✓ |\n| **Production Data** (safe default) | ✗ | ✗ | ✗ |\n\nAll exports include `no_subtree_check` by default for better performance.\n\n## Network Mount Management\n\nNetwork mount management allows you to mount remote shares on your system (client-side functionality). This complements the server-side share management features.\n\n### List all network mounts\n\n```bash\nsudo sambo mount list\n```\n\n### Mount a CIFS/SMB share\n\n```bash\n# Basic mount\nsudo sambo mount cifs \\\n  -source //server/share \\\n  -mountpoint /mnt/share \\\n  -username alice \\\n  -password secret123\n\n# Persistent mount (survives reboot)\nsudo sambo mount cifs \\\n  -source //192.168.1.100/backup \\\n  -mountpoint /mnt/backup \\\n  -username admin \\\n  -password pass123 \\\n  -persistent\n```\n\n### Mount an NFS share\n\n```bash\n# Basic mount\nsudo sambo mount nfs \\\n  -source server:/export/data \\\n  -mountpoint /mnt/data\n\n# Persistent mount (survives reboot)\nsudo sambo mount nfs \\\n  -source 192.168.1.100:/backups \\\n  -mountpoint /mnt/backups \\\n  -persistent\n```\n\n### Unmount a share\n\n```bash\n# Unmount temporarily\nsudo sambo mount unmount -mountpoint /mnt/share\n\n# Unmount and remove from fstab\nsudo sambo mount unmount \\\n  -mountpoint /mnt/share \\\n  -remove-persistent\n```\n\n### Mount Management in TUI\n\nThe interactive TUI provides easy forms for mounting shares:\n\n```bash\nsudo sambo tui\n# Select \"Manage Network Mounts\"\n```\n\n**Mount Features:**\n\n- **List Mounts**: View all currently mounted network shares (CIFS and NFS)\n- **Mount CIFS/SMB**: Mount Windows/Samba shares with authentication\n- **Mount NFS**: Mount NFS shares from Linux/Unix servers\n- **Unmount Share**: Safely unmount network shares\n- **Persistent Option**: Automatically mount shares at boot via /etc/fstab\n\n**Important Notes:**\n\n- Mount points will be created automatically if they don't exist\n- CIFS mounts support username/password authentication\n- Persistent mounts are added to `/etc/fstab` for automatic mounting\n- The \"Persistent\" checkbox in TUI ensures mounts survive reboots\n\n## User Management\n\n### List all Samba users\n\n```bash\nsudo sambo user list\n```\n\n### Add a new user\n\n```bash\n# Create user (creates system user automatically)\nsudo sambo user add -username alice -password secret123\n\n# Add user without creating system user\nsudo sambo user add \\\n  -username bob \\\n  -password pass456 \\\n  -create-system=false\n```\n\n### Show user details\n\n```bash\nsudo sambo user show -username alice\n```\n\n### Change user password\n\n```bash\nsudo sambo user passwd -username alice -password newsecret789\n```\n\n### Remove a user\n\n```bash\n# Remove Samba user only\nsudo sambo user remove -username alice\n\n# Remove both Samba and system user\nsudo sambo user remove -username alice -remove-system\n```\n\n## Common Workflows\n\n### Setting up a new shared folder\n\n```bash\n# 1. Create the directory\nsudo mkdir -p /mnt/shared\n\n# 2. Set permissions\nsudo chmod 775 /mnt/shared\n\n# 3. Create Samba users\nsudo sambo user add -username alice -password pass1\nsudo sambo user add -username bob -password pass2\n\n# 4. Create Samba share\nsudo sambo samba create \\\n  -name shared \\\n  -path /mnt/shared \\\n  -users alice,bob \\\n  -comment \"Shared Team Folder\"\n\n# 5. Create NFS export (optional, for Linux clients)\nsudo sambo nfs create \\\n  -path /mnt/shared \\\n  -clients 192.168.1.0/24\n```\n\n### Removing a share completely\n\n```bash\n# 1. Remove Samba share\nsudo sambo samba remove -name shared\n\n# 2. Remove NFS export\nsudo sambo nfs remove -path /mnt/shared\n\n# 3. Remove users (optional)\nsudo sambo user remove -username alice\nsudo sambo user remove -username bob\n```\n\n### Mounting a remote share persistently\n\n```bash\n# 1. Mount a remote CIFS share (from another server)\nsudo sambo mount cifs \\\n  -source //192.168.1.200/documents \\\n  -mountpoint /mnt/remote-docs \\\n  -username john \\\n  -password secret \\\n  -persistent\n\n# 2. Mount a remote NFS share (from another server)\nsudo sambo mount nfs \\\n  -source 192.168.1.201:/backups \\\n  -mountpoint /mnt/remote-backups \\\n  -persistent\n\n# 3. Verify mounts\nsudo sambo mount list\n```\n\n## Configuration Files\n\nSambo modifies the following system configuration files:\n\n- **Samba**: `/etc/samba/smb.conf`\n- **NFS**: `/etc/exports`\n- **Mounts**: `/etc/fstab` (for persistent mounts)\n\nBackups are created before modifications:\n\n- `/etc/samba/smb.conf.backup`\n- `/etc/exports.backup`\n- `/etc/fstab.backup`\n\n## Troubleshooting\n\n### Samba issues\n\n```bash\n# Test Samba configuration\nsudo testparm\n\n# Check Samba service status\nsudo systemctl status smbd\n\n# Restart Samba service\nsudo systemctl restart smbd\n\n# View Samba logs\nsudo journalctl -u smbd -f\n```\n\n### NFS issues\n\n```bash\n# Check current exports\nsudo exportfs -v\n\n# Re-export all\nsudo exportfs -ra\n\n# Check NFS service status\nsudo systemctl status nfs-server\n# or\nsudo systemctl status nfs-kernel-server\n\n# View NFS logs\nsudo journalctl -u nfs-server -f\n```\n\n### Mount issues\n\n```bash\n# List all network mounts\nsudo sambo mount list\n\n# Check if a share is mounted\nmount | grep cifs\nmount | grep nfs\n\n# View fstab entries\ncat /etc/fstab\n\n# Manually mount all fstab entries\nsudo mount -a\n\n# Check mount errors\nsudo dmesg | grep -i cifs\nsudo dmesg | grep -i nfs\n\n# For CIFS authentication issues, check credentials file\nsudo cat /root/.smbcredentials\n\n# Unmount a stuck mount\nsudo umount -f /mnt/mountpoint\n# or force lazy unmount\nsudo umount -l /mnt/mountpoint\n```\n\n### Permission issues\n\n```bash\n# Ensure directory exists and has correct permissions\nsudo ls -la /path/to/share\n\n# Fix ownership\nsudo chown -R nobody:nogroup /path/to/share\n\n# Fix permissions\nsudo chmod -R 775 /path/to/share\n```\n\n## Security Considerations\n\n1. **Always use strong passwords** for Samba users\n2. **Limit NFS exports** to specific IP addresses or networks when possible\n3. **Use read-only mode** for shares that don't require write access\n4. **Regular backups** of configuration files are maintained automatically\n5. **Firewall rules**: Ensure appropriate ports are open\n   - Samba: 139, 445 (TCP)\n   - NFS: 2049 (TCP/UDP)\n\n## Development\n\n### Project Structure\n\n```\nsambo/\n├── main.go              # Entry point\n├── cmd/                 # CLI commands\n│   ├── root.go         # Main command handler\n│   ├── samba.go        # Samba commands\n│   ├── nfs.go          # NFS commands\n│   ├── mount.go        # Network mount commands\n│   └── user.go         # User commands\n└── pkg/                 # Internal packages\n    ├── samba/          # Samba management\n    │   └── samba.go\n    ├── nfs/            # NFS management\n    │   └── nfs.go\n    ├── mount/          # Network mount management\n    │   └── mount.go\n    ├── user/           # User management\n    │   └── user.go\n    └── tui/            # Terminal UI\n        ├── tui.go\n        ├── forms.go\n        ├── views.go\n        └── select.go\n```\n\n### Building\n\n```bash\n# Development build\ngo build -o sambo\n\n# Production build with optimizations\ngo build -ldflags=\"-s -w\" -o sambo\n\n# Cross-compile for different architectures\nGOOS=linux GOARCH=amd64 go build -o sambo-amd64\nGOOS=linux GOARCH=arm64 go build -o sambo-arm64\n```\n\n## License\n\nThis project is provided as-is for managing Linux file shares.\n\n## Contributing\n\nFeel free to submit issues and enhancement requests!\n\n## Version\n\nv1.5.1\n\n## Credits\n\n- **Samba Team**: For the core file sharing capabilities.\n- **Bubble Tea**: For the amazing TUI framework.\n- **Contributors**:\n    - Carter (Project Lead)\n    - Claude / Gemini (AI Assistants)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwinterweken%2Fsambo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwinterweken%2Fsambo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwinterweken%2Fsambo/lists"}