Filesystem Layout

Relevant source files

• Dockerfile
• README.md

This page documents the internal directory structure of the docker-sshfs container, including the purpose of each directory, the symbolic link integration point, and how these filesystem components enable the protocol bridge between SSHFS and Samba. For configuration details about permissions and the sshuser account, see User and Permissions. For information about how these directories are created during the build process, see Dockerfile Breakdown.

Directory Structure Overview

The container maintains a minimal filesystem layout with three key directories that form the core of the SSHFS-to-Samba bridge. The directory structure is established during the Docker image build process and remains static throughout the container's lifetime.

graph TB
    root["/"]
remote["/remote"]
sambaShare["/samba-share"]
sambaRemote["/samba-share/remote"]
etc["/etc"]
sambaConf["/etc/samba/smb.conf"]
fuseConf["/etc/fuse.conf"]
root --> remote
 
   root --> sambaShare
 
   root --> etc
 
   sambaShare -.->|symbolic link| sambaRemote
 
   sambaRemote -.->|ln -s /remote| remote
 
   etc --> sambaConf
 
   etc --> fuseConf
    
    style sambaRemote fill:#f9f9f9
    style remote fill:#f9f9f9
    style sambaShare fill:#f9f9f9

Container Directory Tree

Sources: Dockerfile12 Dockerfile15 Dockerfile30

Root-Level Mount Directories

/remote - SSHFS Mount Point

The /remote directory serves as the primary mount point for SSHFS operations. This directory is created during the Docker build process and remains empty until a user executes the sshfs command to mount a remote filesystem.

The /remote directory is referenced in the SSHFS mount command but is not directly served by Samba. Instead, it is accessed through the symbolic link integration point.

Sources: Dockerfile12

/samba-share - Samba Root Directory

The /samba-share directory functions as the root directory served by the Samba service. This is the directory that appears to macOS clients when they connect to the SMB share. The directory is configured with world-writable permissions to ensure compatibility with the Samba guest access model.

The 777 permission mode is critical for write access from macOS clients connecting as guests. Without these permissive settings, write operations would fail despite the writable = yes Samba configuration.

Sources: Dockerfile15 Dockerfile21

The Symbolic Link Integration Point

/samba-share/remote → /remote

The symbolic link at /samba-share/remote is the critical integration point that bridges the SSHFS mount with the Samba share. This zero-copy mechanism allows remote files mounted at /remote to be accessible through the Samba share without data duplication.

Sources: Dockerfile30

graph LR
    macOS["macOS Finder Client"]
smbd["smbd process"]
sambashare["/samba-share\n(Samba root)"]
symlink["/samba-share/remote\n(symbolic link)"]
remotedir["/remote\n(SSHFS mount)"]
sshfs["sshfs process"]
remoteServer["Remote SSH Server"]
macOS -->|SMB protocol| smbd
 
   smbd -->|serves| sambashare
 
   sambashare -->|contains| symlink
 
   symlink -.->|ln -s /remote| remotedir
 
   remotedir -->|mounted by| sshfs
 
   sshfs -->|SSH protocol| remoteServer

Symbolic Link Behavior

The symbolic link is created during the Docker build process using the ln -s command. Key behavioral characteristics:

• Cross-Service Access : The symlink allows the smbd process (running as root or nobody) to access files in /remote which are mounted by the sshuser account
• FUSE Requirement : The symbolic link only functions correctly if the SSHFS mount uses the allow_other option, enabled by user_allow_other in /etc/fuse.conf
• Transparent Operation : macOS clients see /samba-share/remote as a normal directory, not as a symbolic link
• Zero-Copy : Files are not duplicated; the symlink provides direct access to the FUSE-mounted filesystem

Sources: Dockerfile30 Dockerfile24

Filesystem Integration Architecture

The following diagram illustrates how the directory structure integrates with the SSHFS and Samba services to create the protocol bridge:

Sources: Dockerfile12 Dockerfile15 Dockerfile30 Dockerfile24 Dockerfile18

