Command Reference

Relevant source files

• README.md

This page provides a comprehensive reference for all commands used to build, run, manage, and interact with the sshfs-mac-docker system. Commands are organized by functional category for quick lookup during system operations.

For detailed explanations of how these commands fit into the overall workflow, see Getting Started. For troubleshooting command-related issues, see Troubleshooting.

Sources: README.md:1-90

Command Workflow Overview

Sources: README.md:19-86

Docker Image Management

Commands for building and managing the docker-sshfs image.

docker build

Builds the Docker image from the Dockerfile in the current directory.

Example:

What This Builds:

• Ubuntu base image with sshfs and samba packages
• User account sshuser:sshpass (UID 1000, GID 1000)
• Directory structure: /remote, /samba-share with symbolic link
• Configuration files: smb.conf, modified fuse.conf

Sources: README.md:19-23

docker rmi

Removes the built image from the local Docker registry.

Example:

Sources: Referenced in state diagram (Diagram 6 in high-level overview)

Container Lifecycle Management

Commands for starting, stopping, and managing the container instance.

graph LR
    Command["docker run"]
subgraph "Required_Flags"
        Privileged["--privileged\nFUSE requires privileged mode"]
Name["--name docker-sshfs\nContainer identifier"]
Port139["-p 127.0.0.1:139:139\nNetBIOS port mapping"]
Port445["-p 127.0.0.1:445:445\nSMB port mapping"]
end
    
    subgraph "Result"
        Container["Container running\nsmbd in foreground"]
end
    
 
   Command --> Privileged
 
   Command --> Name
 
   Command --> Port139
 
   Command --> Port445
    
 
   Privileged --> Container
 
   Name --> Container
 
   Port139 --> Container
 
   Port445 --> Container

docker run

Starts a new container from the docker-sshfs image with required privileges and port mappings.

Example:

Important Notes:

• Container runs in foreground by default; terminal shows Samba logs
• Use -d flag for detached mode: docker run -d --privileged ...
• Port binding to 127.0.0.1 prevents external network access
• Container must be named docker-sshfs or update container name in subsequent commands

Sources: README.md:26-34

docker stop

Stops a running container gracefully.

Example:

Sources: Implied by container lifecycle in README.md85

docker start

Restarts a stopped container (preserves SSHFS mounts if not explicitly unmounted).

Example:

Sources: Container lifecycle management pattern

docker rm

Removes a stopped container permanently.

Example:

Sources: Standard Docker lifecycle pattern

Container Inspection

Commands for querying container state and metadata.

docker inspect

Retrieves detailed container metadata, most commonly used to get the container's IP address.

Example - Get Container IP:

Output Example:

172.17.0.2

This IP address is used in Finder to connect: smb://172.17.0.2

Sources: README.md:57-61

docker logs

Views container output (Samba logs).

Example:

Sources: Standard Docker logging pattern

docker ps

Lists running containers.

Example:

Sources: Standard Docker inspection pattern

SSHFS Operations

Commands executed inside the container to mount and unmount remote filesystems.

Entering the Container

Before executing SSHFS commands, access the container's interactive shell.

Example:

You will see a shell prompt like:

root@a1b2c3d4e5f6:/#

Sources: README.md:38-44

sshfs Mount Command

Mounts a remote filesystem via SSH to /remote inside the container.

Examples:

Why These Options Matter:

Sources: README.md:46-53

Additional SSHFS Options

Optional parameters for advanced use cases.

Combined Example:

Sources: Standard SSHFS options (not explicitly in README but commonly used)

fusermount Unmount Command

Unmounts the SSHFS filesystem from /remote.

Example:

Handling "Device or resource busy" Error:

Cause: macOS Finder still has an active SMB connection to the share.

Solution:

1. In macOS Finder, eject the network share (right-click → Eject)
2. Then retry: fusermount -u /remote
3. Alternative: docker stop docker-sshfs (forces unmount)

Sources: README.md:72-85

macOS Client Operations

Commands and procedures executed on the macOS host to connect to the Samba share.

Discovering Container IP

Since localhost does not work for SMB connections, the container's internal Docker IP must be used.

Command:

Expected Output:

172.17.0.2

Sources: README.md:57-61

Connecting from Finder

Procedure:

1. In macOS Finder, press Cmd+K or navigate to Go → Connect to Server

2. Enter the connection string using the container IP:

   smb://172.17.0.2
   

Replace 172.17.0.2 with the actual container IP from docker inspect

3. Click Connect

4. Authentication prompt:

   • Select Guest (do not use username/password)
   • Click Connect

5. The share appears in Finder under Network → IP address

6. Inside the share, navigate to the remote directory to access mounted files

Sources: README.md:55-69

Connection String Format

Why localhost doesn't work: Despite port forwarding to 127.0.0.1, the macOS SMB client requires connection to the container's internal IP address due to how Docker's network stack handles SMB protocol translation.

Sources: README.md57

Disconnecting from macOS

Procedure:

1. In Finder, locate the mounted share under Network
2. Right-click (or Control-click) on the share
3. Select Eject or click the eject button (⏏)
4. Share disappears from Finder

Alternative: Drag the share icon to Trash

Effect: Closes SMB connection, allowing safe unmounting with fusermount -u in the container

Sources: README.md85

Command Sequences for Common Tasks

Complete Setup and Mount

Sources: README.md:19-69

Complete Teardown

Sources: README.md:72-85

Remounting Different Remote Endpoint

Sources: Implied workflow from README.md:46-85

State-Based Command Reference

Sources: README.md:19-85

Quick Reference Table

Sources: README.md:19-90