logo

oasis

Own branch of Oasis Linux (upstream: <https://git.sr.ht/~mcf/oasis/>) git clone https://anongit.hacktivis.me/git/oasis.git

sshfs.1 (12120B)


  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. .