1GOCRYPTFS(1) GOCRYPTFS(1)
2
6 gocryptfs - create or mount an encrypted filesystem
7
9 Initialize new encrypted filesystem
10 gocryptfs -init [OPTIONS] CIPHERDIR
11 Mount
13 gocryptfs [OPTIONS] CIPHERDIR MOUNTPOINT [-o COMMA-SEPARATED-OPTIONS]
14 Unmount
16 fusermount -u MOUNTPOINT
17 Change password
19 gocryptfs -passwd [OPTIONS] CIPHERDIR
20 Check consistency
22 gocryptfs -fsck [OPTIONS] CIPHERDIR
23
25 gocryptfs is an encrypted overlay filesystem written in Go. Encrypted
26 files are stored in CIPHERDIR, and a plain-text view can be presented
27 by mounting the filesystem at MOUNTPOINT.
28 gocryptfs was inspired by encfs(1) and strives to fix its security is‐
30 sues while providing good performance.
31
33 Available options are listed below. Usually, you don’t need any. De‐
34 faults are fine.
35 -aessiv
37 Use the AES-SIV encryption mode. This is slower than GCM but is secure
38 with deterministic nonces as used in “-reverse” mode.
39 -allow_other
41 By default, the Linux kernel prevents any other user (even root) to ac‐
42 cess a mounted FUSE filesystem. Settings this option allows access for
43 other users, subject to file permission checking. Only works if us‐
44 er_allow_other is set in /etc/fuse.conf. This option is equivalent to
45 “allow_other” plus “default_permissions” described in fuse(8).
46 -config string
48 Use specified config file instead of CIPHERDIR/gocryptfs.conf.
49 -cpuprofile string
51 Write cpu profile to specified file.
52 -ctlsock string
54 Create a control socket at the specified location. The socket can be
55 used to decrypt and encrypt paths inside the filesystem. When using
56 this option, make sure that the directory you place the socket in is
57 not world-accessible. For example, /run/user/UID/my.socket would be
58 suitable.
59 -d, -debug
61 Enable debug output.
62 -dev, -nodev
64 Enable (-dev) or disable (-nodev) device files in a gocryptfs mount
65 (default: -nodev). If both are specified, -nodev takes precedence.
66 You need root permissions to use -dev.
67 -devrandom
69 Use /dev/random for generating the master key instead of the default Go
70 implementation. This is especially useful on embedded systems with Go
71 versions prior to 1.9, which fall back to weak random data when the ge‐
72 trandom syscall is blocking. Using this option can block indefinitely
73 when the kernel cannot harvest enough entropy.
74 -e PATH, -exclude PATH
76 Only for reverse mode: exclude relative plaintext path from the en‐
77 crypted view, matching only from root of mounted filesystem. Can be
78 passed multiple times. Example:
79 gocryptfs -reverse -exclude Music -exclude Movies /home/user /mnt/user.encrypted
81 See also -exclude-wildcard, -exclude-from and the EXCLUDING FILES sec‐
83 tion.
84 -ew PATH, -exclude-wildcard PATH
86 Only for reverse mode: exclude paths from the encrypted view, matching
87 anywhere. Wildcards supported. Can be passed multiple times. Exam‐
88 ple:
89 gocryptfs -reverse -exclude-wildcard '*~' /home/user /mnt/user.encrypted
91 See also -exclude, -exclude-from and the EXCLUDING FILES section.
93 -exclude-from FILE
95 Only for reverse mode: reads exclusion patters (using -exclude-wildcard
96 syntax) from a file. Can be passed multiple times. Example:
97 gocryptfs -reverse -exclude-from ~/crypt-exclusions /home/user /mnt/user.encrypted
99 See also -exclude, -exclude-wildcard and the EXCLUDING FILES section.
101 -exec, -noexec
103 Enable (-exec) or disable (-noexec) executables in a gocryptfs mount
104 (default: -exec). If both are specified, -noexec takes precedence.
105 -extpass string
107 Use an external program (like ssh-askpass) for the password prompt.
108 The program should return the password on stdout, a trailing newline is
109 stripped by gocryptfs. If you just want to read from a password file,
110 see -passfile.
111 When -extpass is specified once, the string argument will be split on
113 spaces. For example, -extpass "md5sum my password.txt" will be execut‐
114 ed as "md5sum" "my" "password.txt", which is NOT what you want.
115 Specify -extpass twice or more to use the string arguments as-is. For
117 example, you DO want to call md5sum like this: -extpass "md5sum"
118 -extpass "my password.txt".
119 If you want to prevent splitting on spaces but don’t want to pass argu‐
121 ments to your program, use "--", which is accepted by most programs:
122 -extpass "my program" -extpass "--"
123 -fg, -f
125 Stay in the foreground instead of forking away. Implies “-nosyslog”.
126 For compatibility, “-f” is also accepted, but “-fg” is preferred.
127 -force_owner string
129 If given a string of the form “uid:gid” (where both “uid” and “gid” are
130 substituted with positive integers), presents all files as owned by the
131 given uid and gid, regardless of their actual ownership. Implies “al‐
132 low_other”.
133 This is rarely desired behavior: One should usually run gocryptfs as
135 the account which owns the backing-store files, which should usually be
136 one and the same with the account intended to access the decrypted con‐
137 tent. An example of a case where this may be useful is a situation
138 where content is stored on a filesystem that doesn’t properly support
139 UNIX ownership and permissions.
140 -forcedecode
142 Force decode of encrypted files even if the integrity check fails, in‐
143 stead of failing with an IO error. Warning messages are still printed
144 to syslog if corrupted files are encountered. It can be useful to re‐
145 cover files from disks with bad sectors or other corrupted media. It
146 shall not be used if the origin of corruption is unknown, specially if
147 you want to run executable files.
148 For corrupted media, note that you probably want to use dd_rescue(1)
150 instead, which will recover all but the corrupted 4kB block.
151 This option makes no sense in reverse mode. It requires gocryptfs to
153 be compiled with openssl support and implies -openssl true. Because of
154 this, it is not compatible with -aessiv, that uses built-in Go crypto.
155 Setting this option forces the filesystem to read-only and noexec.
157 -fsck
159 Check CIPHERDIR for consistency. If corruption is found, the exit code
160 is 26.
161 -fsname string
163 Override the filesystem name (first column in df -T). Can also be
164 passed as “-o fsname=” and is equivalent to libfuse’s option of the
165 same name. By default, CIPHERDIR is used.
166 -fusedebug
168 Enable fuse library debug output.
169 -h, -help
171 Print a short help text that shows the more-often used options.
172 -hh
174 Long help text, shows all available options.
175 -hkdf
177 Use HKDF to derive separate keys for content and name encryption from
178 the master key.
179 -i duration, -idle duration
181 Only for forward mode: automatically unmount the filesystem if it has
182 been idle for the specified duration. Durations can be specified like
183 “500s” or “2h45m”. 0 (the default) means stay mounted indefinitely.
184 -info
186 Pretty-print the contents of the config file for human consumption,
187 stripping out sensitive data.
188 -init
190 Initialize encrypted directory.
191 -ko
193 Pass additional mount options to the kernel (comma-separated list).
194 FUSE filesystems are mounted with “nodev,nosuid” by default. If
195 gocryptfs runs as root, you can enable device files by passing the op‐
196 posite mount option, “dev”, and if you want to enable suid-binaries,
197 pass “suid”. “ro” (equivalent to passing the “-ro” option) and “noex‐
198 ec” may also be interesting. For a complete list see the section
199 FILESYSTEM-INDEPENDENT MOUNT OPTIONS in mount(8). On MacOS, “local”,
200 “noapplexattr”, “noappledouble” may be interesting.
201 Note that unlike “-o”, “-ko” is a regular option and must be passed BE‐
203 FORE the directories. Example:
204 gocryptfs -ko noexec /tmp/foo /tmp/bar
206 -longnames
208 Store names longer than 176 bytes in extra files (default true) This
209 flag is useful when recovering old gocryptfs filesystems using “-mas‐
210 terkey”. It is ignored (stays at the default) otherwise.
211 -masterkey string
213 Use a explicit master key specified on the command line or, if the spe‐
214 cial value “stdin” is used, read the masterkey from stdin. This option
215 can be used to mount a gocryptfs filesystem without a config file.
216 Note that the command line, and with it the master key, is visible to
217 anybody on the machine who can execute “ps -auxwww”. Use “-mas‐
218 terkey=stdin” to avoid that risk.
219 The masterkey option is meant as a recovery option for emergencies,
221 such as if you have forgotten the password or lost the config file.
222 Even if a config file exists, it will not be used. All non-standard
224 settings have to be passed on the command line: -aessiv when you mount
225 a filesystem that was created using reverse mode, or -plaintextnames
226 for a filesystem that was created with that option.
227 Examples:
229 -masterkey=6f717d8b-6b5f8e8a-fd0aa206-778ec093-62c5669b-abd229cd-241e00cd-b4d6713d
231 -masterkey=stdin
232 -memprofile string
234 Write memory profile to the specified file. This is useful when debug‐
235 ging memory usage of gocryptfs.
236 -nodev
238 See -dev, -nodev.
239 -noexec
241 See -exec, -noexec.
242 -nofail
244 Having the nofail option in /etc/fstab instructs systemd to continue
245 booting normally even if the mount fails (see man systemd.fstab).
246 The option is ignored by gocryptfs itself and has no effect outside
248 /etc/fstab.
249 -nonempty
251 Allow mounting over non-empty directories. FUSE by default disallows
252 this to prevent accidental shadowing of files.
253 -noprealloc
255 Disable preallocation before writing. By default, gocryptfs preallo‐
256 cates the space the next write will take using fallocate(2) in mode
257 FALLOC_FL_KEEP_SIZE. The preallocation makes sure it cannot run out of
258 space in the middle of the write, which would cause the last 4kB block
259 to be corrupt and unreadable.
260 On ext4, preallocation is fast and does not cause a noticeable perfor‐
262 mance hit. Unfortunately, on Btrfs, preallocation is very slow, espe‐
263 cially on rotational HDDs. The “-noprealloc” option gives users the
264 choice to trade robustness against out-of-space errors for a massive
265 speedup.
266 For benchmarks and more details of the issue see https://github.com/rf‐
268 jakob/gocryptfs/issues/63 .
269 -nosyslog
271 Diagnostic messages are normally redirected to syslog once gocryptfs
272 daemonizes. This option disables the redirection and messages will
273 continue be printed to stdout and stderr.
274 -nosuid
276 See -suid, -nosuid.
277 -notifypid int
279 Send USR1 to the specified process after successful mount. This is
280 used internally for daemonization.
281 -o COMMA-SEPARATED-OPTIONS
283 For compatibility with mount(1), options are also accepted as “-o COM‐
284 MA-SEPARATED-OPTIONS” at the end of the command line. For example, “-o
285 q,zerokey” is equivalent to passing “-q -zerokey”.
286 Note that you can only use options that are understood by gocryptfs
288 with “-o”. If you want to pass special flags to the kernel, you should
289 use “-ko” (kernel option). This is different in libfuse-based filesys‐
290 tems, that automatically pass any “-o” options they do not understand
291 along to the kernel.
292 Example:
294 gocryptfs /tmp/foo /tmp/bar -o q,zerokey
296 -openssl bool/“auto”
298 Use OpenSSL instead of built-in Go crypto (default “auto”). Using
299 built-in crypto is 4x slower unless your CPU has AES instructions and
300 you are using Go 1.6+. In mode “auto”, gocrypts chooses the faster op‐
301 tion.
302 -passfile string
304 Read password from the specified file. A warning will be printed if
305 there is more than one line, and only the first line will be used. A
306 single trailing newline is allowed and does not cause a warning.
307 Before gocryptfs v1.7, using -passfile was equivant to writing
309 -extpass="/bin/cat -- FILE". gocryptfs v1.7 and later directly read
310 the file without invoking cat.
311 -passwd
313 Change the password. Will ask for the old password, check if it is
314 correct, and ask for a new one.
315 This can be used together with -masterkey if you forgot the password
317 but know the master key. Note that without the old password, gocryptfs
318 cannot tell if the master key is correct and will overwrite the old one
319 without mercy. It will, however, create a backup copy of the old con‐
320 fig file as gocryptfs.conf.bak. Delete it after you have verified that
321 you can access your files with the new password.
322 -plaintextnames
324 Do not encrypt file names and symlink targets.
325 -q, -quiet
327 Quiet - silence informational messages.
328 -raw64
330 Use unpadded base64 encoding for file names. This gets rid of the
331 trailing “\=\=”. A filesystem created with this option can only be
332 mounted using gocryptfs v1.2 and higher.
333 -reverse
335 Reverse mode shows a read-only encrypted view of a plaintext directory.
336 Implies “-aessiv”.
337 -rw, -ro
339 Mount the filesystem read-write (-rw, default) or read-only (-ro). If
340 both are specified, -ro takes precedence.
341 -scryptn int
343 scrypt cost parameter expressed as scryptn=log2(N). Possible values
344 are 10 to 28, representing N=2^10 to N=2^28.
345 Setting this to a lower value speeds up mounting and reduces its memory
347 needs, but makes the password susceptible to brute-force attacks. The
348 default is 16.
349 -serialize_reads
351 The kernel usually submits multiple concurrent reads to service
352 userspace requests and kernel readahead. gocryptfs serves them concur‐
353 rently and in arbitrary order. On backing storage that performs poorly
354 for concurrent or out-of-order reads (like Amazon Cloud Drive), this
355 behavior can cause very slow read speeds.
356 The -serialize_reads option does two things: (1) reads will be submit‐
358 ted one-by-one (no concurrency) and (2) gocryptfs tries to order the
359 reads by file offset order.
360 The ordering requires gocryptfs to wait a certain time before submit‐
362 ting a read. The serialization introduces extra locking. These fac‐
363 tors will limit throughput to below 70MB/s.
364 For more details visit https://github.com/rfjakob/gocryptfs/issues/92 .
366 -sharedstorage
368 Enable work-arounds so gocryptfs works better when the backing storage
369 directory is concurrently accessed by multiple gocryptfs instances.
370 At the moment, it does two things:
372 1. Disable stat() caching so changes to the backing storage show up im‐
374 mediately.
375 2. Disable hard link tracking, as the inode numbers on the backing
377 storage are not stable when files are deleted and re-created behind
378 our back. This would otherwise produce strange “file does not ex‐
379 ist” and other errors.
380 When “-sharedstorage” is active, performance is reduced and hard links
382 cannot be created.
383 Even with this flag set, you may hit occasional problems. Running
385 gocryptfs on shared storage does not receive as much testing as the
386 usual (exclusive) use-case. Please test your workload in advance and
387 report any problems you may hit.
388 More info: https://github.com/rfjakob/gocryptfs/issues/156
390 -speed
392 Run crypto speed test. Benchmark Go’s built-in GCM against OpenSSL (if
393 available). The library that will be selected on “-openssl=auto” (the
394 default) is marked as such.
395 -suid, -nosuid
397 Enable (-suid) or disable (-nosuid) suid and sgid executables in a
398 gocryptfs mount (default: -nosuid). If both are specified, -nosuid
399 takes precedence. You need root permissions to use -suid.
400 -trace string
402 Write execution trace to file. View the trace using “go tool trace
403 FILE”.
404 -version
406 Print version and exit. The output contains three fields separated by
407 “;”. Example: “gocryptfs v1.1.1-5-g75b776c; go-fuse 6b801d3;
408 2016-11-01 go1.7.3”. Field 1 is the gocryptfs version, field 2 is the
409 version of the go-fuse library, field 3 is the compile date and the Go
410 version that was used.
411 -wpanic
413 When encountering a warning, panic and exit immediately. This is use‐
414 ful in regression testing.
415 -zerokey
417 Use all-zero dummy master key. This options is only intended for auto‐
418 mated testing as it does not provide any security.
419 --
421 Stop option parsing. Helpful when CIPHERDIR may start with a dash “-”.
422
424 In reverse mode, it is possible to exclude files from the encrypted
425 view, using the -exclude, -exclude-wildcard and -exclude-from options.
426 -exclude matches complete paths, so -exclude file.txt only excludes a
428 file named file.txt in the root of the mounted filesystem; files named
429 file.txt in subdirectories are still visible. (This option is kept for
430 compatibility with the behavior up to version 1.6.x)
431 -exclude-wildcard matches files anywhere, so -exclude-wildcard file.txt
433 excludes files named file.txt in any directory. If you want to match
434 complete paths, you can prefix the filename with a /: -exclude-wildcard
435 /file.txt excludes only file.txt in the root of the mounted filesystem.
436 If there are many exclusions, you can use -exclude-from to read exclu‐
438 sion patterns from a file. The syntax is that of -exclude-wildcard, so
439 use a leading / to match complete paths.
440 The rules for exclusion are that of gitignore (https://git-
442 scm.com/docs/gitignore#_pattern_format). In short:
443 1. A blank line matches no files, so it can serve as a separator for
445 readability.
446 2. A line starting with # serves as a comment. Put a backslash (\) in
448 front of the first hash for patterns that begin with a hash.
449 3. Trailing spaces are ignored unless they are quoted with backslash
451 (\).
452 4. An optional prefix ! negates the pattern; any matching file excluded
454 by a previous pattern will become included again. It is not possi‐
455 ble to re-include a file if a parent directory of that file is ex‐
456 cluded. Put a backslash (\) in front of the first ! for patterns
457 that begin with a literal !, for example, \!important!.txt.
458 5. If the pattern ends with a slash, it is removed for the purpose of
460 the following description, but it would only find a match with a di‐
461 rectory. In other words, foo/ will match a directory foo and paths
462 underneath it, but will not match a regular file or a symbolic link
463 foo.
464 6. If the pattern does not contain a slash /, it is treated as a shell
466 glob pattern and checked for a match against the pathname relative
467 to the root of the mounted filesystem.
468 7. Otherwise, the pattern is treated as a shell glob suitable for con‐
470 sumption by fnmatch(3) with the FNM_PATHNAME flag: wildcards in the
471 pattern will not match a / in the pathname. For example, Documenta‐
472 tion/*.html matches Documentation/git.html but not Documenta‐
473 tion/ppc/ppc.html or tools/perf/Documentation/perf.html.
474 8. A leading slash matches the beginning of the pathname. For example,
476 /*.c matches cat-file.c but not mozilla-sha1/sha1.c.
477 9. Two consecutive asterisks (**) in patterns matched against full
479 pathname may have special meaning:
480 i. A leading ** followed by a slash means match in all directo‐
482 ries. For example, **/foo matches file or directory foo any‐
483 where, the same as pattern foo. **/foo/bar matches file or
484 directory bar anywhere that is directly under directory foo.
485 ii. A trailing /** matches everything inside. For example, abc/**
487 matches all files inside directory abc, with infinite depth.
488 iii. A slash followed by two consecutive asterisks then a slash
490 matches zero or more directories. For example, a/**/b matches
491 a/b, a/x/b, a/x/y/b and so on.
492 iv. Other consecutive asterisks are considered invalid.
494
496 Create an encrypted filesystem in directory “mydir.crypt”, mount it on
497 “mydir”:
498 mkdir mydir.crypt mydir
500 gocryptfs -init mydir.crypt
501 gocryptfs mydir.crypt mydir
502 Mount an encrypted view of joe’s home directory using reverse mode:
504 mkdir /home/joe.crypt
506 gocryptfs -init -reverse /home/joe
507 gocryptfs -reverse /home/joe /home/joe.crypt
508
510 0: success
511 6: CIPHERDIR is not an empty directory (on “-init”)
512 10: MOUNTPOINT is not an empty directory
513 12: password incorrect
514 22: password is empty (on “-init”)
515 23: could not read gocryptfs.conf
516 24: could not write gocryptfs.conf (on “-init” or “-password”)
517 26: fsck found errors
518 other: please check the error message
519
521 mount(2) fuse(8) fallocate(2) encfs(1)
522
524 github.com/rfjakob.
525 Aug 2017 GOCRYPTFS(1)