SSHMount Driver¶

jumpstarter-driver-ssh-mount provides remote filesystem mounting via sshfs. It allows you to mount remote directories from a target device to your local machine using SSHFS (SSH Filesystem).

Installation¶

pip3 install --extra-index-url https://pkg.jumpstarter.dev/simple/ jumpstarter-driver-ssh-mount

You also need sshfs installed on the client machine:

Fedora/RHEL: sudo dnf install fuse-sshfs
Debian/Ubuntu: sudo apt-get install sshfs
macOS: Install macFUSE and SSHFS from https://macfuse.github.io/, please note that it needs special handling to enable the macOS kernel extensions, read the install documentation carefully.

Configuration¶

The SSHMount driver references an existing SSH driver to inherit credentials (username, identity key) and TCP connectivity. No duplicate configuration is needed.

Example exporter configuration:

export:
  ssh:
    type: jumpstarter_driver_ssh.driver.SSHWrapper
    config:
      default_username: "root"
      # ssh_identity_file: "/path/to/ssh/key"
    children:
      tcp:
        type: jumpstarter_driver_network.driver.TcpNetwork
        config:
          host: "192.168.1.100"
          port: 22
  mount:
    type: jumpstarter_driver_ssh_mount.driver.SSHMount
    children:
      ssh:
        ref: "ssh"

CLI Usage¶

Inside a jmp shell session:

# Mount remote filesystem (spawns a subshell; type 'exit' to unmount)
j mount /local/mountpoint
j mount /local/mountpoint -r /remote/path
j mount /local/mountpoint --direct

# Mount in foreground mode (blocks until Ctrl+C)
j mount /local/mountpoint --foreground

# Pass extra sshfs options (-o forwards each value as an sshfs -o flag)
j mount /local/mountpoint -o reconnect -o cache=yes

# Override default SSH options (e.g., enable host key checking)
j mount /local/mountpoint -o StrictHostKeyChecking=yes

# Allow other users to access the mount (requires user_allow_other in /etc/fuse.conf)
j mount /local/mountpoint -o allow_other

# Unmount an orphaned mount
j mount --umount /local/mountpoint
j mount --umount /local/mountpoint --lazy

By default, j mount runs sshfs in foreground mode and spawns a subshell with a modified prompt. The mount stays active while the subshell is running. When you type exit (or press Ctrl+D), sshfs is terminated and all resources (port forwards, temporary identity files) are cleaned up automatically.

Use --foreground to skip the subshell and block directly on sshfs. Press Ctrl+C to unmount.

The --umount flag is available as a fallback for mounts that were orphaned (e.g., if the process was killed without cleanup).

API Reference¶

SSHMountClient¶

mount(mountpoint, *, remote_path="/", direct=False, foreground=False, extra_args=None) - Mount remote filesystem locally via sshfs
umount(mountpoint, *, lazy=False) - Unmount an sshfs filesystem (fallback for orphaned mounts)

Required Children¶

Child name	Type	Description
`ssh`	`jumpstarter_driver_ssh.driver.SSHWrapper`	SSH driver providing credentials (username, identity key) and TCP connectivity. Must itself have a `tcp` child of type `TcpNetwork`.

CLI¶

The driver registers as mount in the exporter config. When used in a jmp shell session, the CLI is a single command with a --umount flag for unmounting.

Note: Each -o value is forwarded directly to sshfs as an -o option flag. You can pass any option that sshfs (and by extension, the underlying SSH client) supports. By default, the driver sets StrictHostKeyChecking=no, UserKnownHostsFile=/dev/null, and LogLevel=ERROR. To override a default, pass the replacement via -o (e.g., -o StrictHostKeyChecking=yes). Common options include reconnect, cache=yes, ServerAliveInterval=15, and compression=yes. If you need other users on the system to access the mounted filesystem, pass -o allow_other (requires user_allow_other in /etc/fuse.conf). If allow_other fails due to FUSE configuration, the mount will automatically retry without it.