This documentation is part of the "Projects with Books" initiative at zenOSmosis.
The source code for this project is available on GitHub.
Running the Container
Relevant source files
This page explains how to start the docker-sshfs container with the correct privileges and network configuration. It covers the docker run command, required flags, port mappings, and what happens during container startup. For information about building the container image, see Building the Container. For information about using the container to mount remote filesystems, see Mounting Remote Filesystems.
Purpose and Prerequisites
Running the container requires an already-built docker-sshfs image. The container must be started with specific privileges and port configurations to enable FUSE operations and Samba network access. This page assumes Docker or OrbStack is installed and the image has been built as described in Prerequisites and Platform Requirements and Building the Container.
The docker run Command
The container is started using the following command:
This command runs in the foreground and should be executed in a dedicated terminal session, as the Samba daemon (smbd) runs in foreground mode and will occupy the terminal.
Sources: README.md:30-32
Command Flags and Configuration
Container Runtime Configuration
Sources: README.md:30-34 Dockerfile:26-27
Flag Details
| Flag | Purpose | Why Required |
|---|---|---|
--privileged | Grants container access to host devices, specifically /dev/fuse | SSHFS requires FUSE operations which need device access. Without this flag, the sshfs command will fail with permission errors when attempting to mount filesystems |
--name docker-sshfs | Assigns a fixed name to the container | Enables consistent container identification for subsequent docker exec, docker inspect, and docker stop commands |
-p 127.0.0.1:139:139 | Maps container port 139 to host port 139, bound to localhost only | Exposes NetBIOS Session Service for SMB connections. The 127.0.0.1 binding prevents external network access |
-p 127.0.0.1:445:445 | Maps container port 445 to host port 445, bound to localhost only | Exposes SMB over TCP for modern SMB protocol versions (SMB2+). The 127.0.0.1 binding provides security isolation |
docker-sshfs | Image name to instantiate | References the image built in Building the Container |
Sources: README.md:30-34 Dockerfile:26-27
Container Startup Process
Service Initialization Sequence
Sources: README.md:28-34 Dockerfile33
Executed Command
When the container starts, Docker executes the CMD directive specified in the Dockerfile:
Command Flag Breakdown:
| Flag | Purpose |
|---|---|
--foreground | Keeps smbd running in the foreground rather than daemonizing. This is required for Docker containers because the container stops when the main process exits |
--no-process-group | Prevents smbd from creating a new process group, ensuring proper signal handling in the container environment |
--debug-stdout | Sends log output to stdout, making logs visible via docker logs and the terminal running docker run |
Sources: Dockerfile33
Port Binding and Network Access
Port Configuration Map
Sources: README.md:30-34 Dockerfile:26-27
Localhost Binding Rationale
The port mappings use 127.0.0.1: prefix rather than binding to all interfaces (0.0.0.0). This provides security isolation:
- External Access Prevention: Samba ports are not exposed to the host's external network interfaces
- Security Constraint: Only processes running on the macOS host can connect to the mapped ports
- Recommended Practice: Prevents accidental exposure of the Samba share to network-accessible machines
However, there is a known limitation: macOS Finder cannot connect to smb://127.0.0.1 due to how Docker's network bridge interacts with macOS's SMB client. The workaround requires connecting to the container's internal Docker IP address, which is covered in Connecting from macOS.
Sources: README.md34 README.md:57-61
Container State After Startup
Filesystem and Service Availability
Once the container is running, the following state is established:
| Component | State | Details |
|---|---|---|
/dev/fuse | Mounted | Available due to --privileged flag |
/remote directory | Created, empty | Mount point for SSHFS, created during image build |
/samba-share directory | Created, permissions 777 | Samba root directory with symbolic link to /remote |
/samba-share/remote | Symbolic link | Links to /remote, created during image build |
smbd process | Running, foreground | Listening on ports 139 and 445 |
| Samba share | Available | Named "SSHFS Share", serving /samba-share |
| SSHFS mount | Not mounted | Requires manual mounting via docker exec, covered in Mounting Remote Filesystems |
Sources: Dockerfile12 Dockerfile15 Dockerfile21 Dockerfile30 Dockerfile33
Container Lifecycle Management
Starting and Stopping
Sources: README.md:26-34 README.md:73-86
Common Operations
Starting the container:
Stopping the container (from another terminal):
Stopping the container (from the terminal running docker run):
Ctrl+C
Restarting a stopped container:
The -a flag attaches to the container's stdout, allowing you to see smbd logs.
Removing the container:
Sources: README.md:30-32
Verification Steps
After starting the container, verify that services are running correctly:
Check Container Status
Expected output should show docker-sshfs with status "Up" and port mappings 127.0.0.1:139->139/tcp, 127.0.0.1:445->445/tcp.
Check Container Logs
In the terminal running docker run, smbd logs will be displayed due to the --debug-stdout flag. Look for lines indicating successful startup and port binding.
Verify Port Bindings
From another terminal:
Expected output:
139/tcp -> 127.0.0.1:139
445/tcp -> 127.0.0.1:445
Test Container Access
This drops you into a bash shell inside the running container. Exit with exit or Ctrl+D. This verification confirms the container is running and accessible for subsequent SSHFS mount operations described in Mounting Remote Filesystems.
Sources: README.md:40-42
Next Steps
With the container running, proceed to Mounting Remote Filesystems to connect to remote SSH servers via SSHFS, or see Connecting from macOS to access the Samba share from Finder.