FUSE Configuration

Relevant source files

• Dockerfile
• README.md

Purpose and Scope

This page documents the FUSE (Filesystem in Userspace) configuration used by sshfs-mac-docker, specifically the modifications made to /etc/fuse.conf. The primary focus is the user_allow_other setting and its critical role in enabling cross-service filesystem access between SSHFS and Samba.

For Samba-specific configuration settings, see Samba Configuration (smb.conf)). For the SSHFS mount options that depend on this FUSE configuration, see SSHFS Mount Options.

FUSE Overview

FUSE (Filesystem in Userspace) is a software interface that allows non-privileged users to create their own file systems without modifying kernel code. SSHFS is built on top of FUSE, enabling remote directories to be mounted as if they were local filesystems through FUSE operations.

In sshfs-mac-docker, FUSE operations occur entirely within the Docker container, avoiding the need for macFUSE or kernel extensions on the macOS host.

Sources: README.md, Dockerfile

The /etc/fuse.conf File

The /etc/fuse.conf file controls system-wide FUSE behavior. It is a simple text configuration file that defines security policies for FUSE mounts.

Sources: Dockerfile:23-24

The user_allow_other Setting

Syntax and Meaning

user_allow_other

This single-line directive enables non-root users to specify the allow_other mount option when creating FUSE mounts.

Default Behavior Without This Setting

By default, FUSE restricts the allow_other mount option to the root user for security reasons. If a non-root user attempts to mount a FUSE filesystem with allow_other without this setting enabled, the mount operation fails with a permission error:

fuse: option allow_other only allowed if 'user_allow_other' is set in /etc/fuse.conf

Security Implications

The allow_other option permits users other than the one who performed the mount to access the filesystem. This represents a security relaxation, as it bypasses FUSE's default isolation model. The user_allow_other setting delegates the decision to use this option to individual users rather than requiring root privileges for every mount that needs cross-user access.

Sources: Dockerfile:23-24, README.md:52

Configuration in sshfs-mac-docker

Dockerfile Implementation

The FUSE configuration is established during the Docker image build process:

Dockerfile:23-24

This command appends the user_allow_other directive to the existing /etc/fuse.conf file. The >> operator ensures the line is added without overwriting any default content.

Build-Time vs. Runtime

Sources: Dockerfile:23-24

Why user_allow_other is Essential

The Cross-Service Access Problem

The sshfs-mac-docker architecture requires two separate services to access the same filesystem:

1. SSHFS Client : Mounts the remote filesystem (runs as sshuser)
2. Samba Server : Serves the mounted filesystem to macOS (runs as root or configured user)

graph TB
    subgraph "Without user_allow_other"
        SSHFS1["sshfs mount by sshuser"]
FUSE1["FUSE Kernel Module"]
Mount1["/remote mount point"]
Samba1["smbd service (different user)"]
Access1["❌ Permission Denied"]
SSHFS1 --> FUSE1
 
       FUSE1 --> Mount1
 
       Samba1 -.->|Attempts access| Mount1
 
       Mount1 -.->|Blocked by FUSE| Access1
    end
    
    subgraph "With user_allow_other + allow_other mount option"
        SSHFS2["sshfs -o allow_other"]
FUSE2["FUSE Kernel Module\n(user_allow_other enabled)"]
Mount2["/remote mount point"]
Samba2["smbd service (different user)"]
Access2["✓ Access Granted"]
SSHFS2 --> FUSE2
 
       FUSE2 --> Mount2
 
       Samba2 -->|Can access| Mount2
 
       Mount2 --> Access2
    end

Without user_allow_other and the corresponding allow_other mount option, Samba cannot access files in the SSHFS mount because FUSE's default behavior restricts access to only the user who performed the mount (sshuser).

Permission Flow Diagram

Sources: Dockerfile:23-24, README.md:49-53

Relationship to SSHFS Mount Options

Configuration Chain

The user_allow_other setting in /etc/fuse.conf is the prerequisite that enables the allow_other mount option in the SSHFS command:

Sources: Dockerfile:23-24, README.md:49-53

sequenceDiagram
    participant Build as docker build
    participant FuseConf as /etc/fuse.conf
    participant User as Container User
    participant SSHFS as sshfs command
    participant FUSE as FUSE Module
    participant Mount as /remote
    
    Build->>FuseConf: Append "user_allow_other"
    Note over FuseConf: Setting persisted in image
    
    User->>SSHFS: sshfs -o allow_other user@host /remote
    SSHFS->>FuseConf: Check if allow_other permitted
    FuseConf-->>SSHFS: user_allow_other is set ✓
    SSHFS->>FUSE: Mount with allow_other flag
    FUSE->>Mount: Create mount point with cross-user access
    Note over Mount: Other users can now access

Dependency Table

Sources: Dockerfile:23-24, README.md:49-53

Cross-Service Access Flow

This diagram shows how the FUSE configuration enables the complete data flow from macOS through Samba to the SSHFS-mounted remote filesystem:

Sources: Dockerfile:23-24, Dockerfile:30, README.md:49-53

graph LR
    subgraph "macOS Client"
        Finder["macOS Finder"]
end
    
    subgraph "Docker Container"
        subgraph "Service Layer"
            Smbd["smbd process\n(different UID)"]
end
        
        subgraph "FUSE Layer"
            FuseConf["/etc/fuse.conf\nuser_allow_other"]
FuseModule["FUSE Module"]
end
        
        subgraph "Filesystem Layer"
            SambaShare["/samba-share/"]
Symlink["symbolic link"]
RemoteMount["/remote/\n(SSHFS mount)"]
end
        
        subgraph "SSHFS Layer"
            SSHFSProc["sshfs process\n(sshuser UID 1000)\n-o allow_other"]
end
    end
    
    subgraph "Remote"
        RemoteFS["Remote SSH Server"]
end
    
 
   Finder -->|SMB read/write| Smbd
 
   Smbd -->|Access files| SambaShare
 
   SambaShare --> Symlink
 
   Symlink -.->|Points to| RemoteMount
    
 
   FuseConf -.->|Enables| SSHFSProc
 
   SSHFSProc -->|Mount with allow_other| FuseModule
 
   FuseModule -->|Creates| RemoteMount
 
   RemoteMount -->|Cross-user access allowed| Smbd
    
 
   SSHFSProc <-->|SSH protocol| RemoteFS

Verification

Checking the Configuration

To verify that user_allow_other is properly configured in a running container:

Expected output should include:

user_allow_other

Testing Cross-User Access

When SSHFS is mounted with allow_other, verify that Samba can access the mount:

Both commands should successfully list files, confirming cross-user access is working.

Sources: README.md:41-50, Dockerfile:23-24

Configuration Summary

Sources: Dockerfile:23-24, README.md:49-53

Common Issues

Mount Fails with "option allow_other only allowed" Error

Symptom: SSHFS mount command fails when using -o allow_other

Cause: The user_allow_other line is missing from /etc/fuse.conf

Solution: Rebuild the Docker image, ensuring Dockerfile24 is present and executed

Samba Cannot Access Mounted Files

Symptom: Samba share appears empty or shows permission denied errors

Cause: SSHFS mount was performed without -o allow_other flag

Solution: Remount using the complete command from README.md49

Sources: README.md:49-53, Dockerfile:23-24