Unmounting and Cleanup

Relevant source files

• README.md

Purpose and Scope

This page explains the proper procedures for unmounting remote filesystems and cleaning up the sshfs-mac-docker system. The unmounting process requires specific sequencing due to dependencies between macOS Finder connections, Samba shares, and SSHFS mounts. Failure to follow the correct order results in the common "Device or resource busy" error.

For information about establishing the initial connection, see Connecting from macOS. For detailed troubleshooting of unmounting errors, see Device or Resource Busy Errors.

Sources: README.md:71-86

Unmounting Sequence Overview

The system has multiple interdependent mount points that must be disconnected in a specific order. The macOS Finder connection to the Samba share must be terminated before the underlying SSHFS mount can be unmounted. This dependency exists because active SMB connections hold references to the filesystem.

flowchart TD
    FinderMounted["macOS Finder Connected to smb://container-ip"]
SambaServing["Samba serving /samba-share"]
SSHFSMounted["SSHFS mounted at /remote\nsymlinked to /samba-share"]
ContainerRunning["Container docker-sshfs running"]
FinderMounted -->|Must disconnect first| SambaServing
 
   SambaServing -->|Then allow unmount| SSHFSMounted
 
   SSHFSMounted -->|Finally can stop| ContainerRunning
    
 
   FinderMounted -.->|If skipped: 'Device or resource busy'| SSHFSMounted
    
    style FinderMounted fill:#fff
    style SSHFSMounted fill:#fff
    style ContainerRunning fill:#fff

Cleanup Dependency Chain

Sources: README.md:71-86

Step 1: Disconnect from macOS

Before unmounting the SSHFS filesystem inside the container, all macOS Finder connections to the Samba share must be terminated. Active SMB sessions maintain locks on the filesystem that prevent clean unmounting.

Disconnecting in Finder

The share name typically appears as the container's IP address (e.g., 172.17.0.2) or as configured in Samba.

Verification

After disconnecting, the share should no longer appear in:

• Finder sidebar under "Locations"
• Finder → Go → Network
• Desktop (if "Connected servers" is enabled in Finder preferences)

Sources: README.md:79-85

Step 2: Unmount SSHFS in Container

Once all macOS connections are terminated, the SSHFS mount can be safely removed from inside the container using the fusermount utility.

Unmount Command

Alternatively, if already in a container shell session:

The target path /samba-share is where the SSHFS mount was established, not the underlying symlink target /remote.

Command Breakdown

Sources: README.md:71-77

Handling "Device or Resource Busy" Error

The most common unmounting error occurs when attempting to unmount the SSHFS filesystem while macOS Finder still has an active connection to the Samba share.

Error Message

fusermount: failed to unmount /samba-share: Device or resource busy

Root Cause

This error indicates that processes are actively using files or directories within the mount point. In sshfs-mac-docker, this is typically caused by:

1. Active SMB connections from macOS Finder
2. Open file handles from Samba daemon (smbd)
3. Working directory set to a path within /samba-share

flowchart TD
    Start["fusermount -u /samba-share fails:\nDevice or resource busy"]
CheckFinder["Check: Is macOS Finder\nconnected to smb://container-ip?"]
EjectFinder["Eject share from\nmacOS Finder"]
RetryUnmount["Retry: fusermount -u /samba-share"]
CheckLsof["Check: lsof /samba-share\nShows open files?"]
KillProcesses["Identify and terminate\nprocesses using mount"]
ForceStop["Force stop container:\ndocker stop docker-sshfs"]
Success["Unmount successful"]
Start --> CheckFinder
 
   CheckFinder -->|Yes| EjectFinder
 
   CheckFinder -->|No| CheckLsof
 
   EjectFinder --> RetryUnmount
    
 
   RetryUnmount -->|Still fails| CheckLsof
 
   RetryUnmount -->|Success| Success
    
 
   CheckLsof -->|Yes| KillProcesses
 
   CheckLsof -->|No processes found| ForceStop
 
   KillProcesses --> RetryUnmount
    
 
   ForceStop --> Success
    
    style Start fill:#fff
    style Success fill:#fff

Resolution Flowchart

Sources: README.md:79-85

Diagnostic Commands

When troubleshooting unmounting issues, these commands help identify what is preventing the unmount operation.

Check Open Files

This lists all processes with open file handles in the mount point, including:

• Process ID (PID)
• Process name
• File descriptors
• File paths

Check Mount Status

Verifies whether /samba-share is currently mounted and shows the mount options in use.

Inspect Samba Connections

Displays active SMB sessions, including:

• Connected clients (macOS IP addresses)
• Shared resources in use
• Locked files

Sources: README.md:71-86

