SSHFS Mount Options

Relevant source files

• Dockerfile
• README.md

Purpose and Scope

This page documents the critical mount options required when mounting remote filesystems via SSHFS inside the docker-sshfs container. These options are essential for enabling Samba to access the mounted filesystem and for providing write permissions. Without these specific options, the remote filesystem will either be inaccessible to the Samba service or will be read-only from the macOS client.

For information about the Samba configuration that consumes the mounted filesystem, see Samba Configuration (smb.conf)). For details about the FUSE configuration that enables cross-user access, see FUSE Configuration.

Required Mount Options

The SSHFS mount command must include three critical options to function correctly with the Samba integration:

Sources: README.md:49-53

Complete Mount Command

The full SSHFS mount command as executed inside the container:

Where:

• user@host:path is the remote SSH endpoint (user, host, and remote directory path)
• /samba-share is the local mount point inside the container

Note: This command mounts directly to /samba-share (not to /remote), making the remote filesystem immediately available to Samba. The /remote directory exists for alternative mounting strategies but is linked via symlink to /samba-share/remote Dockerfile30

Sources: README.md:46-50

Option Details

allow_other

-o allow_other

The allow_other option is a FUSE-level permission that allows users other than the mount owner to access the mounted filesystem. This option is absolutely critical for the Samba integration.

graph LR
    subgraph "Without allow_other"
        SSHFSMount1["SSHFS Mount"]
SSHUser1["sshuser (uid 1000)"]
SambaProc1["smbd process"]
SSHFSMount1 -->|Owned by| SSHUser1
 
       SambaProc1 -.->|Access Denied| SSHFSMount1
    end
    
    subgraph "With allow_other"
        SSHFSMount2["SSHFS Mount"]
SSHUser2["sshuser (uid 1000)"]
SambaProc2["smbd process"]
SSHFSMount2 -->|Owned by| SSHUser2
 
       SambaProc2 -->|Access Granted| SSHFSMount2
    end

Technical Mechanism

Diagram: Impact of allow_other on cross-process access

By default, FUSE mounts are only accessible to the user who created the mount. Since the sshfs command is executed as sshuser, but the smbd daemon runs as a different process (potentially with different effective permissions), the Samba service would be unable to read files from the mount without allow_other.

Prerequisites

The allow_other option requires that /etc/fuse.conf contains the user_allow_other directive. This is configured during the Docker image build:

Dockerfile:23-24

Sources: README.md52 Dockerfile:23-24

uid=1000

-o uid=1000

graph TB
    subgraph "Remote Server"
        RemoteFiles["Remote Files\n(various owners)"]
end
    
    subgraph "Container (SSHFS Mount)"
        MountedFiles["Mounted Files\n(all uid=1000)"]
end
    
    subgraph "Samba Layer"
        SambaConfig["smb.conf\nforce user = sshuser"]
MacClient["macOS Client\n(connects as Guest)"]
end
    
 
   RemoteFiles -->|SSH Connection| MountedFiles
 
   MountedFiles -.->|uid override| SambaConfig
 
   SambaConfig -->|All operations as sshuser| MacClient

The uid=1000 option forces all files in the mounted filesystem to appear as if they are owned by user ID 1000, which corresponds to the sshuser account created in the container.

User ID Mapping

Diagram: UID mapping through the system layers

The sshuser account is created with UID 1000 during the Docker build:

Dockerfile:8-9

By forcing all files to appear as owned by UID 1000, the system ensures consistent ownership regardless of the actual ownership on the remote server. This is then coordinated with the Samba configuration's force user = sshuser directive, creating a unified permission model.

Sources: README.md53 Dockerfile:8-9

graph TB
    subgraph "Read-Only Configuration"
        Mount1["sshfs -o allow_other\n(gid omitted)"]
Files1["Files with remote GID"]
MacClient1["macOS Client"]
Mount1 --> Files1
 
       Files1 -.->|Write Denied| MacClient1
    end
    
    subgraph "Write-Enabled Configuration"
        Mount2["sshfs -o allow_other,gid=1000"]
Files2["Files with gid=1000"]
MacClient2["macOS Client"]
Mount2 --> Files2
 
       Files2 -->|Write Allowed| MacClient2
    end

gid=1000

-o gid=1000

The gid=1000 option forces all files to appear as if they belong to group ID 1000. This option is essential for write access from the macOS client.

Write Access Dependency

Diagram: Impact of gid option on write permissions

Without the gid=1000 option, files retain their original group ownership from the remote server. This can cause permission mismatches when the Samba service (operating as sshuser with GID 1000) attempts to modify files. The result is a read-only mount from the macOS perspective, even though the underlying remote filesystem is writable.

By setting gid=1000, all files appear to belong to the sshuser group, matching the effective group of the Samba service, thus enabling write operations.

Sources: README.md53

Mount Point Architecture

Directory Structure

Diagram: Mount point and directory relationships

The container creates two directories during the build:

• Dockerfile:11-12: /remote directory (currently unused in the recommended workflow)
• Dockerfile:14-15: /samba-share directory (primary mount point)

A symbolic link is created from /samba-share/remote to /remote Dockerfile30 but when mounting directly to /samba-share, this link is effectively shadowed by the mount.

The /samba-share directory has permissions set to 777 Dockerfile:20-21 to ensure maximum compatibility, though this is less critical when using the uid and gid options.

Sources: Dockerfile:11-12 Dockerfile:14-15 Dockerfile:20-21 Dockerfile30

Option Interaction Matrix

The three options must work together to enable full functionality:

Sources: README.md:52-53

Command Execution Context

The SSHFS mount command is executed inside the running container via docker exec:

Diagram: Mount command execution sequence

The command runs in an interactive shell (bash) within the container, allowing the user to provide SSH authentication credentials when prompted by the remote server.

Sources: README.md:40-50

Additional SSHFS Options

While allow_other, uid=1000, and gid=1000 are required for the Samba integration, SSHFS supports many additional options that can be appended to the -o flag:

Common Optional Settings

Combined Example

These additional options do not affect the Samba integration but may improve reliability or performance depending on the remote connection characteristics.

Sources: README.md49

Verification

To verify that the mount options are correctly applied, inspect the mount inside the container:

Expected output should show:

user@host:path on /samba-share type fuse.sshfs (rw,nosuid,nodev,relatime,user_id=1000,group_id=1000,allow_other)

Key indicators:

• user_id=1000 confirms the uid option
• group_id=1000 confirms the gid option
• allow_other confirms cross-user access is enabled

Sources: Implicit from system behavior