This documentation is part of the "Projects with Books" initiative at zenOSmosis.
The source code for this project is available on GitHub.
Technical Specifications
Relevant source files
This page provides reference information for all technical specifications used in sshfs-mac-docker, including port numbers, file paths, protocol versions, user IDs, permissions, and configuration parameters. This is intended as a quick reference for developers and system administrators who need precise technical details.
For detailed explanations of how these specifications are applied in practice, see Configuration Reference. For architectural context explaining why these specifications were chosen, see Architecture.
Network Specifications
Port Configuration
The system uses two standard SMB/CIFS ports that are exposed from the container to the macOS host:
| Port | Protocol | Purpose | Binding | Exposure |
|---|---|---|---|---|
| 139 | TCP | NetBIOS Session Service | 127.0.0.1:139 | Localhost only |
| 445 | TCP | SMB over TCP (Direct hosting) | 127.0.0.1:445 | Localhost only |
| 22 | TCP | SSH (outbound from container) | N/A | Remote connection |
The port mappings are configured via Docker run command as specified in README.md31:
-p 127.0.0.1:139:139 -p 127.0.0.1:445:445
Both ports are exposed in the Dockerfile at Dockerfile27:
EXPOSE 139 445
Network Architecture Diagram
Sources: README.md31 README.md34 README.md:57-61 Dockerfile27
Container IP Discovery
The container IP address is dynamically assigned by Docker and must be discovered at runtime using:
This command is documented in README.md60
Network Limitation: The SMB client on macOS cannot connect using localhost or 127.0.0.1 despite the port forwarding. Connections must use the container's internal Docker IP address (e.g., 172.17.0.2), as noted in README.md57
Sources: README.md:57-61
Filesystem Specifications
Directory Structure
The container uses a specific directory hierarchy to integrate SSHFS mounts with Samba shares:
| Path | Type | Permissions | Owner | Purpose |
|---|---|---|---|---|
/remote | Directory | Default (created by mkdir) | root | SSHFS mount point |
/samba-share | Directory | 777 (rwxrwxrwx) | root | Samba share root |
/samba-share/remote | Symbolic Link | N/A | root | Link to /remote |
Sources: Dockerfile12 Dockerfile15 Dockerfile21 Dockerfile30 smb.conf11 README.md49
Permission Specifications
| Component | Permission | Octal | Specification |
|---|---|---|---|
/samba-share directory | rwxrwxrwx | 0777 | Dockerfile21 |
| SSHFS mounted files | Controlled by mount options | N/A | See SSHFS Mount Options |
| Samba share create mask | rwxrwxrwx | 0777 | smb.conf17 |
| Samba share directory mask | rwxrwxrwx | 0777 | smb.conf18 |
The broad permissions on /samba-share are necessary because the Samba service must write to this directory on behalf of guest users, which are force-mapped to sshuser via smb.conf19
Sources: Dockerfile21 smb.conf:17-19
User and Group Specifications
User Account
A single non-root user account is created during image build:
| Parameter | Value | Source |
|---|---|---|
| Username | sshuser | Dockerfile9 |
| Password | sshpass | Dockerfile9 |
| UID | 1000 (default) | Implicitly assigned by useradd -m |
| GID | 1000 (default) | Implicitly assigned by useradd -m |
| Home Directory | /home/sshuser | Created by useradd -m flag |
The user is created via: Dockerfile9
useradd -m sshuser && echo "sshuser:sshpass" | chpasswd
User ID Mapping
Sources: Dockerfile9 smb.conf4 smb.conf19 README.md49
Protocol Specifications
SMB/CIFS Protocol
| Configuration Key | Value | Source | Purpose |
|---|---|---|---|
workgroup | WORKGROUP | smb.conf2 | NetBIOS workgroup name |
security | user | smb.conf3 | Security mode |
map to guest | bad user | smb.conf4 | Map unknown users to guest |
client min protocol | SMB2 | smb.conf7 | Minimum client protocol version |
server min protocol | SMB2 | smb.conf8 | Minimum server protocol version |
server string | Samba Server %v | smb.conf5 | Server identification string |
netbios name | sambaserver | smb.conf6 | NetBIOS server name |
The protocol enforcement prevents fallback to SMB1, which has known security vulnerabilities.
Sources: smb.conf:1-9
SSH Protocol
| Parameter | Value | Notes |
|---|---|---|
| Port | 22 (default) | Standard SSH port |
| Protocol | SSH-2 | Used by sshfs command |
| Authentication | User-specified | Passed via user@host syntax |
| Connection Type | FUSE-based | Filesystem operations over SSH |
The SSH connection is established by the sshfs command as documented in README.md49
Sources: README.md49
SSHFS Mount Specifications
Required Mount Options
The following options must be specified for proper system operation:
| Option | Value | Purpose | Source |
|---|---|---|---|
allow_other | Flag | Allows non-mounting user (Samba) to access mount | README.md52 |
uid | 1000 | Sets file ownership to sshuser | README.md53 |
gid | 1000 | Sets group ownership to sshuser | README.md53 |
Complete mount command syntax from README.md49:
Critical Dependencies:
allow_otherrequiresuser_allow_otherenabled in/etc/fuse.conf(Dockerfile24)uid=1000,gid=1000must match the UID/GID ofsshuserfor write access- Without these options, the mount will be read-only or inaccessible to Samba
Sources: README.md:49-53 Dockerfile24
FUSE Configuration
FUSE (Filesystem in Userspace) requires specific configuration to enable cross-user access:
| Configuration File | Setting | Value | Purpose |
|---|---|---|---|
/etc/fuse.conf | user_allow_other | Enabled | Permits non-root users to use allow_other flag |
This is configured via Dockerfile24:
Without this configuration, the allow_other mount option would be rejected by FUSE.
Sources: Dockerfile24
Container Runtime Specifications
Required Privileges
The container must run with elevated privileges:
| Flag | Value | Purpose | Source |
|---|---|---|---|
--privileged | Required | Enables FUSE filesystem operations | README.md31 |
The privileged mode is necessary because FUSE requires access to /dev/fuse and the ability to perform mount operations, which are restricted in standard containers.
Sources: README.md31
Container Command
The container runs Samba as its primary process:
smbd --foreground --no-process-group --debug-stdout
| Argument | Purpose |
|---|---|
--foreground | Runs smbd in foreground (required for Docker) |
--no-process-group | Prevents process group creation |
--debug-stdout | Sends debug output to stdout |
This is specified in Dockerfile33
Sources: Dockerfile33
Samba Share Specifications
Share Configuration
The share named "SSHFS Share" has the following configuration from smb.conf:10-20:
| Parameter | Value | Purpose |
|---|---|---|
path | /samba-share | Root directory of share |
writable | yes | Allows write operations |
guest ok | yes | Permits guest access |
guest only | yes | Forces guest authentication |
read only | no | Explicitly enables writing |
browseable | yes | Share visible in network browser |
create mask | 0777 | Default permissions for new files |
directory mask | 0777 | Default permissions for new directories |
force user | sshuser | All operations performed as this user |
Sources: smb.conf:10-20
Package Specifications
Installed Packages
The following packages are installed via apt-get in Dockerfile:5-6:
| Package | Purpose | Version |
|---|---|---|
sshfs | SSHFS client for mounting remote filesystems over SSH | Latest from Ubuntu repository |
samba | SMB/CIFS server for file sharing | Latest from Ubuntu repository |
Base Image
| Specification | Value |
|---|---|
| Base Image | ubuntu:latest |
| Source | Dockerfile2 |
Sources: Dockerfile2 Dockerfile:5-6
Command Reference Summary
Docker Commands
| Command | Purpose | Source |
|---|---|---|
docker build -t docker-sshfs . | Build container image | README.md22 |
docker run --privileged --name docker-sshfs -p 127.0.0.1:139:139 -p 127.0.0.1:445:445 docker-sshfs | Start container | README.md31 |
docker exec -it docker-sshfs bash | Access container shell | README.md41 |
docker inspect --format '{{ .NetworkSettings.IPAddress }}' docker-sshfs | Get container IP | README.md60 |
SSHFS Commands
| Command | Purpose | Source |
|---|---|---|
sshfs -o allow_other,uid=1000,gid=1000 user@host:path /remote | Mount remote filesystem | README.md49 |
fusermount -u /samba-share | Unmount filesystem | README.md76 |
Sources: README.md22 README.md31 README.md41 README.md49 README.md60 README.md76
Platform Requirements
Recommended Platform
| Requirement | Specification | Notes |
|---|---|---|
| Platform | OrbStack | Highly recommended for network compatibility |
| Alternative | Docker Desktop | Requires network routing modifications |
| macOS Version | Any version supporting Docker | No macFUSE required |
The recommendation for OrbStack over Docker Desktop is documented in README.md9 due to networking compatibility issues with Docker Desktop's SMB client integration.
Sources: README.md9
Error Messages and Codes
Known Error Conditions
| Error Message | Cause | Resolution |
|---|---|---|
fusermount: failed to unmount /samba-share: Device or resource busy | Samba share still mounted on macOS | Unmount from Finder first, or stop container |
This error is documented in README.md:82-85
Sources: README.md:82-85