graph TB
    subgraph "External"
        remote_server["Remote SSH Server\nuser@host:path"]
mac_client["macOS Finder Client"]
end
    
    subgraph "Container Processes"
        sshfs_proc["sshfs process\n(runs as sshuser)"]
smbd_proc["smbd process\n(runs in foreground)"]
end
    
    subgraph "Filesystem Layer"
        remote_dir["/remote\nFUSE mount point\n(empty until mounted)"]
samba_dir["/samba-share\nSamba root\n(permissions: 777)"]
symlink_dir["/samba-share/remote\nsymbolic link\n(ln -s /remote)"]
end
    
    subgraph "Configuration"
        fuse_conf["/etc/fuse.conf\nuser_allow_other"]
smb_conf["/etc/samba/smb.conf\npath = /samba-share"]
end
    
 
   remote_server -->|SSH connection| sshfs_proc
 
   sshfs_proc -->|mounts to| remote_dir
 
   symlink_dir -.->|points to| remote_dir
 
   samba_dir -->|contains| symlink_dir
 
   smbd_proc -->|serves| samba_dir
 
   smbd_proc -->|reads config| smb_conf
 
   sshfs_proc -->|reads config| fuse_conf
 
   mac_client -->|SMB connection| smbd_proc

Mount Point Usage Patterns

Standard Mount Pattern (Using /remote)

The canonical usage pattern mounts the remote filesystem to /remote, making it accessible via the symbolic link:

After mounting, the directory structure becomes:

/remote/               <- SSHFS mount point (contains remote files)
/samba-share/          <- Samba root (empty except for symlink)
/samba-share/remote/   <- Symbolic link to /remote (provides access)

Sources: Dockerfile30

Alternative Mount Pattern (Direct to /samba-share)

Users may alternatively mount directly to /samba-share, bypassing the symbolic link mechanism:

After mounting, the directory structure becomes:

/remote/               <- Empty (not used)
/samba-share/          <- SSHFS mount point (contains remote files)
/samba-share/remote/   <- Hidden by mount (symbolic link inaccessible)

When mounting directly to /samba-share, the symbolic link at /samba-share/remote becomes inaccessible because it exists inside the mount point. This pattern is simpler but eliminates the separation between the SSHFS mount and Samba share.

Sources: README.md49

stateDiagram-v2
    [*] --> ContainerStart : docker run
    
    ContainerStart --> DirectoriesEmpty : smbd starts
    
    state DirectoriesEmpty {
        [*] --> RemoteEmpty : /remote is empty
        [*] --> SambaShareEmpty : /samba-share contains only symlink
    }
    
    DirectoriesEmpty --> RemoteMounted : sshfs user@host - path /remote
    
    state RemoteMounted {
        [*] --> RemotePopulated : /remote contains remote files
        [*] --> SymlinkActive : /samba-share/remote accessible
    }
    
    RemoteMounted --> DirectoriesEmpty : fusermount -u /remote
    
    note right of RemoteMounted
        /remote : populated with remote files /samba-share - contains symlink /samba-share/remote - provides access
    end note
    
    note right of DirectoriesEmpty
        /remote : empty directory /samba-share - contains only symlink /samba-share/remote - symlink exists but points nowhere
    end note

Directory State Lifecycle

The filesystem directories transition through different states during container operation:

Sources: Dockerfile12 Dockerfile15 Dockerfile30 README.md49 README.md76

Filesystem Permissions Summary

The 777 permissions on /samba-share are set explicitly at Dockerfile21 For detailed information about user identity and permission management, see User and Permissions.

Sources: Dockerfile21

Related Configuration Files

The filesystem layout is tightly coupled with configuration files that control access permissions:

• /etc/fuse.conf : Contains user_allow_other setting (Dockerfile24), which enables the symbolic link to function across different user contexts
• /etc/samba/smb.conf : Defines path = /samba-share as the share root and configures guest access and forced user identity

For complete configuration reference, see Samba Configuration) and FUSE Configuration.

Sources: Dockerfile24 Dockerfile18