Mounting Remote Filesystems

Relevant source files

• Dockerfile
• README.md

Purpose and Scope

This page describes how to mount a remote SSH filesystem inside the docker-sshfs container using the sshfs command. It covers the required mount options (allow_other, uid, gid) and explains why each is necessary for integration with Samba. This assumes the container is already built and running. For container setup, see Building the Container and Running the Container. For connecting from macOS Finder, see Connecting from macOS.

Sources: README.md (lines 36-54)

Executing into the Container

To mount a remote filesystem, you must first execute a bash shell inside the running container:

This command starts an interactive terminal session inside the container named docker-sshfs. Once executed, you will be inside the container environment with access to the sshfs command and the mount point directories.

Sources: README.md (lines 40-44)

The SSHFS Mount Command

The sshfs command mounts a remote SSH filesystem to a local directory inside the container. The basic syntax is:

Replace user@host:path with your actual SSH endpoint. For example:

• john@192.168.1.100:/home/john/documents
• deploy@example.com:/var/www/html
• admin@10.0.0.5:~/projects

sequenceDiagram
    participant User as "User Terminal"
    participant Bash as "Container Bash Session"
    participant SSHFS as "sshfs Process"
    participant FUSE as "FUSE Layer"
    participant Remote as "Remote SSH Server"
    participant Samba as "smbd Service"
    
    User->>Bash: docker exec -it docker-sshfs bash
    activate Bash
    
    User->>Bash: sshfs -o allow_other,uid=1000,gid=1000\nuser@host:path /samba-share
    Bash->>SSHFS: Execute sshfs command
    activate SSHFS
    
    SSHFS->>Remote: SSH connection request
    Remote-->>SSHFS: Authentication prompt
    User->>Remote: Enter SSH password/key
    Remote-->>SSHFS: Authentication successful
    
    SSHFS->>FUSE: Register FUSE filesystem
    FUSE->>FUSE: Apply mount options:\nallow_other, uid=1000, gid=1000
    
    FUSE-->>SSHFS: Mount registered at /samba-share
    SSHFS-->>Bash: Mount successful
    
    Note over FUSE,Samba: allow_other enables cross-user access
    
    Samba->>FUSE: Read /samba-share (as sshuser)
    FUSE-->>Samba: Access granted (allow_other)
    
    Bash-->>User: Return to prompt
    deactivate SSHFS
    deactivate Bash

The mount target is /samba-share, which is the directory that the Samba service exposes to macOS.

Sources: README.md (lines 46-50)

SSHFS Mount Process Flow

Diagram: SSHFS Mount Process - Shows the sequence of operations from command execution through SSH authentication to successful FUSE mount registration and Samba integration.

Sources: README.md (lines 40-54), Dockerfile (lines 23-24)

Critical Mount Options

The mount options specified with -o are essential for the system to function correctly. Omitting any of these options will result in either read-only access or complete inaccessibility from macOS.

The combination of uid=1000 and gid=1000 corresponds to the sshuser account created in the container Dockerfile9 This ensures consistent ownership and enables write access. Without these options, the mount will be read-only.

Sources: README.md (lines 52-53)

Container Directory Structure

The container has two primary directories involved in the mount process:

Diagram: Container Directory Structure and Mount Options - Illustrates the relationship between /remote, /samba-share, and the symbolic link, along with two possible mounting approaches.

Sources: Dockerfile (lines 12, 15, 30)

Directory Roles and Relationships

/remote Directory

Created by Dockerfile12 This directory serves as the designated FUSE mount point in the system architecture. While the README documents mounting directly to /samba-share, the container structure includes /remote as an alternative mount location. When used, the symbolic link at /samba-share/remote provides access.

/samba-share Directory

Created by Dockerfile15 and configured with chmod -R 777 permissions Dockerfile21 This directory is the root of the Samba share exposed to macOS. The README documents mounting the remote filesystem directly to this location.

/samba-share/remote Symbolic Link

Created by Dockerfile30 as ln -s /remote /samba-share/remote. This symbolic link connects /remote to /samba-share/remote, enabling access to /remote contents through the Samba share when mounting to /remote instead of /samba-share.

Sources: Dockerfile (lines 12, 15, 21, 30)

FUSE Configuration Requirement

The allow_other mount option requires that FUSE be configured to permit non-root users to use this option. The container enables this by appending user_allow_other to /etc/fuse.conf:

user_allow_other

This line is added during the container build process Dockerfile24 Without this configuration, the sshfs command will fail with an error message stating that allow_other is not permitted.

Sources: Dockerfile (lines 23-24)

graph TB
    subgraph "Mount Command Components"
        Cmd["sshfs -o allow_other,uid=1000,gid=1000"]
Remote["user@host:path"]
Target["/samba-share"]
end
    
    subgraph "allow_other Effect"
        AO1["FUSE allows cross-user access"]
AO2["smbd process can read mount"]
AO3["macOS Finder receives files"]
AO1 -->
 AO2 --> AO3
    end
    
    subgraph "uid=1000,gid=1000 Effect"
        UID1["All files owned by uid=1000"]
UID2["Matches sshuser account"]
UID3["Write operations permitted"]
UID4["No permission errors"]
UID1 -->
 UID2 -->
 UID3 --> UID4
    end
    
    subgraph "Without uid/gid"
        NO1["Files owned by root:root"]
NO2["sshuser cannot modify"]
NO3["Read-only access from macOS"]
NO1 -->
 NO2 --> NO3
    end
    
 
   Cmd --> AO1
 
   Cmd --> UID1
    
    style AO3 fill:#e1ffe1
    style UID4 fill:#e1ffe1
    style NO3 fill:#ffe1e1

Mount Options Technical Details

Diagram: Mount Options Impact on Access Permissions - Shows how each mount option affects the accessibility and write permissions of the mounted filesystem.

Sources: README.md (lines 49-53), Dockerfile (line 9)

Verification of Successful Mount

After executing the sshfs command, you can verify the mount succeeded by:

1. Check mount point contents:

The directory should display the contents of the remote filesystem.

2. Inspect active mounts:

Should display a line showing the SSHFS mount at /samba-share.

3. Check FUSE mounts:

Should show the FUSE filesystem mounted at the specified path.

If the mount fails, common issues include:

• Incorrect SSH credentials
• Network connectivity problems to the remote host
• SSH host key verification prompts (may require running sshfs interactively first)
• Insufficient permissions on the remote filesystem

Sources: README.md (lines 46-54)

Relationship to Samba Service

Once the remote filesystem is mounted at /samba-share, the smbd service (started automatically when the container runs Dockerfile33) serves this directory over SMB protocol. The Samba configuration file smb.conf defines /samba-share as the share path.

The allow_other mount option is critical for this integration because:

1. The sshfs process runs as the user executing the command inside the container
2. The smbd service runs as a separate process (as sshuser due to force user configuration)
3. Without allow_other, FUSE would deny smbd access to the mounted filesystem
4. With allow_other enabled, smbd can read and serve the mounted files to macOS clients

For details on the Samba configuration, see Samba Configuration (smb.conf)). For connecting from macOS, see Connecting from macOS.

Sources: README.md (lines 52-53), Dockerfile (lines 23-24, 33)