Configuration Reference

Relevant source files

• Dockerfile
• README.md
• smb.conf

Purpose and Scope

This page provides a comprehensive reference for all configuration settings used by sshfs-mac-docker. The system requires three distinct types of configuration: Samba server configuration (for SMB protocol), FUSE configuration (for filesystem access permissions), and SSHFS mount options (for remote filesystem behavior).

For detailed explanations of specific configuration files and their parameters, see:

• Samba server settings: 5.1)
• FUSE access control: 5.2
• SSHFS mounting parameters: 5.3

This page focuses on the relationships between configurations, their locations in the system, and how they interact to enable the protocol bridge between SSH and SMB.

Configuration Overview

The system uses a layered configuration approach with distinct build-time and runtime settings:

The build-time configurations are embedded in the Docker image via Dockerfile:17-24 while runtime options are specified when executing the sshfs command inside the container.

Sources: Dockerfile:17-24 README.md:49-53

Configuration File Locations

Configuration File Mapping

Diagram: Configuration File Locations and Build Process

The diagram shows how configuration files move from the repository into the container filesystem during the build process, and how they control different aspects of the system at runtime.

Sources: Dockerfile:1-34 smb.conf:1-20

Configuration Hierarchy and Application Points

Build-Time vs Runtime Configuration

Diagram: Configuration Application Timeline

This diagram shows the temporal relationship between configuration application points. Build-time configurations are immutable once the image is created, while runtime configurations can be changed with each mount operation.

Sources: Dockerfile:1-34 README.md:19-53

Configuration Dependencies

Inter-Configuration Dependencies

The three configuration types have strict dependencies that must be satisfied for the system to function:

Diagram: Configuration Dependency Graph

graph TB
    subgraph "FUSE Configuration Dependencies"
        FuseConf["user_allow_other\n/etc/fuse.conf:last line"]
AllowOther["allow_other option\nsshfs mount parameter"]
CrossUserAccess["Samba can access\nSSHFS-mounted files"]
end
    
    subgraph "User and Permission Dependencies"
        SSHUser["sshuser:sshpass\nUID 1000, GID 1000"]
ForceUser["force user = sshuser\nsmb.conf:19"]
UidGidOptions["uid=1000,gid=1000\nsshfs mount parameters"]
FileOwnership["Consistent file ownership\nacross protocols"]
end
    
    subgraph "Directory Permission Dependencies"
        SambaSharePerm["chmod 777 /samba-share\nDockerfile:21"]
Writable["writable = yes\nsmb.conf:12"]
CreateMask["create mask = 0777\nsmb.conf:17"]
WriteAccess["Write access\nfrom macOS"]
end
    
    subgraph "Guest Access Dependencies"
        MapToGuest["map to guest = bad user\nsmb.conf:4"]
GuestOk["guest ok = yes\nsmb.conf:13"]
GuestOnly["guest only = yes\nsmb.conf:14"]
NoAuth["No password required\nfrom macOS"]
end
    
 
   FuseConf -->|Enables| AllowOther
 
   AllowOther -->|Required for| CrossUserAccess
    
 
   SSHUser -->|Identity enforced by| ForceUser
 
   SSHUser -->|UID/GID matched by| UidGidOptions
 
   ForceUser --> FileOwnership
 
   UidGidOptions --> FileOwnership
    
 
   SambaSharePerm -->|Base permissions| WriteAccess
 
   Writable -->|Samba-level permissions| WriteAccess
 
   CreateMask -->|New file permissions| WriteAccess
    
 
   MapToGuest -->|Maps unknown users| NoAuth
 
   GuestOk -->|Allows guest login| NoAuth
 
   GuestOnly -->|Forces guest mode| NoAuth

This diagram illustrates critical dependencies between configuration parameters. If any dependency is missing, specific functionality (cross-user access, write access, or guest authentication) will fail.

Sources: smb.conf:1-20 Dockerfile:9-24 README.md:49-53

Critical Configuration Parameters

Parameter Reference Table

Configuration Omission Impact

Diagram: Configuration Omission Impact

This diagram shows the direct consequences of missing critical configuration parameters. Each omission results in a specific failure mode.

Sources: Dockerfile24 README.md:49-53 smb.conf19

Configuration Interaction Model

Protocol Bridge Configuration Flow

Diagram: Configuration Interaction During Write Operation

This diagram traces how configuration parameters interact when a file write operation flows from macOS Finder through Samba, the filesystem layer, SSHFS, and finally to the remote server. Each layer consults its configuration to validate and process the operation.

Sources: smb.conf:1-20 Dockerfile:21-30 README.md:49-53

Configuration Validation Checklist

Use this checklist to verify that all configurations are correctly applied:

Build-Time Configuration Verification

Runtime Configuration Verification

Sources: Dockerfile:1-34 smb.conf:1-20 README.md:19-53

Configuration Modification Guidelines

Which Configurations Can Be Changed

Changing SSHFS Mount Options

SSHFS mount options are the only runtime-configurable settings. To change them:

1. Unmount the existing mount: fusermount -u /samba-share
2. Mount with new options: sshfs -o [new-options] user@host:path /samba-share

Common option modifications:

• Change ownership : Modify uid= and gid= values
• Add compression : Include compression=yes
• Adjust timeout : Include ServerAliveInterval=15
• Enable debug : Include debug,sshfs_debug,loglevel=debug

Sources: README.md:49-77

Configuration Files Summary

Complete File Reference

Diagram: Configuration Files and Their Relationships

This diagram maps the repository files to the container filesystem files they create or modify. All configuration originates from the two repository files: smb.conf and Dockerfile.

Sources: Dockerfile:1-34 smb.conf:1-20

For detailed documentation of specific configuration files and their parameters, continue to:

• 5.1 Samba Configuration (smb.conf)) - Complete reference for all smb.conf parameters
• 5.2 FUSE Configuration - FUSE access control and user_allow_other setting
• 5.3 SSHFS Mount Options - Runtime mount options including allow_other, uid, and gid