1 .\" Man page generated from reStructuredText.
2 .
3 .TH SSHFS 1 "" "" "User Commands"
4 .SH NAME
5 SSHFS \- filesystem client based on SSH
6 .
7 .nr rst2man-indent-level 0
8 .
9 .de1 rstReportMargin
10 \\$1 \\n[an-margin]
11 level \\n[rst2man-indent-level]
12 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
13 -
14 \\n[rst2man-indent0]
15 \\n[rst2man-indent1]
16 \\n[rst2man-indent2]
17 ..
18 .de1 INDENT
19 .\" .rstReportMargin pre:
20 . RS \\$1
21 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
22 . nr rst2man-indent-level +1
23 .\" .rstReportMargin post:
24 ..
25 .de UNINDENT
26 . RE
27 .\" indent \\n[an-margin]
28 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
29 .nr rst2man-indent-level -1
30 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
31 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
32 ..
33 .SH SYNOPSIS
34 .sp
35 To mount a filesystem:
36 .INDENT 0.0
37 .INDENT 3.5
38 .sp
39 .nf
40 .ft C
41 sshfs [user@]host:[dir] mountpoint [options]
42 .ft P
43 .fi
44 .UNINDENT
45 .UNINDENT
46 .sp
47 If \fIhost\fP is a numeric IPv6 address, it needs to be enclosed in square
48 brackets.
49 .sp
50 To unmount it:
51 .INDENT 0.0
52 .INDENT 3.5
53 .sp
54 .nf
55 .ft C
56 fusermount3 \-u mountpoint # Linux
57 umount mountpoint # OS X, FreeBSD
58 .ft P
59 .fi
60 .UNINDENT
61 .UNINDENT
62 .SH DESCRIPTION
63 .sp
64 SSHFS allows you to mount a remote filesystem using SSH (more
65 precisely, the SFTP subsystem). Most SSH servers support and enable
66 this SFTP access by default, so SSHFS is very simple to use \- there\(aqs
67 nothing to do on the server\-side.
68 .sp
69 SSHFS uses FUSE (Filesystem in Userspace) and should work on any
70 operating system that provides a FUSE implementation. Currently,
71 this includes Linux, FreeBSD and Mac OS X.
72 .sp
73 It is recommended to run SSHFS as regular user (not as root). For
74 this to work the mountpoint must be owned by the user. If username is
75 omitted SSHFS will use the local username. If the directory is
76 omitted, SSHFS will mount the (remote) home directory. If you need to
77 enter a password sshfs will ask for it (actually it just runs ssh
78 which ask for the password if needed).
79 .SH OPTIONS
80 .INDENT 0.0
81 .TP
82 .B \-o opt,[opt...]
83 mount options, see below for details. A a variety of SSH options can
84 be given here as well, see the manual pages for \fIsftp(1)\fP and
85 \fIssh_config(5)\fP\&.
86 .UNINDENT
87 .INDENT 0.0
88 .TP
89 .B \-h\fP,\fB \-\-help
90 print help and exit.
91 .TP
92 .B \-V\fP,\fB \-\-version
93 print version information and exit.
94 .TP
95 .B \-d\fP,\fB \-\-debug
96 print debugging information.
97 .TP
98 .BI \-p \ PORT
99 equivalent to \(aq\-o port=PORT\(aq
100 .TP
101 .B \-f
102 do not daemonize, stay in foreground.
103 .TP
104 .B \-s
105 Single threaded operation.
106 .TP
107 .B \-C
108 equivalent to \(aq\-o compression=yes\(aq
109 .TP
110 .BI \-F \ ssh_configfile
111 specifies alternative ssh configuration file
112 .TP
113 .B \-1
114 equivalent to \(aq\-o ssh_protocol=1\(aq
115 .TP
116 .BI \-o \ reconnect
117 automatically reconnect to server if connection is
118 interrupted. Attempts to access files that were opened before the
119 reconnection will give errors and need to be re\-opened.
120 .TP
121 .BI \-o \ delay_connect
122 Don\(aqt immediately connect to server, wait until mountpoint is first
123 accessed.
124 .TP
125 .BI \-o \ sshfs_sync
126 synchronous writes. This will slow things down, but may be useful
127 in some situations.
128 .TP
129 .BI \-o \ no_readahead
130 Only read exactly the data that was requested, instead of
131 speculatively reading more to anticipate the next read request.
132 .TP
133 .BI \-o \ sync_readdir
134 synchronous readdir. This will slow things down, but may be useful
135 in some situations.
136 .UNINDENT
137 .INDENT 0.0
138 .TP
139 .B \-o workaround=LIST
140 Enable the specified workaround. See the \fICaveats\fP section below
141 for some additional information. Possible values are:
142 .INDENT 7.0
143 .TP
144 .B rename
145 Emulate overwriting an existing file by deleting and
146 renaming.
147 .TP
148 .B renamexdev
149 Make rename fail with EXDEV instead of the default EPERM
150 to allow moving files across remote filesystems.
151 .TP
152 .B truncate
153 Work around servers that don\(aqt support truncate by
154 coping the whole file, truncating it locally, and sending it
155 back.
156 .TP
157 .B fstat
158 Work around broken servers that don\(aqt support \fIfstat()\fP by
159 using \fIstat\fP instead.
160 .TP
161 .B buflimit
162 Work around OpenSSH "buffer fillup" bug.
163 .TP
164 .B createmode
165 Work around broken servers that produce an error when passing a
166 non\-zero mode to create, by always passing a mode of 0.
167 .UNINDENT
168 .TP
169 .B \-o idmap=TYPE
170 How to map remote UID/GIDs to local values. Possible values are:
171 .INDENT 7.0
172 .TP
173 .B none
174 no translation of the ID space (default).
175 .TP
176 .B user
177 map the UID/GID of the remote user to UID/GID of the
178 mounting user.
179 .TP
180 .B file
181 translate UIDs/GIDs based upon the contents of \fI\-\-uidfile\fP
182 and \fI\-\-gidfile\fP\&.
183 .UNINDENT
184 .TP
185 .B \-o uidfile=FILE
186 file containing \fBusername:uid\fP mappings for \fI\-o idmap=file\fP
187 .TP
188 .B \-o gidfile=FILE
189 file containing \fBgroupname:gid\fP mappings for \fI\-o idmap=file\fP
190 .TP
191 .B \-o nomap=TYPE
192 with idmap=file, how to handle missing mappings:
193 .INDENT 7.0
194 .TP
195 .B ignore
196 don\(aqt do any re\-mapping
197 .TP
198 .B error
199 return an error (default)
200 .UNINDENT
201 .TP
202 .B \-o ssh_command=CMD
203 execute CMD instead of \(aqssh\(aq
204 .TP
205 .B \-o ssh_protocol=N
206 ssh protocol to use (default: 2)
207 .TP
208 .B \-o sftp_server=SERV
209 path to sftp server or subsystem (default: sftp)
210 .TP
211 .B \-o directport=PORT
212 directly connect to PORT bypassing ssh
213 .UNINDENT
214 .INDENT 0.0
215 .TP
216 .BI \-o \ slave
217 communicate over stdin and stdout bypassing network
218 .TP
219 .BI \-o \ disable_hardlink
220 With this option set, attempts to call \fIlink(2)\fP will fail with
221 error code ENOSYS.
222 .TP
223 .BI \-o \ transform_symlinks
224 transform absolute symlinks on remote side to relative
225 symlinks. This means that if e.g. on the server side
226 \fB/foo/bar/com\fP is a symlink to \fB/foo/blub\fP, SSHFS will
227 transform the link target to \fB\&../blub\fP on the client side.
228 .TP
229 .BI \-o \ follow_symlinks
230 follow symlinks on the server, i.e. present them as regular
231 files on the client. If a symlink is dangling (i.e, the target does
232 not exist) the behavior depends on the remote server \- the entry
233 may appear as a symlink on the client, or it may appear as a
234 regular file that cannot be accessed.
235 .TP
236 .BI \-o \ no_check_root
237 don\(aqt check for existence of \(aqdir\(aq on server
238 .TP
239 .BI \-o \ password_stdin
240 read password from stdin (only for pam_mount!)
241 .UNINDENT
242 .INDENT 0.0
243 .TP
244 .B \-o dir_cache=BOOL
245 Enables (\fIyes\fP) or disables (\fIno\fP) the SSHFS directory cache. The
246 directory cache holds the names of directory entries. Enabling it
247 allows \fIreaddir(3)\fP system calls to be processed without network
248 access.
249 .TP
250 .B \-o dcache_max_size=N
251 sets the maximum size of the directory cache.
252 .TP
253 .B \-o dcache_timeout=N
254 sets timeout for directory cache in seconds.
255 .TP
256 .B \-o dcache_{stat,link,dir}_timeout=N
257 sets separate timeout for {attributes, symlinks, names} in the
258 directory cache.
259 .TP
260 .B \-o dcache_clean_interval=N
261 sets the interval for automatic cleaning of the directory cache.
262 .TP
263 .B \-o dcache_min_clean_interval=N
264 sets the interval for forced cleaning of the directory cache
265 when full.
266 .UNINDENT
267 .INDENT 0.0
268 .TP
269 .BI \-o \ direct_io
270 This option disables the use of page cache (file content cache) in
271 the kernel for this filesystem.
272 This has several affects:
273 1. Each read() or write() system call will initiate one or more read or
274 .IP "System Message: ERROR/3 (../sshfs.rst:, line 210)"
275 Unexpected indentation.
276 .INDENT 7.0
277 .INDENT 3.5
278 write operations, data will not be cached in the kernel.
279 .UNINDENT
280 .UNINDENT
281 .IP "System Message: WARNING/2 (../sshfs.rst:, line 211)"
282 Block quote ends without a blank line; unexpected unindent.
283 .INDENT 7.0
284 .IP 2. 3
285 The return value of the read() and write() system calls will correspond
286 to the return values of the read and write operations. This is useful
287 for example if the file size is not known in advance (before reading it).
288 e.g. /proc filesystem
289 .UNINDENT
290 .UNINDENT
291 .sp
292 In addition, SSHFS accepts several options common to all FUSE file
293 systems. These are described in the \fImount.fuse\fP manpage (look
294 for "general", "libfuse specific", and "high\-level API" options).
295 .SH CAVEATS / WORKAROUNDS
296 .SS Hardlinks
297 .sp
298 If the SSH server supports the \fIhardlinks\fP extension, SSHFS will allow
299 you to create hardlinks. However, hardlinks will always appear as
300 individual files when seen through an SSHFS mount, i.e. they will
301 appear to have different inodes and an \fIst_nlink\fP value of 1.
302 .SS Rename
303 .sp
304 Some SSH servers do not support atomically overwriting the destination
305 when renaming a file. In this case you will get an error when you
306 attempt to rename a file and the destination already exists. A
307 workaround is to first remove the destination file, and then do the
308 rename. SSHFS can do this automatically if you call it with \fI\-o
309 workaround=rename\fP\&. However, in this case it is still possible that
310 someone (or something) recreates the destination file after SSHFS has
311 removed it, but before SSHFS had the time to rename the old file. In
312 this case, the rename will still fail.
313 .SS Permission denied when moving files across remote filesystems
314 .sp
315 Most SFTP servers return only a generic "failure" when failing to rename
316 across filesystem boundaries (EXDEV). sshfs normally converts this generic
317 failure to a permission denied error (EPERM). If the option \fB\-o
318 workaround=renamexdev\fP is given, generic failures will be considered EXDEV
319 errors which will make programs like \fImv(1)\fP attempt to actually move the
320 file after the failed rename.
321 .SS SSHFS hangs for no apparent reason
322 .sp
323 In some cases, attempts to access the SSHFS mountpoint may freeze if
324 no filesystem activity has occured for some time. This is typically
325 caused by the SSH connection being dropped because of inactivity
326 without SSHFS being informed about that. As a workaround, you can try
327 to mount with \fB\-o ServerAliveInterval=15\fP\&. This will force the SSH
328 connection to stay alive even if you have no activity.
329 .SS SSHFS hangs after the connection was interrupted
330 .sp
331 By default, network operations in SSHFS run without timeouts, mirroring the
332 default behavior of SSH itself. As a consequence, if the connection to the
333 remote host is interrupted (e.g. because a network cable was removed),
334 operations on files or directories under the mountpoint will block until the
335 connection is either restored or closed altogether (e.g. manually).
336 Applications that try to access such files or directories will generally appear
337 to "freeze" when this happens.
338 .sp
339 If it is acceptable to discard data being read or written, a quick workaround
340 is to kill the responsible \fBsshfs\fP process, which will make any blocking
341 operations on the mounted filesystem error out and thereby "unfreeze" the
342 relevant applications. Note that force unmounting with \fBfusermount \-zu\fP, on
343 the other hand, does not help in this case and will leave read/write operations
344 in the blocking state.
345 .sp
346 For a more automatic solution, one can use the \fB\-o ServerAliveInterval=15\fP
347 option mentioned above, which will drop the connection after not receiving a
348 response for 3 * 15 = 45 seconds from the remote host. By also supplying \fB\-o
349 reconnect\fP, one can ensure that the connection is re\-established as soon as
350 possible afterwards. As before, this will naturally lead to loss of data that
351 was in the process of being read or written at the time when the connection was
352 interrupted.
353 .SH MOUNTING FROM /ETC/FSTAB
354 .sp
355 To mount an SSHFS filesystem from \fB/etc/fstab\fP, simply use \fBsshfs\(ga
356 as the file system type. (For backwards compatibility, you may also
357 use \(ga\(gafuse.sshfs\fP).
358 .SH SEE ALSO
359 .sp
360 The \fImount.fuse(8)\fP manpage.
361 .SH GETTING HELP
362 .sp
363 If you need help, please ask on the <\fI\%fuse\-sshfs@lists.sourceforge.net\fP>
364 mailing list (subscribe at
365 \fI\%https://lists.sourceforge.net/lists/listinfo/fuse\-sshfs\fP).
366 .sp
367 Please report any bugs on the GitHub issue tracker at
368 \fI\%https://github.com/libfuse/libfuse/issues\fP\&.
369 .SH AUTHORS
370 .sp
371 SSHFS is currently maintained by Nikolaus Rath <\fI\%Nikolaus@rath.org\fP>,
372 and was created by Miklos Szeredi <\fI\%miklos@szeredi.hu\fP>.
373 .sp
374 This man page was originally written by Bartosz Fenski
375 <\fI\%fenio@debian.org\fP> for the Debian GNU/Linux distribution (but it may
376 be used by others).
377 .\" Generated by docutils manpage writer.
378 .
|
