sambam

The fastest way to share files with Windows, macOS and Linux. No setup. No passwords. No patience required.

Built with AI assistance — Idea and design by a human, code by an AI. Fully open source and auditable.

You know the drill: Your colleague needs a file. They're on Windows. You're on Linux. You could email it (if it's under 25MB). You could upload it to some cloud service (and wait). You could set up Samba (LOL, see you next week). Or...

sudo sambam /path/to/folder

Done. They open \\your-ip\share in Explorer. Files are flowing. You're a hero. sambam is like python -m http.server but for Windows network shares. One command, instant SMB file sharing.

Why sambam?

The Old Way	The sambam Way
Install Samba	sudo sambam .
Edit smb.conf	That's it.
Configure users	Seriously.
Restart services	You're done.
Debug permissions	Go grab coffee.
Google error messages
Cry softly

Features

• Zero setup - One command starts sharing, no service install required
• Config is optional - Run CLI-only, use layered defaults (/etc, home, local), or use explicit -c config-only mode
• Anonymous by default - Guest access works out of the box
• Optional authentication - Add users/passwords via CLI or config
• Multiple shares - Share multiple directories with custom names
• Per-share ACLs - allow_users and share-level readonly
• SMB3 encryption by default - Enabled automatically for authenticated sessions when client supports it
• Discovery support - mDNS (macOS) and WSD (Windows), with --no-advertise to disable
• Auto-expire - Stop sharing automatically after a duration
• Daemon mode - Run in background with sambam status / sambam stop
• Cross-platform clients - Windows 10/11, macOS, Linux (CIFS mount)
• SMB 2.1 / 3.0 / 3.1.1 - Modern protocol support, including POSIX extensions
• Single binary - Runs on Linux distributions (Debian, Ubuntu, OpenWrt, etc.)
• Shell completions - Bash and Fish completion scripts included

Installation

Download artifacts from the Releases page.

Native packages are available for:

• Debian/Ubuntu (.deb)
• Fedora/RHEL/openSUSE (.rpm)
• Arch Linux (.pkg.tar.zst)
• Alpine (.apk)

You can install the matching package for your distro, or use the standalone binary:

chmod +x sambam-linux-amd64
sudo mv sambam-linux-amd64 /usr/local/bin/sambam

Or build from source:

go build -o sambam .

Quick Start

# Share current directory (anonymous access, read-write)
sudo sambam

# Share a specific folder
sudo sambam /path/to/folder

# Share read-only with a custom name
sudo sambam -r -n photos ~/Pictures

Options

-n, --name <name> or -n <name:path>

Set the share name. By default the share name is the directory name. Use name:path syntax to specify both name and path. Repeatable for multiple shares.

sudo sambam -n myfiles /data
sudo sambam -n docs:/home/user/documents -n pics:/home/user/photos

-l, --listen <address>

Address and port to listen on. Default: 0.0.0.0:445.
You can also bind by interface with @<name> (optionally with port), for example @eth0 or @eth0:445. Repeat the flag to bind multiple endpoints.

sudo sambam -l 0.0.0.0:8445 /data
sudo sambam -l @eth0:445 /data
sudo sambam -l @eth0 -l 10.23.22.13:445 /data

-a, --allow <ip-or-cidr>

Allowlist client source addresses. Repeatable.

Accepted values:

• Single IP (192.168.1.10)
• CIDR network (192.168.1.0/24)

If one or more --allow rules are set, only matching clients can connect.

sambam -a 192.168.1.10 -a 192.168.2.0/24 /data

-x, --no-advertise

By default, sambam advertises the SMB service for LAN discovery using:

• Bonjour/mDNS (_smb._tcp)
• WS-Discovery (Windows Network discovery)

Ports used by sambam:

• TCP 445 (SMB service)
• UDP 3702 (WS-Discovery probe/resolve)
• TCP 5357 (WS-Discovery metadata HTTP)

Use -x / --no-advertise to disable discovery announcements. Set [global].discovery_name_mdns and [global].discovery_name_wsd in config to control discovery names for macOS (mDNS) and Windows (WSD).

sambam /data
sambam -x /data
sambam --no-advertise /data

-r, --readonly

Share in read-only mode. Clients can browse and copy files but cannot modify, delete, or upload.

-u, --username <user|user:password>

Require authentication. Repeatable.

• Single-user quick mode: -u admin -p secret (or omit -p for random password)
• Multi-user CLI mode: -u alice:secret1 -u bob:secret2

sudo sambam -u admin /data
sudo sambam -u admin -p secret123 /data
sudo sambam -u alice:secret1 -u bob:secret2 /data

-p, --password <password>

Set a password for single-user CLI mode (-u <user>).
For multi-user CLI mode, use -u <user:password> for each user.

Authentication Tiers

Tier 1 — quick share:

sambam /data
sambam -u alice -p secret /data

Tier 2 — multiple users (same access for all):

sambam -u alice:secret1 -u bob:secret2 /data

Tier 3 — per-share permissions (config):

[user.alice]
password = "secret1"

[user.bob]
password = "secret2"
readonly = true

[share.media]
path = "/mnt/media"

[share.private]
path = "/home/user/private"
allow_users = ["alice"]

[share.public]
path = "/srv/public"
allow_users = ["guest"]

-e, --expire <duration>

Automatically stop sharing after the given duration. Accepts Go duration format: 30m, 1h, 2h30m, etc.

sudo sambam --expire 30m /data

-v, --verbose

Show real-time connection and file activity.

Use verbosity levels:

• -v basic activity
• -vv extended diagnostics (open mode, read events, close summaries, slow ops, auth failures)
• -vvv full protocol trace (includes -v and -vv)

  15:04:05 connect 192.168.1.100:54321
  15:04:10 [share] create file documents/report.docx
  15:04:12 [share] create dir  backup
  15:04:15 [share] delete temp/old-file.txt

-H, --hide-dotfiles

Hide files starting with . from directory listings. By default dotfiles are visible.

-d, --daemon

Run sambam as a background daemon. Use sambam status to inspect it and sambam stop to stop it.

sudo sambam -d /data
sudo sambam status
sudo sambam stop

-P, --pidfile <path>

PID file location for daemon mode. Default: /tmp/sambam.pid.

-L, --logfile [path]

Log file path. In daemon mode, logs go to this file (otherwise daemon output goes to /dev/null). In foreground mode, logs are written to both terminal and this file. If used without a value, defaults to /tmp/sambam.log.

-c, --config <path>

Load config file(s) explicitly. Repeatable.

When -c is used, default discovery (/etc/sambamrc, ~/.sambamrc, ./.sambamrc) is skipped. Files passed via -c are applied in order, and CLI flags still have highest priority.

sambam -c /etc/sambam-prod.toml -c ./sambam.override.toml

sudo sambam -d -L /var/log/sambam.log /data
sudo sambam -L /tmp/sambam.log /data

-G, --gen-config [path]

Generate a TOML config from the currently passed CLI flags and exit without starting the server.

• If no path is given, writes ./.sambamrc
• If a path is given, writes to that file
• Generated config includes users and shares based on passed flags

sambam -r -u admin -p secret -G
sambam -l 10.23.22.13:445 -e 1h -G /tmp/sambamrc.toml

-V, --version

Show version and exit.

-h, --help

Show help and exit.

Configuration File

sambam has two config loading modes:

1. Default mode (no -c): /etc/sambamrc -> ~/.sambamrc -> ./.sambamrc
2. Explicit mode (with -c): only the provided -c, --config <path> files, in order (required to exist)

CLI flags override all config values.

Configuration Layout

[global]
listen = "0.0.0.0:445"
# listen = ["@eth0:445", "10.23.22.13:445"]

allow = ["0.0.0.0/0"]
advertise = true
smb3_encryption = true
guest_browse_ipc = true
show_connect_hints = true
discovery_name_mdns = "<hostname>-sambam"
discovery_name_wsd = "<hostname>"
readonly = false
hide_dotfiles = false

verbose = true
# verbose_level = 2
# verbose_level = 3
debug = false
trace = false

expire = "1h"
pidfile = "/tmp/sambam.pid"
logfile = "/tmp/sambam.log"

[user.alice]
password = "secret1"
readonly = false

[user.bob]
password = "secret2"
readonly = true

[share.docs]
path = "/tmp/docs"
allow_users = ["alice", "bob"]
readonly = false

[share.private]
path = "/tmp/private"
allow_users = ["alice"]
readonly = true

[share.public]
path = "/tmp/public"
allow_users = ["guest"]
readonly = false

Global options:

• listen (string or array)
• allow (default: allow all, e.g. ["0.0.0.0/0"])
• advertise (default: true)
• smb3_encryption (default: true; used when client supports SMB3 encryption)
• guest_browse_ipc (default: true; allows guest auth for IPC$/browse discovery even when shares require users)
• show_connect_hints (default: true; show Windows/macOS/Linux connect commands in startup banner)
• discovery_name_mdns (default: <hostname>-sambam)
• discovery_name_wsd (default: <hostname>)
• hide_dotfiles
• readonly
• expire
• pidfile
• logfile
• verbose / verbose_level

Per-user options ([user.<name>]):

• password
• readonly

Per-share options ([share.<name>]):

• path
• readonly
• allow_users

Notes:

• allow_users = ["guest"] creates a guest-only (anonymous) share.
• allow_users = ["alice", "bob"] restricts a share to specific authenticated users.
• allow_users = ["guest", "alice"] allows both guest and selected users.
• smb3_encryption is enabled by default. Set smb3_encryption = false only for compatibility troubleshooting.
• Guest sessions (allow_users = ["guest"]) are not encrypted; use authenticated users if you require SMB encryption.
• guest_browse_ipc = true improves Finder "click discovered server" behavior on macOS while still enforcing share ACLs. Set it to false to require authenticated session setup from the start.

See sambamrc.example for a full example.

Troubleshooting config selection

Run with verbosity to see exactly which config files were loaded:

sambam -v

You will see a line like:

config: loaded /etc/sambamrc, /root/.sambamrc, .sambamrc

Connecting from Windows

Once sambam is running, it prints ready-to-use connection paths:

  sambam v1.4.x

  Sharing      /home/user/documents
  Share        documents
  Listen       10.23.22.13:445
  Mode         read-write
  Auth         anonymous

  All connections:
  Windows      \\10.23.22.13\documents
  macOS        smb://10.23.22.13/documents
  Linux        sudo mount -t cifs //10.23.22.13/documents /mnt -o guest
               sudo mount -t cifs //10.23.22.13/documents /mnt -o guest,vers=3.1.1,posix,cifsacl # POSIX

  Press Ctrl+C to stop

From Windows:

1. Open File Explorer
2. Type the path in the address bar: \\10.23.22.13\documents
3. Press Enter
4. If authentication is required, enter the username and password

Or mount as a drive:

net use Z: \\10.23.22.13\documents

# With authentication
net use Z: \\10.23.22.13\documents /user:alice

Connecting from Linux

Mount using CIFS with SMB 3.0:

# Anonymous access
sudo mount -t cifs //server-ip/share /mnt/share -o guest,vers=3.0

# With authentication
sudo mount -t cifs //server-ip/share /mnt/share -o username=admin,password=secret123,vers=3.0

POSIX extensions (real Unix permissions)

sambam supports SMB2 POSIX extensions, which let Linux clients see real Unix permissions, owners, and use chmod/chown. This requires SMB 3.1.1:

# POSIX mount with chmod/chown support
sudo mount -t cifs //server-ip/share /mnt/share -o guest,vers=3.1.1,posix,cifsacl

With POSIX extensions, ls -la shows actual file owners and permissions from the server instead of defaults. The cifsacl option is required on kernel 6.1 for chmod to work; newer kernels (6.5+) may not need it.

Windows Credential Troubleshooting

Windows caches SMB credentials. If you're having authentication issues:

# List active connections
net use

# Disconnect a specific share
net use \\192.168.1.100\share /delete

# Or disconnect all shares
net use * /delete

After clearing cached connections, reconnect and Windows will prompt for new credentials.

Non-standard ports

Port 445 requires root. You can use a non-standard port instead:

sambam -l :8888 /data

Linux clients support non-standard ports natively:

sudo mount -t cifs //server-ip/share /mnt -o guest,port=8888

Windows and macOS only connect to port 445. To use a non-standard port, create an SSH tunnel:

# Forward local port 445 to the sambam server
ssh -L 445:server-ip:8888 user@server-ip

Then connect to \\localhost\share (Windows) or smb://localhost/share (macOS).

On Windows, port 445 is usually already in use by the built-in SMB service. A workaround is to run the tunnel inside WSL and bind to the WSL network interface:

# Inside WSL — find WSL's IP with: ip addr show eth0
ssh -L 172.x.x.x:445:server-ip:8888 user@server-ip

Then connect from Windows using \\172.x.x.x\share (the WSL IP).

Requirements

• Root privileges - Port 445 requires root (or use -l :8888 for a non-standard port)
• Linux server - Works on any distribution (Debian, Ubuntu, OpenWrt, Alpine, etc.)
• Clients - Windows 10/11, macOS, or Linux (via CIFS mount)

Known Issues

These notes apply to the sambam server (the application serving files), not to client applications (Windows Explorer, macOS Finder, Linux mount tools, etc.).

Platform-Specific Notes

Linux - Fully stable. All features working including POSIX extensions, file permissions, and advanced operations.

macOS (Apple Silicon) - Excellent support. Thoroughly tested and works as reliably as Linux. All features including POSIX extensions fully functional. No known issues.

Windows - Experimental server build

• No POSIX extensions support (limitations on Unix-style permissions)
• File deletion issues: Files cannot be deleted while the server is running (Windows file locking behavior)
• Other features work correctly

Security Notice

By default, sambam uses anonymous/guest authentication. This means:

• No passwords - Anyone on your network can access the share
• Use on trusted networks only - Don't run this on public WiFi
• Not for production - This is for quick file transfers, not Fort Knox

For sensitive shares, use --username to require authentication, and -r for read-only mode.

License

AGPL-3.0

---

Made for those moments when you just need to share a damn file.