Data transfers - Push to or pull from Gearshift User Interface via Jumphost with GUI on macOS

On macOS you can use SSHFS (SSH File System) to browse the file systems of the Gearshift cluster directly in the Finder With SSHFS you will use the Secure File Transfer Protocol, which is basically FTP tunneled over an SSH connection.

Important: starting from macOS 15.x Sequoia Apple has deprecated the use of kernel extensions (kexts), which will no longer work without overriding system security settings. For file systems developers are now supposed to use a new API instead, but this API is not finished yet nor properly documented yet, so cannot be used. Therefore we currently advise against the use of FUSE for macOS and suggest to use rsync on the command line instead to transfer data securely. For details: * https://github.com/macfuse/macfuse/issues/987 * https://github.com/macfuse/macfuse/issues/1025

SFTP with SSHFS in the Finder

SSHFS simulates a file system over a normal SSH connection and depends on the FUSE libraries, which extend the native macOS file handling capabilities via third-party file systems. Important: SSHFS is great for browsing file systems and transferring data. You may also open a remote file read-only in an application on your Mac for a quick peak at it's content, but you should not open a remote file in read-write mode and start to make changes unless you want to get surprising results; When you loose the network connection, for example due to unstable WiFi or when you put your Mac to sleep, you may loose unsaved changes or worse end up with "half modified" corrupt files. So when you want to modify a remote file, transfer a copy from the remote server to your local Mac, make changes to the copy, save them and transfer the updated file to the server.

1. Install FUSE for macOS

  • Download and install FUSE for macOS from https://osxfuse.github.io/
  • Note: when you are on macOS Catalina or newer, you may get a security warning like this:
    InstallFuseForMacOS
    Open the Security Preferences pane from System Preferences and
    InstallFuseForMacOS
    1: Open the lock to make changes and
    2: Allow the system to load the Fuse for macOS kernel extensions developed by Benjamin Fleischer

2. Install SSHFS for macOS

3. Download and run mount-cluster-drives app

  • Download and unzip the mount-cluster-drives AppleScript application.
  • Locate the mount-cluster-drives app, right click in the Finder application and select Open from the contextual pop-up menu: Launch mount-cluster-drives.app
    Note: when you are on macOS Catalina or newer, you may get a security warning like this:
    Launch mount-cluster-drives.app
    Select Open to continue. (If you started the app by double clicking as opposed to choosing Open from the contextual pop-up menu, the window will look similar, but will lack the Open button allowing you only to Cancel or Move to Bin)
  • Depending on your macOS version, you may receive a pop-up requesting permission to allow access to the Finder application:
    Allow access to the Finder.app
    Click Ok to allow access to the Finder.
    If you want to revoke this permission or change it back to allow later on, you can do so in System Preferences -> Security & Privacy prefs -> Privacy tab -> Automation
  • The mount-cluster-drives app will mount the file systems of all configured clusters in a sub directory of your home dir named ClusterDrives.
    ClusterDrivesInFinder
    You can now drag and drop files in the Finder to transfer to / from Gearshift.
  • To unmount the SSHFS shares click the eject button behind the name of the share.
Technical Details

Some technical details for the curious who like to know how this works or need to debug connection issues:

The mount-cluster-drives app parses special comment lines like this:

#
# Special comment lines parsed by our mount-cluster-drives script to create sshfs mounts.
# (Will be ignored by OpenSSH.)
# 
# 
#SSHFS gearshift_groups=airlock+gearshift:/groups/
#SSHFS gearshift_home=airlock+gearshift:/home/<youraccount>/
#

in the OpenSSH client configuration file for Gearshift ${HOME}/.ssh/conf.d/gearshift, which was created by the ssh-client-config-for-gearshift app from the OpenSSH client configuration instructions for macOS clients page.

The parsed comment lines result in the following mount commands:

sshfs -o "defer_permissions,follow_symlinks,noappledouble,noapplexattr,reconnect,auto_xattr,auto_cache,connecttimeout=10,volname=gearshift_groups" \
         "airlock+gearshift:/groups/" \
         "~/ClusterDrives/gearshift_groups"
sshfs -o "defer_permissions,follow_symlinks,noappledouble,noapplexattr,reconnect,auto_xattr,auto_cache,connecttimeout=10,volname=gearshift_home" \
         "airlock+gearshift:/home/<youraccount>"
         "~/ClusterDrives/gearshift_home"

If you have access to multiple clusters, which were configured in a similar way, you may have multiple SSHFS mounts, which are all mounted with the same mount-cluster-drives app.

Back to operating system independent instructions for data transfers