Connecting from macOS

Relevant source files

• README.md
• smb.conf

Purpose and Scope

This page guides users through connecting to the Samba share from macOS Finder after the container is running and the remote filesystem has been mounted. This is the final step in making remote files accessible through macOS's native file browser.

For information about starting the container, see Running the Container. For information about mounting the remote filesystem via SSHFS, see Mounting Remote Filesystems. For troubleshooting connection issues, see Connection Problems.

Sources : README.md:55-70

Prerequisites

Before connecting from macOS, ensure the following conditions are met:

If any prerequisite is not met, the connection will fail silently or show authentication errors.

Sources : README.md:26-54

Discovering the Container IP Address

macOS Finder cannot connect to the Samba share using localhost or 127.0.0.1, despite the port forwarding configuration in docker run -p 127.0.0.1:139:139 -p 127.0.0.1:445:445. 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

Obtaining the Container IP

Execute the following command to retrieve the container's internal Docker network IP address:

Example output :

flowchart LR
    Finder["macOS Finder\nSMB Client"]
Localhost["localhost:445\nPort Forward"]
DockerBridge["Docker Bridge\nNetwork"]
Container["Container IP\n(e.g., 172.17.0.2)"]
Samba["smbd Process\nPorts 139/445"]
Finder -->|❌ Attempts| Localhost
 
   Localhost -.->|Port Forward Incompatibility| Container
    
 
   Finder -->|✓ Direct Connection| DockerBridge
 
   DockerBridge --> Container
 
   Container --> Samba

172.17.0.2

The IP address is dynamically assigned by Docker and may change between container restarts. Always retrieve the current IP before attempting to connect.

Why Localhost Doesn't Work

Diagram : Network routing showing that Finder must connect directly to the container's Docker bridge IP, bypassing localhost port forwarding.

The port forwarding to 127.0.0.1 serves to restrict external network access (security), but does not enable localhost connectivity for SMB protocol negotiation.

Sources : README.md:57-61

Connecting via Finder

Step-by-Step Connection Process

Diagram : Complete sequence of user interactions and protocol negotiations during the connection process.

Detailed Steps

1. Open Finder on macOS

2. Access Server Connection Dialog

   • Press ⌘K (Cmd+K), or
   • Navigate to menu bar: Go → Connect to Server

3. Enter Server Address

   • Input: smb://<container-ip> where <container-ip> is the IP obtained from docker inspect
   • Example: smb://172.17.0.2
   • Click Connect

4. Select Authentication Method

   • When prompted, select Guest radio button
   • Do not enter username/password
   • Click Connect

5. Share Selection

   • If multiple shares exist, select SSHFS Share
   • Click OK

The connection process typically completes in 1-3 seconds. If authentication fails, verify the Samba configuration allows guest access (see section below).

Sources : README.md:63-68

Authentication and Guest Access

Guest Authentication Configuration

The Samba service is configured to accept guest connections without password authentication. This configuration is defined in smb.conf:1-20:

Authentication Flow

Diagram : Authentication and identity mapping flow from macOS guest connection to remote filesystem operations.

Security Implications

The force user = sshuser directive smb.conf19 ensures all filesystem operations execute with consistent permissions:

• Benefit : Simplifies permission management; no need to coordinate macOS user IDs with remote server IDs
• Limitation : All users connecting to the share have identical access rights
• Mitigation : Port forwarding restricted to 127.0.0.1 prevents external network access README.md31

The guest access model is appropriate for development and personal use where the macOS host is trusted. For multi-user or production scenarios, consider implementing authenticated access (requires modifications to smb.conf:3-4).

Sources : smb.conf:1-20 README.md67

Accessing Remote Files in Finder

flowchart LR
    subgraph "Finder Locations"
        Sidebar["Finder Sidebar\n'Network' Section"]
Network["Network View\nCmd+Shift+K"]
Volumes["Volumes View\n/Volumes/"]
end
    
    subgraph "Share Contents"
        SSHFSShare["SSHFS Share\n(Mount Point)"]
RemoteDir["remote/\n(Directory)"]
RemoteFiles["Remote Files\n(via Symbolic Link)"]
end
    
 
   Sidebar --> SSHFSShare
 
   Network --> SSHFSShare
 
   Volumes --> SSHFSShare
    
 
   SSHFSShare --> RemoteDir
 
   RemoteDir --> RemoteFiles
    
    ContainerPath["/samba-share/remote\n(Container Path)"]
SymLink["Symbolic Link\n/samba-share/remote → /remote"]
RemoteFiles -.->|Maps to| SymLink
 
   SymLink -.->|Points to| ContainerPath

Mounted Share Location

After successful connection, the Samba share appears in multiple locations within Finder:

Diagram : Filesystem hierarchy showing how remote files appear in macOS Finder through the Samba share and symbolic link integration.

Navigation Path

1. Sidebar Access

   • Finder sidebar → Network section
   • Look for container IP (e.g., 172.17.0.2)
   • Click to expand

2. Share Contents

   • Top level shows SSHFS Share directory
   • Navigate to remote subdirectory
   • Contents are the mounted remote filesystem

3. Direct Volume Path

   • Accessible at /Volumes/SSHFS Share/remote/
   • Usable in Terminal and CLI tools

Share Mapping

The symbolic link at samba-share/remote (created during container initialization) provides transparent access to the SSHFS mount point at remote

Sources : README.md:69-70

File Operations and Performance

Supported Operations

All standard macOS file operations function through the SMB connection:

Performance Characteristics

Diagram : Complete data path showing protocol translation layers from macOS application to remote SSH server.

Performance Considerations :

• Latency : Each file operation traverses 6+ layers (SMB → Samba → symlink → FUSE → SSHFS → SSH)
• Throughput : Limited by SSH connection bandwidth and encryption overhead
• Caching : Minimal; most operations query remote server directly
• Best Use Case : Occasional file access and editing, not high-throughput data processing

For large file transfers or high-frequency operations, consider using native SSH tools (scp, rsync) instead of mounting the filesystem.

Sources : README.md:1-5 smb.conf:11-19

Connection Verification

Confirming Successful Connection

After connecting, verify the setup with the following checks:

1. Check Finder Sidebar

2. Verify Mount Point

Expected output :

//GUEST@172.17.0.2/SSHFS Share on /Volumes/SSHFS Share (smbfs, nodev, nosuid, mounted by username)

3. Test File Listing

Should display files from the remote SSH server mounted via SSHFS at remote

4. Test Write Access

If write fails, verify SSHFS was mounted with uid=1000,gid=1000 options (see Mounting Remote Filesystems).

Connection State Diagram

Diagram : State transitions during the macOS connection lifecycle, from initial disconnected state through successful mounting to active use.

Sources : README.md:55-70

Common Connection Parameters

SMB URL Format

smb://<container-ip>/<share-name>

Valid URLs :

• smb://172.17.0.2 (auto-selects share)
• smb://172.17.0.2/SSHFS Share (explicit share)

Invalid URLs :

• smb://localhost (port forwarding incompatibility)
• smb://127.0.0.1 (same issue as localhost)
• smb://docker-sshfs (DNS name not resolvable)

Protocol Versions

The Samba service enforces SMB2 or later smb.conf:7-8:

This ensures compatibility with modern macOS versions (10.12+) while disabling insecure SMB1 protocol. macOS automatically negotiates the highest supported protocol version during connection.

Sources : README.md65 smb.conf:7-10

Troubleshooting Quick Reference

For detailed troubleshooting, see Connection Problems and Platform-Specific Issues.

Sources : README.md:55-70