summary refs log tree commit diff
path: root/nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml
diff options
context:
space:
mode:
Diffstat (limited to 'nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml')
-rw-r--r--nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml139
1 files changed, 139 insertions, 0 deletions
diff --git a/nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml b/nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml
new file mode 100644
index 00000000000..5d74712f35d
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/sshfs-file-systems.section.xml
@@ -0,0 +1,139 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-sshfs-file-systems">
+  <title>SSHFS File Systems</title>
+  <para>
+    <link xlink:href="https://github.com/libfuse/sshfs">SSHFS</link> is
+    a
+    <link xlink:href="https://en.wikipedia.org/wiki/Filesystem_in_Userspace">FUSE</link>
+    filesystem that allows easy access to directories on a remote
+    machine using the SSH File Transfer Protocol (SFTP). It means that
+    if you have SSH access to a machine, no additional setup is needed
+    to mount a directory.
+  </para>
+  <section xml:id="sec-sshfs-interactive">
+    <title>Interactive mounting</title>
+    <para>
+      In NixOS, SSHFS is packaged as <package>sshfs</package>. Once
+      installed, mounting a directory interactively is simple as
+      running:
+    </para>
+    <programlisting>
+$ sshfs my-user@example.com:/my-dir /mnt/my-dir
+</programlisting>
+    <para>
+      Like any other FUSE file system, the directory is unmounted using:
+    </para>
+    <programlisting>
+$ fusermount -u /mnt/my-dir
+</programlisting>
+  </section>
+  <section xml:id="sec-sshfs-non-interactive">
+    <title>Non-interactive mounting</title>
+    <para>
+      Mounting non-interactively requires some precautions because
+      <literal>sshfs</literal> will run at boot and under a different
+      user (root). For obvious reason, you can’t input a password, so
+      public key authentication using an unencrypted key is needed. To
+      create a new key without a passphrase you can do:
+    </para>
+    <programlisting>
+$ ssh-keygen -t ed25519 -P '' -f example-key
+Generating public/private ed25519 key pair.
+Your identification has been saved in test-key
+Your public key has been saved in test-key.pub
+The key fingerprint is:
+SHA256:yjxl3UbTn31fLWeyLYTAKYJPRmzknjQZoyG8gSNEoIE my-user@workstation
+</programlisting>
+    <para>
+      To keep the key safe, change the ownership to
+      <literal>root:root</literal> and make sure the permissions are
+      <literal>600</literal>: OpenSSH normally refuses to use the key if
+      it’s not well-protected.
+    </para>
+    <para>
+      The file system can be configured in NixOS via the usual
+      <link linkend="opt-fileSystems">fileSystems</link> option. Here’s
+      a typical setup:
+    </para>
+    <programlisting language="bash">
+{
+  system.fsPackages = [ pkgs.sshfs ];
+
+  fileSystems.&quot;/mnt/my-dir&quot; = {
+    device = &quot;my-user@example.com:/my-dir/&quot;;
+    fsType = &quot;sshfs&quot;;
+    options =
+      [ # Filesystem options
+        &quot;allow_other&quot;          # for non-root access
+        &quot;_netdev&quot;              # this is a network fs
+        &quot;x-systemd.automount&quot;  # mount on demand
+
+        # SSH options
+        &quot;reconnect&quot;              # handle connection drops
+        &quot;ServerAliveInterval=15&quot; # keep connections alive
+        &quot;IdentityFile=/var/secrets/example-key&quot;
+      ];
+  };
+}
+</programlisting>
+    <para>
+      More options from <literal>ssh_config(5)</literal> can be given as
+      well, for example you can change the default SSH port or specify a
+      jump proxy:
+    </para>
+    <programlisting language="bash">
+{
+  options =
+    [ &quot;ProxyJump=bastion@example.com&quot;
+      &quot;Port=22&quot;
+    ];
+}
+</programlisting>
+    <para>
+      It’s also possible to change the <literal>ssh</literal> command
+      used by SSHFS to connect to the server. For example:
+    </para>
+    <programlisting language="bash">
+{
+  options =
+    [ (builtins.replaceStrings [&quot; &quot;] [&quot;\\040&quot;]
+        &quot;ssh_command=${pkgs.openssh}/bin/ssh -v -L 8080:localhost:80&quot;)
+    ];
+
+}
+</programlisting>
+    <note>
+      <para>
+        The escaping of spaces is needed because every option is written
+        to the <literal>/etc/fstab</literal> file, which is a
+        space-separated table.
+      </para>
+    </note>
+    <section xml:id="sec-sshfs-troubleshooting">
+      <title>Troubleshooting</title>
+      <para>
+        If you’re having a hard time figuring out why mounting is
+        failing, you can add the option
+        <literal>&quot;debug&quot;</literal>. This enables a verbose log
+        in SSHFS that you can access via:
+      </para>
+      <programlisting>
+$ journalctl -u $(systemd-escape -p /mnt/my-dir/).mount
+Jun 22 11:41:18 workstation mount[87790]: SSHFS version 3.7.1
+Jun 22 11:41:18 workstation mount[87793]: executing &lt;ssh&gt; &lt;-x&gt; &lt;-a&gt; &lt;-oClearAllForwardings=yes&gt; &lt;-oServerAliveInterval=15&gt; &lt;-oIdentityFile=/var/secrets/wrong-key&gt; &lt;-2&gt; &lt;my-user@example.com&gt; &lt;-s&gt; &lt;sftp&gt;
+Jun 22 11:41:19 workstation mount[87793]: my-user@example.com: Permission denied (publickey).
+Jun 22 11:41:19 workstation mount[87790]: read: Connection reset by peer
+Jun 22 11:41:19 workstation systemd[1]: mnt-my\x2ddir.mount: Mount process exited, code=exited, status=1/FAILURE
+Jun 22 11:41:19 workstation systemd[1]: mnt-my\x2ddir.mount: Failed with result 'exit-code'.
+Jun 22 11:41:19 workstation systemd[1]: Failed to mount /mnt/my-dir.
+Jun 22 11:41:19 workstation systemd[1]: mnt-my\x2ddir.mount: Consumed 54ms CPU time, received 2.3K IP traffic, sent 2.7K IP traffic.
+</programlisting>
+      <note>
+        <para>
+          If the mount point contains special characters it needs to be
+          escaped using <literal>systemd-escape</literal>. This is due
+          to the way systemd converts paths into unit names.
+        </para>
+      </note>
+    </section>
+  </section>
+</section>