README.rst
1SSHFS
2=====
3
4
5About
6-----
7
8SSHFS allows you to mount a remote filesystem using SFTP. Most SSH
9servers support and enable this SFTP access by default, so SSHFS is
10very simple to use - there's nothing to do on the server-side.
11
12
13Development Status
14------------------
15
16SSHFS is shipped by all major Linux distributions and has been in
17production use across a wide range of systems for many years. However,
18at present SSHFS does not have any active, regular contributors, and
19there are a number of known issues (see the bugtracker). The current
20maintainer continues to apply pull requests and makes regular
21releases, but unfortunately has no capacity to do any development
22beyond addressing high-impact issues. When reporting bugs, please
23understand that unless you are including a pull request or are
24reporting a critical issue, you will probably not get a response.
25
26
27How to use
28----------
29
30Once sshfs is installed (see next section) running it is very simple::
31
32 sshfs [user@]hostname:[directory] mountpoint
33
34It is recommended to run SSHFS as regular user (not as root). For
35this to work the mountpoint must be owned by the user. If username is
36omitted SSHFS will use the local username. If the directory is
37omitted, SSHFS will mount the (remote) home directory. If you need to
38enter a password sshfs will ask for it (actually it just runs ssh
39which ask for the password if needed).
40
41Also many ssh options can be specified (see the manual pages for
42*sftp(1)* and *ssh_config(5)*), including the remote port number
43(``-oport=PORT``)
44
45To unmount the filesystem::
46
47 fusermount -u mountpoint
48
49On BSD and macOS, to unmount the filesystem::
50
51 umount mountpoint
52
53
54Installation
55------------
56
57First, download the latest SSHFS release from
58https://github.com/libfuse/sshfs/releases. On Linux and BSD, you will
59also need to install libfuse_ 3.1.0 or newer. On macOS, you need
60OSXFUSE_ instead. Finally, you need the Glib_ library with development
61headers (which should be available from your operating system's
62package manager).
63
64To build and install, we recommend to use Meson_ (version 0.38 or
65newer) and Ninja_. After extracting the sshfs tarball, create a
66(temporary) build directory and run Meson::
67
68 $ mkdir build; cd build
69 $ meson ..
70
71Normally, the default build options will work fine. If you
72nevertheless want to adjust them, you can do so with the *mesonconf*
73command::
74
75 $ mesonconf # list options
76 $ mesonconf -D strip=true # set an option
77
78To build, test and install SSHFS, you then use Ninja (running the
79tests requires the `py.test`_ Python module)::
80
81 $ ninja
82 $ python3 -m pytest test/ # optional, but recommended
83 $ sudo ninja install
84
85.. _libfuse: http://github.com/libfuse/libfuse
86.. _OSXFUSE: https://osxfuse.github.io/
87.. _Glib: https://developer.gnome.org/glib/stable/
88.. _Meson: http://mesonbuild.com/
89.. _Ninja: https://ninja-build.org/
90.. _`py.test`: http://www.pytest.org/
91
92Getting Help
93------------
94
95If you need help, please ask on the <fuse-sshfs@lists.sourceforge.net>
96mailing list (subscribe at
97https://lists.sourceforge.net/lists/listinfo/fuse-sshfs).
98
99Please report any bugs on the GitHub issue tracker at
100https://github.com/libfuse/libfuse/issues.
101