GOCRYPTFS(1)

📦
version 2.6.1 · 12 versions
, in fedora 43, fedora 44

💖 GOCRYPTFS 💖 — the gocryptfs manual, bestie edition

okay so. bestie. you're holding the manual page for gocryptfs, and I need you to know this is genuinely one of my fave little tools, so let's get into it. 🫶

🌸 NAME 🌸

gocryptfs — create or mount an encrypted filesystem

✨ SYNOPSIS ✨

like, the vibes are: it depends what you're doing. pick your adventure 💅

🎀 Initialize new encrypted filesystem

gocryptfs -init [OPTIONS] CIPHERDIR

🦋 Mount

gocryptfs [OPTIONS] CIPHERDIR MOUNTPOINT [-o COMMA-SEPARATED-OPTIONS]

🌈 Unmount

fusermount -u MOUNTPOINT

💜 Change password

gocryptfs -passwd [OPTIONS] CIPHERDIR

⭐ Check consistency

gocryptfs -fsck [OPTIONS] CIPHERDIR

🍓 Show filesystem information

gocryptfs -info [OPTIONS] CIPHERDIR

👑 DESCRIPTION 👑

so gocryptfs is an encrypted overlay filesystem written in Go. The way it works is: your encrypted files live in CIPHERDIR, and then you can get a plain-text view of them by mounting the filesystem at MOUNTPOINT. it's giving ✨magic✨ but it's literally just filesystems.

gocryptfs was inspired by encfs(1) and it's lowkey on a mission to fix the security issues encfs had while still being fast. we love a redemption arc. 🙈

🔥 ACTION FLAGS 🔥

okay bestie, important: unless you pass one of these action flags, the default action is to mount a filesystem (peep the SYNOPSIS if you missed it). so no flag = mounting. periodt.

💀 -fsck

Check CIPHERDIR for consistency. And if corruption is found?? the exit code is 26. no cap. 😭

💅 -h, -help

Print a short help text that shows the more-often used options. the little quick-look version.

🦋 -hh

Long help text, shows all available options. every single one. she's thorough.

🎀 -info

Pretty-print the contents of the config file in CIPHERDIR for human consumption, stripping out sensitive data. so you can look at it without exposing anything spicy. 🔒

Example:

$ gocryptfs -info my_cipherdir
Creator:      gocryptfs v2.0-beta2
FeatureFlags: GCMIV128 HKDF DirIV EMENames LongNames Raw64
EncryptedKey: 64B
ScryptObject: Salt=32B N=65536 R=8 P=1 KeyLen=32

🌸 -init

Initialize encrypted directory. the very first step, the origin story. ✨

💜 -passwd

Change the password. She'll ask for the old password, check if it is correct, and ask for a new one. very polite about it.

This can be used together with -masterkey if you forgot the password but know the master key. Note that without the old password, gocryptfs cannot tell if the master key is correct and will overwrite the old one without mercy. 😭 literally no mercy. It will, however, create a backup copy of the old config file as gocryptfs.conf.bak. Delete it after you have verified that you can access your files with the new password. please don't forget that part bestie.

⭐ -speed

Run crypto speed test. Benchmark Go's built-in GCM against OpenSSL (if available). The library that will be selected on -openssl=auto (the default) is marked as such. it's a little race and the winner gets a crown 👑

🌈 -version

Print version and exit. The output contains three fields separated by ;. Example: gocryptfs v1.1.1-5-g75b776c; go-fuse 6b801d3; 2016-11-01 go1.7.3. So field 1 is the gocryptfs version, field 2 is the version of the go-fuse library, field 3 is the compile date and the Go version that was used. three little fields, all separated by ;. iykyk.

💖 INIT OPTIONS 💖

Available options for -init are listed below. Usually, you don't need any. Defaults are fine. fr fr, the defaults ate.

👑 -aessiv

Use the AES-SIV encryption mode. This is slower than AES-GCM but is secure with deterministic nonces as used in -reverse mode.

