This documentation is part of the "Projects with Books" initiative at zenOSmosis.

The source code for this project is available on GitHub.

Connection Problems

Relevant source files

Purpose and Scope

This page addresses common connection issues when attempting to access the Samba share from macOS Finder. It covers troubleshooting the specific network and authentication configurations required for successful SMB connections to the Docker container.

For platform-specific networking issues with Docker Desktop, see Platform-Specific Issues. For problems unmounting active shares, see Device or Resource Busy Errors.

Connection Problem Symptoms

Users typically encounter connection problems in the following scenarios:

Symptom	Likely Cause
"Connection failed" when using `smb://localhost`	Localhost limitation - must use container IP
"Connection failed" when using `smb://127.0.0.1`	Same localhost limitation
Cannot find container IP address	Container not running or incorrect inspection command
Authentication dialog appears and rejects credentials	Attempting to use registered user instead of Guest
Connection refused on SMB ports	Port forwarding not configured or ports already in use
Network timeout when connecting	Docker Desktop networking issue (requires OrbStack)

Sources : README.md:57-69

The Localhost Limitation

Problem Description

Despite port forwarding configured with -p 127.0.0.1:139:139 -p 127.0.0.1:445:445 in README.md31 macOS Finder's SMB client cannot successfully connect using smb://localhost or smb://127.0.0.1. This is a known limitation of how Docker's port forwarding interacts with macOS's SMB client implementation.

graph TB
    subgraph "Attempted Connection (Fails)"
        FinderA["macOS Finder"]
LocalhostA["smb://localhost or\nsmb://127.0.0.1"]
PortForwardA["Port Forward\n-p 127.0.0.1:139:139\n-p 127.0.0.1:445:445"]
FailureA["❌ Connection Refused"]
FinderA --> LocalhostA
 
       LocalhostA --> PortForwardA
 
       PortForwardA --> FailureA
    end
    
    subgraph "Working Connection (Required)"
        FinderB["macOS Finder"]
ContainerIPB["smb://172.17.0.2\n(container IP)"]
DockerNetB["Docker Bridge Network\ndocker0"]
SmbdB["smbd process\nPorts 139/445"]
SambaShareB["/samba-share"]
FinderB --> ContainerIPB
 
       ContainerIPB --> DockerNetB
 
       DockerNetB --> SmbdB
 
       SmbdB --> SambaShareB
    end
    
    subgraph "IP Discovery"
        InspectCmd["docker inspect\n--format '{{ .NetworkSettings.IPAddress }}'\ndocker-sshfs"]
OutputIP["172.17.0.2"]
InspectCmd --> OutputIP
    end

Network Path Analysis

Diagram : Network path comparison showing why localhost fails and container IP succeeds

The port forwarding defined in Dockerfile27 (EXPOSE 139 445) and mapped in the docker run command README.md31 forwards traffic to 127.0.0.1 on the host, but the SMB protocol requires direct access to the container's IP address within the Docker bridge network.

Sources : README.md31 README.md57 Dockerfile27

IP Address Discovery

Primary Method

The recommended approach uses docker inspect with a format template:

This command queries the container's network configuration and extracts the IPAddress field from the NetworkSettings object. The output is typically in the form 172.17.0.x for default Docker bridge networks.

Sources : README.md60

Alternative Discovery Methods

If the primary method fails or returns an empty string, try these alternatives:

Method	Command	When to Use
Full inspect output	`docker inspect docker-sshfs`	Review complete network configuration
Network listing	`docker network inspect bridge`	Check bridge network configuration
Container stats	`docker ps` with wide output	Verify container is running
OrbStack UI	Check OrbStack dashboard	When using OrbStack instead of Docker Desktop

Container Not Running Issue

If docker inspect returns no output or error:

Diagram : Diagnostic workflow for IP address discovery failures with specific commands

Sources : README.md:59-61 README.md31

Authentication Configuration

Guest Access Requirement

The Samba configuration in smb.conf:3-4 and smb.conf:13-14 enforces guest-only access:

[global]
security = user
map to guest = bad user

[SSHFS Share]
guest ok = yes
guest only = yes

This configuration means:

map to guest = bad user: Any authentication attempt with invalid credentials is mapped to guest access
guest ok = yes: Anonymous guest connections are permitted
guest only = yes: All connections are forced to guest mode, regardless of credentials provided

Connection Procedure

When connecting from macOS Finder README.md:63-67:

Navigate to Finder → Go → Connect to Server
Enter smb://172.17.0.2 (using discovered container IP)
When authentication dialog appears, select Connect as Guest
Do not attempt to enter username/password - the configuration does not support registered users

graph TB
    subgraph "Samba Authentication Flow"
        FinderReq["Finder SMB Request"]
SmbGlobal["smb.conf [global]\nsecurity = user\nmap to guest = bad user"]
AuthCheck{"Valid\ncredentials?"}
MapGuest["Map to guest"]
ShareConfig["[SSHFS Share]\nguest ok = yes\nguest only = yes\nforce user = sshuser"]
AccessGranted["Access granted as sshuser"]
FinderReq --> SmbGlobal
 
       SmbGlobal --> AuthCheck
 
       AuthCheck -->|No| MapGuest
 
       AuthCheck -->|N/A guest mode| MapGuest
 
       MapGuest --> ShareConfig
 
       ShareConfig --> AccessGranted
    end
    
    subgraph "Common Mistakes"
        UserPass["Attempting\nusername/password"]
RegisteredUser["Selecting\nregistered user"]
Rejection["❌ Authentication\nRejected"]
UserPass --> Rejection
 
       RegisteredUser --> Rejection
    end

