1GOCRYPTFS(1)                                                      GOCRYPTFS(1)
2
3
4

NAME

6       gocryptfs - create or mount an encrypted filesystem
7

SYNOPSIS

9   Initialize new encrypted filesystem
10       gocryptfs -init [OPTIONS] CIPHERDIR
11
12   Mount
13       gocryptfs [OPTIONS] CIPHERDIR MOUNTPOINT [-o COMMA-SEPARATED-OPTIONS]
14
15   Unmount
16       fusermount -u MOUNTPOINT
17
18   Change password
19       gocryptfs -passwd [OPTIONS] CIPHERDIR
20
21   Check consistency
22       gocryptfs -fsck [OPTIONS] CIPHERDIR
23

DESCRIPTION

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
29       gocryptfs  was inspired by encfs(1) and strives to fix its security is‐
30       sues while providing good performance.
31

OPTIONS

33       Available options are listed below.  Usually, you don’t need any.   De‐
34       faults are fine.
35
36   -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
40   -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
47   -config string
48       Use specified config file instead of CIPHERDIR/gocryptfs.conf.
49
50   -cpuprofile string
51       Write cpu profile to specified file.
52
53   -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
60   -d, -debug
61       Enable debug output.
62
63   -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
68   -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
75   -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
80              gocryptfs -reverse -exclude Music -exclude Movies /home/user /mnt/user.encrypted
81
82       See also -exclude-wildcard, -exclude-from and the EXCLUDING FILES  sec‐
83       tion.
84
85   -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
90              gocryptfs -reverse -exclude-wildcard '*~' /home/user /mnt/user.encrypted
91
92       See also -exclude, -exclude-from and the EXCLUDING FILES section.
93
94   -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
98              gocryptfs -reverse -exclude-from ~/crypt-exclusions /home/user /mnt/user.encrypted
99
100       See also -exclude, -exclude-wildcard and the EXCLUDING FILES section.
101
102   -exec, -noexec
103       Enable (-exec) or disable (-noexec) executables in  a  gocryptfs  mount
104       (default: -exec).  If both are specified, -noexec takes precedence.
105
106   -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
112       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
116       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
120       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
124   -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
128   -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
134       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
141   -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
149       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
152       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
156       Setting this option forces the filesystem to read-only and noexec.
157
158   -fsck
159       Check CIPHERDIR for consistency.  If corruption is found, the exit code
160       is 26.
161
162   -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
167   -fusedebug
168       Enable fuse library debug output.
169
170   -h, -help
171       Print a short help text that shows the more-often used options.
172
173   -hh
174       Long help text, shows all available options.
175
176   -hkdf
177       Use HKDF to derive separate keys for content and name  encryption  from
178       the master key.
179
180   -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
185   -info
186       Pretty-print  the  contents  of  the config file for human consumption,
187       stripping out sensitive data.
188
189   -init
190       Initialize encrypted directory.
191
192   -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
202       Note that unlike “-o”, “-ko” is a regular option and must be passed BE‐
203       FORE the directories.  Example:
204
205              gocryptfs -ko noexec /tmp/foo /tmp/bar
206
207   -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
212   -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
220       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
223       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
228       Examples:
229
230              -masterkey=6f717d8b-6b5f8e8a-fd0aa206-778ec093-62c5669b-abd229cd-241e00cd-b4d6713d
231              -masterkey=stdin
232
233   -memprofile string
234       Write memory profile to the specified file.  This is useful when debug‐
235       ging memory usage of gocryptfs.
236
237   -nodev
238       See -dev, -nodev.
239
240   -noexec
241       See -exec, -noexec.
242
243   -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
247       The  option  is  ignored  by gocryptfs itself and has no effect outside
248       /etc/fstab.
249
250   -nonempty
251       Allow mounting over non-empty directories.  FUSE by  default  disallows
252       this to prevent accidental shadowing of files.
253
254   -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
261       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
267       For benchmarks and more details of the issue see https://github.com/rf
268       jakob/gocryptfs/issues/63 .
269
270   -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
275   -nosuid
276       See -suid, -nosuid.
277
278   -notifypid int
279       Send USR1 to the specified process after  successful  mount.   This  is
280       used internally for daemonization.
281
282   -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
287       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
293       Example:
294
295              gocryptfs /tmp/foo /tmp/bar -o q,zerokey
296
297   -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
303   -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
308       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
312   -passwd
313       Change the password.  Will ask for the old password,  check  if  it  is
314       correct, and ask for a new one.
315
316       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
323   -plaintextnames
324       Do not encrypt file names and symlink targets.
325
326   -q, -quiet
327       Quiet - silence informational messages.
328
329   -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
334   -reverse
335       Reverse mode shows a read-only encrypted view of a plaintext directory.
336       Implies “-aessiv”.
337
338   -rw, -ro
339       Mount  the filesystem read-write (-rw, default) or read-only (-ro).  If
340       both are specified, -ro takes precedence.
341
342   -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
346       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
350   -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
357       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
361       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
365       For more details visit https://github.com/rfjakob/gocryptfs/issues/92 .
366
367   -sharedstorage
368       Enable  work-arounds so gocryptfs works better when the backing storage
369       directory is concurrently accessed by multiple gocryptfs instances.
370
371       At the moment, it does two things:
372
373       1. Disable stat() caching so changes to the backing storage show up im‐
374          mediately.
375
376       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
381       When “-sharedstorage” is active, performance is reduced and hard  links
382       cannot be created.
383
384       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
389       More info: https://github.com/rfjakob/gocryptfs/issues/156
390
391   -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
396   -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
401   -trace string
402       Write execution trace to file.  View the trace  using  “go  tool  trace
403       FILE”.
404
405   -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
412   -wpanic
413       When  encountering a warning, panic and exit immediately.  This is use‐
414       ful in regression testing.
415
416   -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
420   --
421       Stop option parsing.  Helpful when CIPHERDIR may start with a dash “-”.
422

EXCLUDING FILES

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
427       -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
432       -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
437       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
441       The  rules  for  exclusion  are   that   of   gitignore   (https://git-
442       scm.com/docs/gitignore#_pattern_format).  In short:
443
444       1. A  blank  line  matches no files, so it can serve as a separator for
445          readability.
446
447       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
450       3. Trailing  spaces  are  ignored unless they are quoted with backslash
451          (\).
452
453       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
459       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
465       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
469       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
475       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
478       9. Two  consecutive  asterisks  (**)  in  patterns matched against full
479          pathname may have special meaning:
480
481             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
486            ii. A trailing /** matches everything inside.  For example, abc/**
487                matches all files inside directory abc, with infinite depth.
488
489           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
493            iv. Other consecutive asterisks are considered invalid.
494

EXAMPLES

496       Create an encrypted filesystem in directory “mydir.crypt”, mount it  on
497       “mydir”:
498
499              mkdir mydir.crypt mydir
500              gocryptfs -init mydir.crypt
501              gocryptfs mydir.crypt mydir
502
503       Mount an encrypted view of joe’s home directory using reverse mode:
504
505              mkdir /home/joe.crypt
506              gocryptfs -init -reverse /home/joe
507              gocryptfs -reverse /home/joe /home/joe.crypt
508

EXIT CODES

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

SEE ALSO

521       mount(2) fuse(8) fallocate(2) encfs(1)
522

AUTHORS

524       github.com/rfjakob.
525
526
527
528                                   Aug 2017                       GOCRYPTFS(1)
Impressum