sequenceDiagram
    actor User
    participant Finder as "macOS Finder"
    participant Docker as "Docker Engine"
    participant Container as "docker-sshfs"
    participant SSHFS as "SSHFS Mount\n/samba-share"
    participant Remote as "Remote Server"
    
    rect rgb(240, 240, 240)
        Note over Finder,Remote: Active State: System in Use
        Finder->>Container: SMB connection active
        Container->>SSHFS: Serving files via Samba
        SSHFS->>Remote: SSH connection active
    end
    
    rect rgb(250, 240, 240)
        Note over User,Remote: Phase 1: Disconnect macOS Client
        User->>Finder: Eject smb://container-ip
        Finder-->>Container: Close SMB sessions
        Container->>Container: smbd releases file locks
    end
    
    rect rgb(240, 250, 240)
        Note over User,Remote: Phase 2: Unmount SSHFS
        User->>Container: fusermount -u /samba-share
        Container->>SSHFS: Unmount request
        SSHFS->>Remote: Close SSH connection
        Remote-->>SSHFS: Connection terminated
        SSHFS-->>Container: Unmount complete
        Container-->>User: Success (no output)
    end
    
    rect rgb(240, 240, 250)
        Note over User,Container: Phase 3: Container Cleanup (Optional)
        User->>Docker: docker stop docker-sshfs
        Docker->>Container: SIGTERM to smbd
        Container->>Container: smbd graceful shutdown
        Container-->>Docker: Container stopped
        
        User->>Docker: docker rm docker-sshfs (optional)
        Docker-->>User: Container removed
    end

Complete Cleanup Sequence

This diagram shows the full lifecycle from active use to complete system shutdown.

Sources: README.md:71-86

Container Lifecycle Management

Beyond unmounting the filesystem, you may need to stop or remove the container itself as part of cleanup operations.

Stopping the Container

This sends a SIGTERM signal to the container's main process (smbd), allowing it to:

• Close active SMB connections gracefully
• Flush buffered data
• Release filesystem locks

The container automatically unmounts all FUSE filesystems during shutdown, though this may fail if macOS connections are still active.

Removing the Container

Removes the stopped container, including:

• Container filesystem layers
• Network configurations
• Port mappings

The Docker image docker-sshfs remains available for creating new containers.

Force Cleanup

If the container cannot be stopped normally (e.g., hung processes), force removal:

This sends SIGKILL, immediately terminating all processes. Use this as a last resort, as it may result in:

• Incomplete file writes on remote server
• Stale SSH connections
• Corrupt cache data

Sources: README.md:26-35

Cleanup Command Reference

Unmounting Operations

Container Lifecycle

Image Management

Sources: README.md:71-86 README.md:26-35

stateDiagram-v2
    [*] --> Active : Normal operation
    
    state Active {
        [*] --> FinderConnected
        state FinderConnected {
            [*] --> SSHFSMounted : SMB serving files
            SSHFSMounted --> [*] : fusermount -u fails (Device busy)
        }
    }
    
    Active --> FinderDisconnected : Eject from Finder
    
    state FinderDisconnected {
        [*] --> SSHFSMounted : No SMB connections
        SSHFSMounted --> Unmounted : fusermount -u
        Unmounted --> [*] : Clean state
    }
    
    FinderDisconnected --> ContainerStopped : docker stop
    Active --> ContainerStopped : docker stop -f (forces unmount)
    
    state ContainerStopped {
        [*] --> Stopped : smbd terminated
        Stopped --> [*] : Can be restarted
    }
    
    ContainerStopped --> [*] : docker rm
    
    note right of Active
        Attempting fusermount -u
        while Finder connected
        results in error
    end note
    
    note right of ContainerStopped
        Container stop automatically
        unmounts SSHFS if no
        active connections exist
    end note

State Transition Diagram

This diagram shows valid state transitions during unmounting and cleanup operations.

Sources: README.md:71-86

Best Practices

Orderly Shutdown Checklist

1. Save all open files in macOS applications accessing the remote filesystem
2. Close applications that may have file handles open on the remote share
3. Eject from Finder using any of the methods described above
4. Wait 2-3 seconds for SMB connections to fully terminate
5. Execute fusermount inside the container
6. Verify unmount using mount | grep samba-share (should return nothing)
7. Stop container if no longer needed

Avoiding Common Mistakes

Sources: README.md:71-86

Error Recovery Scenarios

Scenario 1: Container Becomes Unresponsive

If the container does not respond to docker exec commands:

This forces a restart, which will:

• Terminate all SSHFS mounts
• Close all Samba connections
• Restart the smbd daemon

Finder connections must be re-established after restart.

Scenario 2: Unmount Fails Despite No Finder Connection

If fusermount -u fails even after disconnecting from Finder, check for other processes:

Kill any non-Samba processes using the mount:

Then retry unmounting.

Scenario 3: SSH Connection to Remote Server Hangs

If the SSH connection becomes unresponsive, the SSHFS mount may become stale. In this case:

The -l option performs a lazy unmount, detaching the filesystem immediately but cleaning up references when they become idle.

Sources: README.md:71-86

Summary

Proper unmounting requires understanding the dependency chain between macOS Finder, Samba, and SSHFS. The key principle is outside-in cleanup : disconnect external clients first (Finder), then unmount the underlying filesystem (SSHFS), and finally stop the container infrastructure (Docker) if needed.

The "Device or resource busy" error is a symptom of violating this ordering, indicating that active connections still hold references to the filesystem. By following the documented sequence and using the diagnostic commands provided, clean unmounting can be achieved consistently.

Sources: README.md:71-86