{"id":43676152,"url":"https://github.com/darkpenguin23/sambam","last_synced_at":"2026-02-19T02:02:45.725Z","repository":{"id":336536081,"uuid":"1148763613","full_name":"darkpenguin23/sambam","owner":"darkpenguin23","description":"One-command SMB file server for quick LAN sharing with Windows/macOS clients.","archived":false,"fork":false,"pushed_at":"2026-02-07T18:54:41.000Z","size":3538,"stargazers_count":13,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-07T22:46:05.281Z","etag":null,"topics":["file-sharing","network-share","samba"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/darkpenguin23.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":"2026-02-03T10:39:13.000Z","updated_at":"2026-02-07T18:54:44.000Z","dependencies_parsed_at":"2026-02-08T17:00:46.578Z","dependency_job_id":null,"html_url":"https://github.com/darkpenguin23/sambam","commit_stats":null,"previous_names":["darkpenguin23/sambam"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/darkpenguin23/sambam","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkpenguin23%2Fsambam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkpenguin23%2Fsambam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkpenguin23%2Fsambam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkpenguin23%2Fsambam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/darkpenguin23","download_url":"https://codeload.github.com/darkpenguin23/sambam/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkpenguin23%2Fsambam/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29237072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-08T14:18:14.570Z","status":"ssl_error","status_checked_at":"2026-02-08T14:18:14.071Z","response_time":57,"last_error":"SSL_read: 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":["file-sharing","network-share","samba"],"created_at":"2026-02-05T01:02:16.288Z","updated_at":"2026-02-19T02:02:45.713Z","avatar_url":"https://github.com/darkpenguin23.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sambam\n\n**The fastest way to share files with Windows, macOS and Linux.** No setup. No passwords. No patience required.\n\n\u003e **Built with AI assistance** — Idea and design by a human, code by an AI. Fully open source and auditable.\n\nYou 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...\n\n```bash\nsudo sambam /path/to/folder\n```\n\nDone. They open `\\\\your-ip\\share` in Explorer. Files are flowing. You're a hero.\n**sambam** is like `python -m http.server` but for Windows network shares. One command, instant SMB file sharing.\n\n![Demo](demo.gif)\n\n## Why sambam?\n\n| The Old Way | The sambam Way |\n|-------------|----------------|\n| Install Samba | `sudo sambam .` |\n| Edit smb.conf | That's it. |\n| Configure users | Seriously. |\n| Restart services | You're done. |\n| Debug permissions | Go grab coffee. |\n| Google error messages | |\n| Cry softly | |\n\n## Features\n\n- **Zero configuration** - No config files, no setup wizards, no existential dread\n- **Anonymous access** - No passwords by default (or add authentication if needed)\n- **Optional authentication** - Require username/password when you need it\n- **Tiered auth model** - Single-user CLI, multi-user CLI shorthand, or `[[users]]` config\n- **Multiple shares** - Share multiple directories with different names\n- **Per-share access control** - `allow_users` and share-level `readonly` in config\n- **Auto-expire** - Automatically stop sharing after a set time\n- **Config file** - Layered defaults, or explicit `-c` config-only mode\n- **Cross-platform clients** - Works with Windows 10/11, macOS, and Linux (CIFS mount)\n- **SMB 2.1 / 3.0 / 3.1.1** - Compatible with modern SMB protocol versions, including POSIX extensions\n- **Single binary** - Runs on any Linux distribution (Debian, Ubuntu, OpenWrt, etc.)\n- **Daemon mode** - Run in background, stop when done\n- **Shell completions** - Bash and Fish completion scripts included\n\n## Installation\n\nDownload artifacts from the [Releases](https://github.com/darkpenguin23/sambam/releases) page.\n\nNative packages are available for:\n- Debian/Ubuntu (`.deb`)\n- Fedora/RHEL/openSUSE (`.rpm`)\n- Arch Linux (`.pkg.tar.zst`)\n- Alpine (`.apk`)\n\nYou can install the matching package for your distro, or use the standalone binary:\n\n```bash\nchmod +x sambam-linux-amd64\nsudo mv sambam-linux-amd64 /usr/local/bin/sambam\n```\n\nOr build from source:\n\n```bash\ngo build -o sambam .\n```\n\n## Quick Start\n\n```bash\n# Share current directory (anonymous access, read-write)\nsudo sambam\n\n# Share a specific folder\nsudo sambam /path/to/folder\n\n# Share read-only with a custom name\nsudo sambam -r -n photos ~/Pictures\n```\n\n## Options\n\n### `-n, --name \u003cname\u003e` or `-n \u003cname:path\u003e`\n\nSet 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.\n\n```bash\nsudo sambam -n myfiles /data\nsudo sambam -n docs:/home/user/documents -n pics:/home/user/photos\n```\n\n### `-l, --listen \u003caddress\u003e`\n\nAddress and port to listen on. Default: `0.0.0.0:445`.  \nYou can also bind by interface with `@\u003cname\u003e` (optionally with port), for example `@eth0` or `@eth0:445`.\nRepeat the flag to bind multiple endpoints.\n\n```bash\nsudo sambam -l 0.0.0.0:8445 /data\nsudo sambam -l @eth0:445 /data\nsudo sambam -l @eth0 -l 10.23.22.13:445 /data\n```\n\n### `-a, --allow \u003cip-or-cidr\u003e`\n\nAllowlist client source addresses. Repeatable.\n\nAccepted values:\n- Single IP (`192.168.1.10`)\n- CIDR network (`192.168.1.0/24`)\n\nIf one or more `--allow` rules are set, only matching clients can connect.\n\n```bash\nsambam -a 192.168.1.10 -a 192.168.2.0/24 /data\n```\n\n### `-x, --no-advertise`\n\nBy default, sambam advertises the SMB service for LAN discovery using:\n- Bonjour/mDNS (`_smb._tcp`)\n- WS-Discovery (Windows Network discovery)\n\nPorts used by sambam:\n- `TCP 445` (SMB service)\n- `UDP 3702` (WS-Discovery probe/resolve)\n- `TCP 5357` (WS-Discovery metadata HTTP)\n\nUse `-x` / `--no-advertise` to disable discovery announcements.\n\n```bash\nsambam /data\nsambam -x /data\nsambam --no-advertise /data\n```\n\n### `-r, --readonly`\n\nShare in read-only mode. Clients can browse and copy files but cannot modify, delete, or upload.\n\n### `-u, --username \u003cuser|user:password\u003e`\n\nRequire authentication. Repeatable.\n\n- Single-user quick mode: `-u admin -p secret` (or omit `-p` for random password)\n- Multi-user CLI mode: `-u alice:secret1 -u bob:secret2`\n\n```bash\nsudo sambam -u admin /data\nsudo sambam -u admin -p secret123 /data\nsudo sambam -u alice:secret1 -u bob:secret2 /data\n```\n\n### `-p, --password \u003cpassword\u003e`\n\nSet a password for single-user CLI mode (`-u \u003cuser\u003e`).  \nFor multi-user CLI mode, use `-u \u003cuser:password\u003e` for each user.\n\n### Authentication Tiers\n\nTier 1 — quick share:\n\n```bash\nsambam /data\nsambam -u alice -p secret /data\n```\n\nTier 2 — multiple users (same access for all):\n\n```bash\nsambam -u alice:secret1 -u bob:secret2 /data\n```\n\nTier 3 — per-share permissions (config):\n\n```toml\n[[users]]\nname = \"alice\"\npassword = \"secret1\"\n\n[[users]]\nname = \"bob\"\npassword = \"secret2\"\nreadonly = true\n\n[shares.media]\npath = \"/mnt/media\"\n\n[shares.private]\npath = \"/home/user/private\"\nallow_users = [\"alice\"]\n\n[shares.public]\npath = \"/srv/public\"\nguest = true\n```\n\n### `-e, --expire \u003cduration\u003e`\n\nAutomatically stop sharing after the given duration. Accepts Go duration format: `30m`, `1h`, `2h30m`, etc.\n\n```bash\nsudo sambam --expire 30m /data\n```\n\n### `-v, --verbose`\n\nShow real-time connection and file activity.\n\nUse verbosity levels:\n- `-v` basic activity\n- `-vv` extended diagnostics (open mode, read events, close summaries, slow ops, auth failures)\n- `-vvv` full protocol trace (includes `-v` and `-vv`)\n\n```\n  15:04:05 connect 192.168.1.100:54321\n  15:04:10 [share] create file documents/report.docx\n  15:04:12 [share] create dir  backup\n  15:04:15 [share] delete temp/old-file.txt\n```\n\n### `-H, --hide-dotfiles`\n\nHide files starting with `.` from directory listings. By default dotfiles are visible.\n\n### `-d, --daemon`\n\nRun sambam as a background daemon. Use `sambam status` to inspect it and `sambam stop` to stop it.\n\n```bash\nsudo sambam -d /data\nsudo sambam status\nsudo sambam stop\n```\n\n### `-P, --pidfile \u003cpath\u003e`\n\nPID file location for daemon mode. Default: `/tmp/sambam.pid`.\n\n### `-L, --logfile [path]`\n\nLog 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.\nIf used without a value, defaults to `/tmp/sambam.log`.\n\n### `-c, --config \u003cpath\u003e`\n\nLoad config file(s) explicitly. Repeatable.\n\nWhen `-c` is used, default discovery (`/etc/sambamrc`, `~/.sambamrc`, `./.sambamrc`) is skipped.\nFiles passed via `-c` are applied in order, and CLI flags still have highest priority.\n\n```bash\nsambam -c /etc/sambam-prod.toml -c ./sambam.override.toml\n```\n\n```bash\nsudo sambam -d -L /var/log/sambam.log /data\nsudo sambam -L /tmp/sambam.log /data\n```\n\n### `-G, --gen-config [path]`\n\nGenerate a TOML config from the currently passed CLI flags and exit without starting the server.\n\n- If no path is given, writes `./.sambamrc`\n- If a path is given, writes to that file\n- Generated config includes users and shares based on passed flags\n\n```bash\nsambam -r -u admin -p secret -G\nsambam -l 10.23.22.13:445 -e 1h -G /tmp/sambamrc.toml\n```\n\n### `-V, --version`\n\nShow version and exit.\n\n### `-h, --help`\n\nShow help and exit.\n\n## Configuration File\n\nsambam has two config loading modes:\n\n1. Default mode (no `-c`): `/etc/sambamrc` -\u003e `~/.sambamrc` -\u003e `./.sambamrc`\n2. Explicit mode (with `-c`): only the provided `-c, --config \u003cpath\u003e` files, in order (required to exist)\n\nCLI flags override all config values.\n\n### Configuration Layout\n\n```toml\nlisten = \"0.0.0.0:445\"\n# listen_addrs = [\"@eth0:445\", \"10.23.22.13:445\"]\n\nallow = [\"10.23.0.0/16\"]\nadvertise = true\nreadonly = false\nhide_dotfiles = false\n\nverbose = true\n# verbose_level = 2\n# verbose_level = 3\ndebug = false\ntrace = false\n\nexpire = \"1h\"\npidfile = \"/tmp/sambam.pid\"\nlogfile = \"/tmp/sambam.log\"\n\n[[users]]\nname = \"alice\"\npassword = \"secret1\"\nreadonly = false\n\n[[users]]\nname = \"bob\"\npassword = \"secret2\"\nreadonly = true\n\n[shares.docs]\npath = \"/tmp/docs\"\nallow_users = [\"alice\", \"bob\"]\nreadonly = false\n\n[shares.private]\npath = \"/tmp/private\"\nallow_users = [\"alice\"]\nreadonly = true\n\n[shares.public]\npath = \"/tmp/public\"\nguest = true\nreadonly = false\n```\n\nGlobal options:\n- `listen` / `listen_addrs`\n- `allow`\n- `advertise` (default: `true`)\n- `hide_dotfiles`\n- `readonly`\n- `expire`\n- `pidfile`\n- `logfile`\n- `verbose` / `verbose_level`\n\nPer-user options (`[[users]]`):\n- `name`\n- `password`\n- `readonly`\n\nPer-share options (`[shares.\u003cname\u003e]`):\n- `path`\n- `readonly`\n- `guest`\n- `allow_users`\n\nNotes:\n- `guest = true` allows anonymous access for that share.\n- `allow_users` restricts a share to specific authenticated users.\n\nSee `sambamrc.example` for a full example.\n\n### Troubleshooting config selection\n\nRun with verbosity to see exactly which config files were loaded:\n\n```bash\nsambam -v\n```\n\nYou will see a line like:\n\n```text\nconfig: system=true (/etc/sambamrc), home=true (/root/.sambamrc), local=true (.sambamrc), custom=0\n```\n\n## Connecting from Windows\n\nOnce sambam is running, it shows you the exact path to use:\n\n```\n  sambam v1.2.6\n\n  Sharing      /home/user/documents\n  Share        share\n  Listen       0.0.0.0:445\n  Mode         read-write\n  Auth         anonymous\n\n  Connect from Windows:\n    \\\\192.168.1.100\\share\n\n  Built with AI assistance\n\n  Press Ctrl+C to stop\n```\n\nFrom Windows:\n1. Open **File Explorer**\n2. Type the path in the address bar: `\\\\192.168.1.100\\share`\n3. Press Enter\n4. If authentication is required, enter the username and password\n\nOr mount as a drive:\n```cmd\nnet use Z: \\\\192.168.1.100\\share /user:admin\n```\n\n## Connecting from Linux\n\nMount using CIFS with SMB 3.0:\n\n```bash\n# Anonymous access\nsudo mount -t cifs //server-ip/share /mnt/share -o guest,vers=3.0\n\n# With authentication\nsudo mount -t cifs //server-ip/share /mnt/share -o username=admin,password=secret123,vers=3.0\n```\n\n### POSIX extensions (real Unix permissions)\n\nsambam supports SMB2 POSIX extensions, which let Linux clients see real Unix permissions, owners, and use `chmod`/`chown`. This requires SMB 3.1.1:\n\n```bash\n# POSIX mount with chmod/chown support\nsudo mount -t cifs //server-ip/share /mnt/share -o guest,vers=3.1.1,posix,cifsacl\n```\n\nWith 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.\n\n## Windows Credential Troubleshooting\n\nWindows caches SMB credentials. If you're having authentication issues:\n\n```cmd\n# List active connections\nnet use\n\n# Disconnect a specific share\nnet use \\\\192.168.1.100\\share /delete\n\n# Or disconnect all shares\nnet use * /delete\n```\n\nAfter clearing cached connections, reconnect and Windows will prompt for new credentials.\n\n## Non-standard ports\n\nPort 445 requires root. You can use a non-standard port instead:\n\n```bash\nsambam -l :8888 /data\n```\n\n**Linux clients** support non-standard ports natively:\n\n```bash\nsudo mount -t cifs //server-ip/share /mnt -o guest,port=8888\n```\n\n**Windows and macOS** only connect to port 445. To use a non-standard port, create an SSH tunnel:\n\n```bash\n# Forward local port 445 to the sambam server\nssh -L 445:server-ip:8888 user@server-ip\n```\n\nThen connect to `\\\\localhost\\share` (Windows) or `smb://localhost/share` (macOS).\n\nOn 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:\n\n```bash\n# Inside WSL — find WSL's IP with: ip addr show eth0\nssh -L 172.x.x.x:445:server-ip:8888 user@server-ip\n```\n\nThen connect from Windows using `\\\\172.x.x.x\\share` (the WSL IP).\n\n## Requirements\n\n- **Root privileges** - Port 445 requires root (or use `-l :8888` for a non-standard port)\n- **Linux server** - Works on any distribution (Debian, Ubuntu, OpenWrt, Alpine, etc.)\n- **Clients** - Windows 10/11, macOS, or Linux (via CIFS mount)\n\n## Known Issues\n\nThese notes apply to the **sambam server** (the application serving files), not to client applications (Windows Explorer, macOS Finder, Linux mount tools, etc.).\n\n### Platform-Specific Notes\n\n**Linux** - Fully stable. All features working including POSIX extensions, file permissions, and advanced operations.\n\n**macOS (Apple Silicon)** - Excellent support. Thoroughly tested and works as reliably as Linux. All features including POSIX extensions fully functional. No known issues.\n\n**Windows** - Experimental server build\n- No POSIX extensions support (limitations on Unix-style permissions)\n- File deletion issues: Files cannot be deleted while the server is running (Windows file locking behavior)\n- Other features work correctly\n\n## Security Notice\n\nBy default, sambam uses anonymous/guest authentication. This means:\n\n- **No passwords** - Anyone on your network can access the share\n- **Use on trusted networks only** - Don't run this on public WiFi\n- **Not for production** - This is for quick file transfers, not Fort Knox\n\nFor sensitive shares, use `--username` to require authentication, and `-r` for read-only mode.\n\n## License\n\nAGPL-3.0\n\n---\n*Made for those moments when you just need to share a damn file.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarkpenguin23%2Fsambam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdarkpenguin23%2Fsambam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarkpenguin23%2Fsambam/lists"}