Authentication Failure Scenarios

Diagram : Samba authentication flow showing smb.conf directives and their effects

The force user = sshuser directive in smb.conf19 ensures that all file operations, regardless of connection method, execute with sshuser identity (UID 1000 from Dockerfile9).

Sources : smb.conf:3-4 smb.conf:13-14 smb.conf19 README.md67 Dockerfile9

Port Binding Issues

Verifying Port Availability

The container requires exclusive access to ports 139 and 445 on the host. If another service is using these ports, the container will fail to start or Samba will fail to bind.

Check port usage before starting the container:

Common port conflicts:

Port 445 : Windows File Sharing or other SMB servers on macOS
Port 139 : NetBIOS services or legacy SMB implementations

Port Forwarding Configuration

The port mapping in README.md31 explicitly binds to 127.0.0.1:

This configuration:

Forwards host port 139 → container port 139
Forwards host port 445 → container port 445
Restricts access to localhost only (security measure)
Does not work with the SMB client connecting to 127.0.0.1 (see localhost limitation above)

To verify port forwarding is active:

Expected output:

139/tcp -> 127.0.0.1:139
445/tcp -> 127.0.0.1:445

Sources : README.md31 README.md34 Dockerfile27

Docker Desktop Network Routing

Known Limitation

README.md9 explicitly warns:

Note: It is highly recommended to use OrbStack. Docker Desktop will not work for this without modifying the network routing.

Why Docker Desktop Fails

Docker Desktop on macOS uses a virtual machine (HyperKit or QEMU) with NAT networking. The SMB protocol's direct IP addressing requirements conflict with Docker Desktop's network isolation model. The container's IP address exists within the VM's network namespace, which is not directly accessible from the macOS host without additional routing configuration.

graph TB
    subgraph "OrbStack (Recommended)"
        MacOSA["macOS Host"]
OrbStackNet["OrbStack Network\nDirect Integration"]
ContainerA["docker-sshfs Container\nIP: 172.17.0.2"]
SmbdA["smbd\nPorts 139/445"]
MacOSA -->|Direct SMB access| OrbStackNet
 
       OrbStackNet --> ContainerA
 
       ContainerA --> SmbdA
    end
    
    subgraph "Docker Desktop (Requires Modification)"
        MacOSB["macOS Host"]
HyperKit["HyperKit/QEMU VM"]
NATLayer["NAT Networking"]
ContainerB["docker-sshfs Container\nIP: 172.17.0.2"]
SmbdB["smbd\nPorts 139/445"]
BlockB["❌ Network isolation\nprevents SMB"]
MacOSB --> HyperKit
 
       HyperKit --> NATLayer
 
       NATLayer --> ContainerB
 
       ContainerB --> SmbdB
 
       NATLayer -.->|Blocked| BlockB
    end

Network Architecture Comparison

Diagram : Network architecture differences between OrbStack and Docker Desktop affecting SMB connectivity

Mitigation for Docker Desktop

If OrbStack cannot be used, modify Docker Desktop's network routing to bridge the VM network to the host. This is beyond the scope of this project and requires advanced Docker Desktop configuration. Consider using OrbStack as specified in the prerequisites README.md9

Sources : README.md9

Step	Command/Action	Expected Result
1. Container running	`docker ps	grep docker-sshfs`
2. Samba process active	`docker exec docker-sshfs pgrep smbd`	Returns process ID
3. SSHFS mounted	`docker exec docker-sshfs mount	grep sshfs`
4. Get container IP	`docker inspect --format '{{ .NetworkSettings.IPAddress }}' docker-sshfs`	Returns IP like `172.17.0.x`
5. Verify ports	`docker port docker-sshfs`	Shows `139/tcp` and `445/tcp` mappings

Connection Attempt

Step	Action	Configuration
1. Open Finder	Go → Connect to Server	N/A
2. Enter address	`smb://172.17.0.2`	Use discovered container IP, not localhost
3. Authenticate	Connect as Guest	Do not use registered user
4. Verify mount	Check Network in Finder sidebar	Share appears as `sambaserver`
5. Access files	Navigate to `remote` folder	Contents of SSHFS mount visible

Sources : README.md:55-69 smb.conf6

Advanced Diagnostics

Testing SMB Connectivity

From macOS terminal, test SMB availability:

Expected output from nc:

Connection to 172.17.0.2 port 445 [tcp/microsoft-ds] succeeded!

Inspecting Samba Logs

Check Samba server logs for connection attempts:

Look for:

Connection attempts from macOS IP
Authentication successes/failures
Share access denials

Verifying Configuration Files

Confirm Samba configuration is correctly loaded:

This command runs the Samba parameter verification tool against smb.conf:1-20 and displays the active configuration, highlighting any syntax errors or warnings.

Sources : smb.conf:1-20 Dockerfile18

Summary of Common Solutions

Problem	Solution	Reference
Cannot connect to `smb://localhost`	Use container IP from `docker inspect`	README.md:57-61
Cannot find container IP	Verify container is running with `docker ps`	README.md31
Authentication fails	Connect as Guest , not registered user	README.md67 smb.conf:13-14
Connection timeout with Docker Desktop	Switch to OrbStack	README.md9
Port binding fails	Check for conflicts on 139/445 with `lsof`	README.md31
Container runs but no SMB	Verify `smbd` process with `docker exec docker-sshfs pgrep smbd`	Dockerfile33
Files not visible	Ensure SSHFS mounted with `allow_other` flag	README.md49

Sources : README.md9 README.md31 README.md49 README.md:57-67 smb.conf:13-14 Dockerfile33

sshfs-mac-docker Documentation