Run gocryptfs -speed to find out if and how much slower. (spoiler: she'll tell you the numbers, no guessing here)

🍓 -deterministic-names

Disable file name randomisation and creation of gocryptfs.diriv files. This can prevent sync conflicts when synchronising files, but leaks information about identical file names across directories ("Identical names leak" in https://nuetzlich.net/gocryptfs/comparison/#file-names ). so like, tradeoffs, bestie.

The resulting gocryptfs.conf has "DirIV" missing from "FeatureFlags".

🙈 -devrandom

Obsolete and ignored on gocryptfs v2.2 and later. she's retired, she's living her best life, she does nothing now.

See https://github.com/rfjakob/gocryptfs/commit/f3c777d5eaa682d878c638192311e52f9c204294 and https://github.com/rfjakob/gocryptfs/issues/596 for background info.

🧚 -hkdf

Use HKDF to derive separate keys for content and name encryption from the master key. Default true. slay.

💅 -longnamemax

       integer value, allowed range 62...255

Hash file names that (in encrypted form) exceed this length. The default is 255, which aligns with the usual name length limit on Linux and provides best performance.

However, online storage may impose lower limits on file name and/or path length. In this case, setting -longnamemax to a lower value can be helpful.

The lower the value, the more extra .name files must be created, which slows down directory listings. so like, more files, more waiting. 🐌

Values below 62 are not allowed as then the hashed name would be longer than the original name. that would be giving nonsense.

Example:

-longnamemax 100

🌸 -plaintextnames

Do not encrypt file names and symlink targets. just... out there. raw. 😭

⭐ -raw64

Use unpadded base64 encoding for file names. This gets rid of the trailing "\=\=". A filesystem created with this option can only be mounted using gocryptfs v1.2 and higher. Default true.

🦋 -reverse

Reverse mode shows a read-only encrypted view of a plaintext directory. Implies -aessiv.

If you want to mount the encrypted view using -masterkey, you must specify -aessiv. important!! don't skip that part!!

💜 -xchacha

Use XChaCha20-Poly1305 file content encryption. This should be much faster than AES-GCM on CPUs that lack AES acceleration. so if your CPU isn't built different for AES, this is your girl. 🔥

Run gocryptfs -speed to find out if and how much faster.

💅 MOUNT OPTIONS 💅

okay bestie so these are all the options you can throw at gocryptfs when you're mounting. and like… you probably don't need any of them?? the defaults are fine, the defaults are slaying, leave them alone. ✨ but if you're curious, here's the whole menu. 🎀

  • -acl — turns on ACL enforcement. so like, if you wanna use ACLs, you literally have to flip this on. no option, no ACLs, that's the deal. 💅
  • -allow_other — by default the Linux kernel is super gatekeepy and won't let any other user (yes, even root 😭) touch a mounted FUSE filesystem. setting this option lets other users in, subject to normal file permission checking. it only works if user_allow_other is set in /etc/fuse.conf. this option is equivalent to allow_other plus default_permissions as described in fuse(8).
  • -badname string — so when gocryptfs runs into a "bad" file name (can't decrypt it, or it decrypts into garbage 🗑️), it logs a warning and hides that file from the plaintext view. with -badname you get to pick which "bad" names still show up in the plaintext view instead of being hidden. bad files get GOCRYPTFS_BAD_NAME appended to their name. it's a glob pattern, and you can pass it multiple times for multiple patterns. examples, bestie:

Dropbox sync conflicts:

-badname '*conflicted copy*'

Syncthing sync conflicts:

-badname '*.sync-conflict*'

Show all invalid filenames:

-badname '*'
  • -context string — sets the SELinux context. see mount(8) for the deets. this option was added for compatibility with xfstests, which sets it via -o context="system_u:object_r:root_t:s0". ⚠️ only works when you mount as root — otherwise you get this lil error from fusermount3:
fusermount3: unknown option 'context="system_u:object_r:root_t:s0"'
  • -ctlsock string — makes a control socket at whatever location you point it at. the socket can be used to decrypt and encrypt paths inside the filesystem. 🔐 when you use this, make sure the directory you drop the socket in is not world-accessible, fr fr. like /run/user/UID/my.socket would be a good spot.
  • -dev, -nodev — enable (-dev) or disable (-nodev) device files in a gocryptfs mount (default: -nodev). if you pass both, -nodev wins, periodt. you need root permissions to use -dev.
  • -e PATH, -exclude PATH — reverse mode only, bestie: excludes a relative plaintext path from the encrypted view, matching only from the root of the mounted filesystem. can be passed multiple times. example that excludes the directories "Music" and "Movies" from the root directory:
gocryptfs -reverse -exclude Music -exclude Movies /home/user /mnt/user.encrypted

see also -exclude-wildcard, -exclude-from, and the EXCLUDING FILES section. 🦋

  • -ew GITIGNORE-PATTERN, -exclude-wildcard GITIGNORE-PATTERN — reverse mode only again: excludes paths from the encrypted view using gitignore(5) syntax, wildcards supported. pass it multiple times for multiple patterns. example to exclude all .mp3 files in any directory:
gocryptfs -reverse -exclude-wildcard '*.mp3' /home/user /mnt/user.encrypted

example to to exclude everything but the directory important in the root dir:

gocryptfs -reverse -exclude-wildcard '*' -exclude-wildcard '!/important' /home/user /mnt/user.encrypted

see also -exclude-from and the EXCLUDING FILES section.

  • -exclude-from FILE — reverse mode only: reads gitignore patterns from a file. can be passed multiple times. example:
gocryptfs -reverse -exclude-from ~/crypt-exclusions /home/user /mnt/user.encrypted

see also -exclude, -exclude-wildcard, and the EXCLUDING FILES section.

  • -exec, -noexec — enable (-exec) or disable (-noexec) executables in a gocryptfs mount (default: -exec). if both are specified, -noexec takes precedence.
  • -fg, -f — stay in the foreground instead of forking away. for compatibility, -f is also accepted, but -fg is the preferred one (it's giving main character 💅). unless -notifypid is also passed, the logs go to stdout and stderr instead of syslog.
  • -force_owner string — if you give it a string shaped like uid:gid (where both uid and gid get substituted with positive integers), it presents all files as owned by that uid and gid, no matter what their actual ownership is. implies allow_other. tbh this is rarely what you want: you should usually run gocryptfs as the account that owns the backing-store files, which should usually be the same account that's meant to access the decrypted content. one case where it can be useful is when your content lives on a filesystem that doesn't properly support UNIX ownership and permissions. 🫶
  • -forcedecode — obsolete and ignored on gocryptfs v2.2 and later. it's a fossil, bestie. 💀 see https://github.com/rfjakob/gocryptfs/commit/d023cd6c95fcbc6b5056ba1f425d2ac3df4abc5a for what it was and why it got dropped.
  • -fsname string — overrides the filesystem name (that's the first column in df -T). can also be passed as -o fsname= and is equivalent to libfuse's option of the same name. by default, CIPHERDIR is used.
  • -fusedebug — enables fuse library debug output. 🐛
  • -i duration, -idle duration — forward mode only: automatically unmounts the filesystem if it's been idle for the specified duration. durations can be written like 500s or 2h45m. 0 (the default) means stay mounted indefinitely. when a process has open files or its working directory in the mount, that keeps it not-idle indefinitely. no nap time for you. 😴
  • -kernel_cache — enables the kernel_cache option of the FUSE filesystem. see fuse(8) for details.
  • -ko — passes additional mount options straight to the kernel (comma-separated list). FUSE filesystems get mounted with nodev,nosuid by default. if gocryptfs runs as root, you can enable device files by passing the opposite mount option, dev, and if you want suid-binaries, pass suid. ro (equivalent to passing the -ro option) and noexec may also be interesting. for the complete list, see the section FILESYSTEM-INDEPENDENT MOUNT OPTIONS in mount(8). on MacOS, local enables volume-based trash if you have a .Trashes folder in the root of your volume (it might need to be manually created) — but heads up, local is marked as "experimental" in osxfuse. noapplexattr and noappledouble may also be interesting. 📝 note that unlike -o, -ko is a regular option and must be passed BEFORE the directories. example:
gocryptfs -ko noexec /tmp/foo /tmp/bar
  • -longnames — stores names longer than 175 bytes in extra files (default true). this flag is only useful when recovering very old gocryptfs filesystems (gocryptfs v0.8 and earlier) using -masterkey. otherwise it's ignored and stays at the default. 🧚
  • -nodev — see -dev, -nodev.
  • -noexec — see -exec, -noexec.
  • -nofail — having the nofail option in /etc/fstab tells systemd to keep booting normally even if the mount fails (see man systemd.fstab). the option is ignored by gocryptfs itself and has no effect outside /etc/fstab.
  • -nonempty — allows mounting over non-empty directories. FUSE by default says no to this, to prevent accidentally shadowing files. 🙈
  • -noprealloc — disables preallocation before writing. by default, gocryptfs preallocates the space the next write will take using fallocate(2) in mode FALLOC_FL_KEEP_SIZE. the preallocation makes sure it can't run out of space in the middle of the write, which would cause the last 4kB block to be corrupt and unreadable. 😭 on ext4, preallocation is fast and causes no noticeable performance hit. unfortunately on Btrfs, preallocation is very slow, especially on rotational HDDs. the -noprealloc option lets you trade robustness against out-of-space errors for a massive speedup. for benchmarks and more details on the whole situation, see https://github.com/rfjakob/gocryptfs/issues/63 .
  • -nosuid — see -suid, -nosuid.
  • -nosyslog — diagnostic messages normally get redirected to syslog once gocryptfs daemonizes. this option disables that redirection, so messages keep printing to stdout and stderr. 📢
  • -notifypid int — sends USR1 to the specified process after a successful mount. this is used internally for daemonization.
  • -one-file-system — don't cross filesystem boundaries (just like rsync's --one-file-system). mountpoints will appear as empty directories. only applicable to reverse mode. ⚠️ limitation: mounted single files (yes, that's possible) are NOT hidden.
  • -rw, -ro — mount the filesystem read-write (-rw, the default) or read-only (-ro). if both are specified, -ro takes precedence.
  • -reverse — see the -reverse section in INIT OPTIONS. you need to specify the -reverse option both at -init and at mount. ✌️
  • -serialize_reads — the kernel usually submits multiple concurrent reads to service userspace requests and kernel readahead. gocryptfs serves them concurrently and in arbitrary order. on backing storage that performs poorly for concurrent or out-of-order reads (like Amazon Cloud Drive), this behavior can cause very slow read speeds. the -serialize_reads option does two things: (1) reads get submitted one-by-one (no concurrency) and (2) gocryptfs tries to order the reads by file offset order. the ordering means gocryptfs has to wait a certain time before submitting a read. the serialization introduces extra locking. these factors will limit throughput to below 70MB/s. for more details visit https://github.com/rfjakob/gocryptfs/issues/92 .
  • -sharedstorage — enables work-arounds so gocryptfs behaves better when the backing storage directory is concurrently accessed by multiple gocryptfs instances. at the moment, it does two things:
    1. Disables stat() caching so changes to the backing storage show up immediately.
    2. Disables hard link tracking, because the inode numbers on the backing storage aren't stable when files are deleted and re-created behind our back. that would otherwise produce strange "file does not exist" and other errors.

when -sharedstorage is active, performance is reduced and hard links cannot be created. and even with this flag set, you may hit occasional problems — running gocryptfs on shared storage doesn't receive as much testing as the usual (exclusive) use-case. please test your workload in advance and report any problems you hit. 🫶 more info: https://github.com/rfjakob/gocryptfs/issues/156

  • -suid, -nosuid — enable (-suid) or disable (-nosuid) suid and sgid executables in a gocryptfs mount (default: -nosuid). if both are specified, -nosuid takes precedence. you need root permissions to use -suid.
  • -zerokey — use an all-zero dummy master key. 🚨 this option is only intended for automated testing, because it does not provide any security. literally none. do not use it for real stuff, bestie.

✨ COMMON OPTIONS ✨

Okay bestie, these are the options that show up in more than one action — the multi-hyphenate icons of the flag world 💅. Each one tells you exactly where it's applicable, so you never have to guess. And again, fr fr: usually you don't need any of them. They're here if you need them, not because you do.

  • -config string — Use the specified config file instead of CIPHERDIR/gocryptfs.conf.

Applies to: all actions that use a config file: mount, -fsck, -passwd, -info, -init.

  • -cpuprofile string — Write the CPU profile to the specified file.

Applies to: all actions.

  • -d, -debug — Turn on debug output. Spicy extra detail mode.

Applies to: all actions.

  • -extpass CMD [-extpass ARG1 ...] — Use an external program (like ssh-askpass) for the password prompt instead of typing it yourself. The program should return the password on stdout, and gocryptfs strips a trailing newline for you 🫶. If all you want is to read from a password file, see -passfile instead.

When -extpass is specified once, the string argument gets split on spaces. For example, -extpass "md5sum my password.txt" will be executed as "md5sum" "my" "password.txt" — which is NOT what you want 😭.

Specify -extpass twice or more to use the string arguments as-is. For example, you DO want to call md5sum like this: -extpass "md5sum" -extpass "my password.txt".

If you want to prevent splitting on spaces but don't want to pass arguments to your program, use "--", which is accepted by most programs: -extpass "my program" -extpass "--".

Applies to: all actions that ask for a password.

BUG: In -extpass -X, the -X will be interpreted as --X. Please use -extpass=-X to prevent that. See Dash duplication in the BUGS section for details.
  • -fido2 DEVICE_PATH — Use a FIDO2 token to initialize and unlock the filesystem. Use fido2-token -L to obtain the FIDO2 token device path. For linux, the fido2-tools package is needed.

Applies to: all actions that ask for a password.

  • -fido2-assert-option OPTION — Options passed to fido2-assert with the -t option. This option may be specified multiple times, and each time it will add two arguements -t OPTION to fido2-assert. See man fido2-assert to check supported options.

Examples:

Creating a filesystem with no pin verification:

gocryptfs -init -fido2 DEVICE_PATH -fido2-assert-option pin=false CIPHERDIR

Creating a filesystem with both user verification and pin verification:

gocryptfs -init -fido2 DEVICE_PATH -fido2-assert-option uv=true -fido2-assert-option pin=true CIPHERDIR

Creating a filesystem with both user presence and user verification:

gocryptfs -init -fido2 DEVICE_PATH -fido2-assert-option up=true -fido2-assert-option uv=true CIPHERDIR
  • -masterkey string — Use an explicit master key specified right on the command line, or — if the special value "stdin" is used — read the masterkey from stdin, instead of reading the config file and asking for the decryption password. Emergency vibes only, bestie.

Note that the command line, and with it the master key, is visible to anybody on the machine who can execute "ps -auxwww". Use "-masterkey=stdin" to avoid that risk. 👀

The masterkey option is meant as a recovery option for emergencies, such as if you have forgotten the password or lost the config file.

Even if a config file exists, it will not be used. All non-standard settings have to be passed on the command line: -aessiv when you mount a filesystem that was created using reverse mode, or -plaintextnames for a filesystem that was created with that option.

Example 1: Mount a filesystem that was created using default options:

gocryptfs -masterkey=6f717d8b-6b5f8e8a-fd0aa206-778ec093-62c5669b-abd229cd-241e00cd-b4d6713d cipher mnt
gocryptfs -masterkey=stdin cipher mnt

Example 2: Mount a gocryptfs -reverse filesystem (note that you must specify -aessiv):

gocryptfs -masterkey=stdin -aessiv cipher mnt

Applies to: all actions that ask for a password.

  • -memprofile string — Write the memory profile to the specified file. This is useful when debugging memory usage of gocryptfs. 🔍

Applies to: all actions.

  • -o COMMA-SEPARATED-OPTIONS — For compatibility with mount(1), options are also accepted as "-o COMMA-SEPARATED-OPTIONS" at the end of the command line. For example, "-o q,zerokey" is equivalent to passing "-q -zerokey".

Note that you can only use options that are understood by gocryptfs with "-o". If you want to pass special flags to the kernel, you should use "-ko" (kernel option). This is different in libfuse-based filesystems, that automatically pass any "-o" options they do not understand along to the kernel.

Example:

gocryptfs /tmp/foo /tmp/bar -o q,zerokey

Applies to: all actions.

  • -openssl bool/"auto" — Use OpenSSL instead of built-in Go crypto (default "auto"). Using built-in crypto is 4x slower unless your CPU has AES instructions and you are using Go 1.6+. In mode "auto", gocrypts chooses the faster option. ⚡

Applies to: all actions.

  • -passfile FILE [-passfile FILE2 ...] — Read the password from the specified plain text file. The file should contain exactly one line (do not use binary files! 🚫). A warning will be printed if there is more than one line, and only the first line will be used. A single trailing newline is allowed and does not cause a warning.

Pass this option multiple times to read the first line from multiple files. They are concatenated for the effective password.

Example:

echo hello > hello.txt
echo world > world.txt
gocryptfs -passfile hello.txt -passfile world.txt

The effective password will be "helloworld".

Applies to: all actions that ask for a password.

  • -q, -quiet — Quiet — silence informational messages. 🤫

Applies to: all actions.

  • -scryptn int — gocryptfs uses scrypt for hashing the password when mounting, which protects from brute-force attacks.

-scryptn controls the scrypt cost parameter "N" expressed as scryptn=log2(N). Possible values are -scryptn=10 to -scryptn=28, representing N=2^10 to N=2^28.

Setting this to a lower value speeds up mounting and reduces its memory needs, but makes the password susceptible to brute-force attacks. The default is 16.

The memory usage for scrypt during mounting is as follows:

scryptn     Memory Usage
=======     ============
10          1   MiB
11          2
12          4
13          8
14          16
15          32
16          64
17          128
18          256
19          512
20          1   GiB
21          2
22          4
23          8
24          16
25          32
26          64
27          128
28          256

Applies to: -init, -passwd

See also: the benchmarks in the gocryptfs source code in internal/configfile.

  • -trace string — Write an execution trace to file. View the trace using "go tool trace FILE".

Applies to: all actions.

  • -wpanic — When encountering a warning, panic and exit immediately. This is useful in regression testing. 💀

Applies to: all actions.

  • -- — Stop option parsing. Helpful when CIPHERDIR may start with a dash "-". Little escape hatch, we love her.

Applies to: all actions.

🌸 EXCLUDING FILES 🌸

In reverse mode, it is possible to exclude files from the encrypted view, using the -exclude, -exclude-wildcard and -exclude-from options.

-exclude matches complete paths, so -exclude file.txt only excludes a file named file.txt in the root of the mounted filesystem; files named file.txt in subdirectories are still visible. Wildcards are NOT supported. This option is kept for compatibility with the behavior up to version 1.6.x. New users should use -exclude-wildcard instead. 👑

-exclude-wildcard uses gitignore syntax and matches files anywhere, so -exclude-wildcard file.txt excludes files named file.txt in any directory. If you want to match complete paths, you can prefix the filename with a /: -exclude-wildcard /file.txt excludes only file.txt in the root of the mounted filesystem.

If there are many exclusions, you can use -exclude-from to read gitignore patterns from a file. As with -exclude-wildcard, use a leading / to match complete paths.

The rules for exclusion are that of gitignore. In short:

  1. A blank line matches no files, so it can serve as a separator for readability.
  2. A line starting with # serves as a comment. Put a backslash (\) in front of the first hash for patterns that begin with a hash.
  3. Trailing spaces are ignored unless they are quoted with backslash (\).
  4. An optional prefix ! negates the pattern; any matching file excluded by a previous pattern will become included again. It is not possible to re-include a file if a parent directory of that file is excluded. Put a backslash (\) in front of the first ! for patterns that begin with a literal !, for example, \!important!.txt.
  5. If the pattern ends with a slash, it is removed for the purpose of the following description, but it would only find a match with a directory. In other words, foo/ will match a directory foo and paths underneath it, but will not match a regular file or a symbolic link foo.
  6. If the pattern does not contain a slash /, it is treated as a shell glob pattern and checked for a match against the pathname relative to the root of the mounted filesystem.
  7. Otherwise, the pattern is treated as a shell glob suitable for consumption by fnmatch(3) with the FNM_PATHNAME flag: wildcards in the pattern will not match a / in the pathname. For example, Documentation/*.html matches Documentation/git.html but not Documentation/ppc/ppc.html or tools/perf/Documentation/perf.html.
  8. A leading slash matches the beginning of the pathname. For example, /*.c matches cat-file.c but not mozilla-sha1/sha1.c.
  9. Two consecutive asterisks (**) in patterns matched against full pathname may have special meaning:

i. A leading ** followed by a slash means match in all directories. For example, **/foo matches file or directory foo anywhere, the same as pattern foo. **/foo/bar matches file or directory bar anywhere that is directly under directory foo.

ii. A trailing /** matches everything inside. For example, abc/** matches all files inside directory abc, with infinite depth.

iii. A slash followed by two consecutive asterisks then a slash matches zero or more directories. For example, a/**/b matches a/b, a/x/b, a/x/y/b and so on.

iv. Other consecutive asterisks are considered invalid. 🚩

🌈 EXAMPLES 🌈

🎀 Init

Okay bestie, first vibe: make an encrypted filesystem in the directory mydir.crypt, then mount it onto mydir. Three lines, that's the whole ritual:

mkdir mydir.crypt mydir
gocryptfs -init mydir.crypt
gocryptfs mydir.crypt mydir

🦋 Mount

Now the reverse-mode glow-up 💅 — mount an encrypted view of joe's home directory:

mkdir /home/joe.crypt
gocryptfs -init -reverse /home/joe
gocryptfs -reverse /home/joe /home/joe.crypt

reverse mode really said "your plaintext stays home, the ciphertext goes out" and honestly? iconic.

⭐ fstab

Drop this line into /etc/fstab and it'll mount /tmp/cipher onto /tmp/plain at boot, using the password sitting in /tmp/passfile:

/tmp/cipher /tmp/plain fuse./usr/local/bin/gocryptfs nofail,allow_other,passfile=/tmp/password 0 0

Test the line without the whole reboot situation by running sudo mount -av. And adjust that gocryptfs path according to whatever which gocryptfs spits out — ask the terminal, it knows.

🚨 do use the nofail option, no cap. Otherwise if the gocryptfs mount fails you get an unbootable system and that is not the main character energy you want. See the -nofail option for the deets.

🌸 ENVIRONMENT VARIABLES 🌸

💜 NO_COLOR

If NO_COLOR is set — literally regardless of its value — colored output gets switched off. See https://no-color.org/ for the whole story.

✨ EXIT CODES ✨

Here's the tea on what gocryptfs hands back to you when it's done:

  • 0: success 🎉
  • 6: CIPHERDIR is not an empty directory (on -init)
  • 10: MOUNTPOINT is not an empty directory
  • 12: password incorrect 😭
  • 22: password is empty (on -init)
  • 23: could not read gocryptfs.conf
  • 24: could not write gocryptfs.conf (on -init or -password)
  • 26: fsck found errors
  • other: please check the error message

See also: https://github.com/rfjakob/gocryptfs/blob/master/internal/exitcodes/exitcodes.go

💀 BUGS 💀

🙈 Dash duplication

gocryptfs v2.1 switched to the pflag library for command-line parsing so it could support flags and positional arguments in any order. To stay compatible with single-dash long options like -extpass, an ugly hack got bolted on: the command line is preprocessed, and every single-dash option gets converted to double-dash.

Unfortunately that means in

gocryptfs -extpass myapp -extpass -X

gocryptfs transforms that -X into --X, and then it'll call myapp --X as the extpass program. 😬 not the plot twist anybody asked for.

Please use

gocryptfs -extpass myapp -extpass=-X

to work around this bug. 🫶

👑 SEE ALSO 👑

mount(2) fuse(8) fallocate(2) encfs(1) gitignore(5)

🧚 AUTHORS 🧚

github.com/rfjakob.

and that's the whole page, bestie — written by github.com/rfjakob, dating all the way back to Aug 2017, living in the GOCRYPTFS(1) section of your manual. go forth and encrypt responsibly 💖✨

📦 where this page comes from