From 602f62b82170f0dcb85ed6b5016df49f3aa965a1 Mon Sep 17 00:00:00 2001 From: Jakob Unterwurzacher Date: Tue, 28 Mar 2017 19:55:46 +0200 Subject: [PATCH] MANPAGE: reformat to GFM (github flavored markdown) This makes it render properly on the github webinterface. --- Documentation/MANPAGE.md | 344 +++++++++++++++++++-------------------- 1 file changed, 169 insertions(+), 175 deletions(-) diff --git a/Documentation/MANPAGE.md b/Documentation/MANPAGE.md index 1dbf4bc..6fb55ca 100644 --- a/Documentation/MANPAGE.md +++ b/Documentation/MANPAGE.md @@ -10,226 +10,220 @@ gocryptfs - mount an encrypted directory SYNOPSIS ======== -Initialize encrypted filesystem -------------------------------- - +#### Initialize encrypted filesystem gocryptfs -init [OPTIONS] CIPHERDIR -Mount ------ - +#### Mount gocryptfs [OPTIONS] CIPHERDIR MOUNTPOINT [-o COMMA-SEPARATED-OPTIONS] -Change password ---------------- - +#### Change password gocryptfs -passwd [OPTIONS] CIPHERDIR DESCRIPTION =========== -Options: +Available options are listed below. -**-aessiv** -: Use the AES-SIV encryption mode. This is slower than GCM but is - secure with deterministic nonces as used in "-reverse" mode. +#### -aessiv +Use the AES-SIV encryption mode. This is slower than GCM but is +secure with deterministic nonces as used in "-reverse" mode. -**-allow_other** -: By default, the Linux kernel prevents any other user (even root) to - access a mounted FUSE filesystem. Settings this option allows access for - other users, subject to file permission checking. Only works if - user_allow_other is set in /etc/fuse.conf. This option is equivalent to - "allow_other" plus "default_permissions" described in fuse(8). +#### -allow_other +By default, the Linux kernel prevents any other user (even root) to +access a mounted FUSE filesystem. Settings this option allows access for +other users, subject to file permission checking. Only works if +user_allow_other is set in /etc/fuse.conf. This option is equivalent to +"allow_other" plus "default_permissions" described in fuse(8). -**-config string** -: Use specified config file instead of CIPHERDIR/gocryptfs.conf +#### -config string +Use specified config file instead of CIPHERDIR/gocryptfs.conf -**-cpuprofile string** -: Write cpu profile to specified file +#### -cpuprofile string +Write cpu profile to specified file -**-ctlsock string** -: Create a control socket at the specified location. The socket can be - used to decrypt and encrypt paths inside the filesystem. When using - this option, make sure that the direcory you place the socket in is - not world-accessible. For example, `/run/user/UID/my.socket` would - be suitable. +#### -ctlsock string +Create a control socket at the specified location. The socket can be +used to decrypt and encrypt paths inside the filesystem. When using +this option, make sure that the direcory you place the socket in is +not world-accessible. For example, `/run/user/UID/my.socket` would +be suitable. -**-d, -debug** -: Enable debug output +#### -d, -debug +Enable debug output -**-extpass string** -: Use an external program (like ssh-askpass) for the password prompt. - The program should return the password on stdout, a trailing newline is - stripped by gocryptfs. Using something like "cat /mypassword.txt" allows - to mount the gocryptfs filesytem without user interaction. +#### -extpass string +Use an external program (like ssh-askpass) for the password prompt. +The program should return the password on stdout, a trailing newline is +stripped by gocryptfs. Using something like "cat /mypassword.txt" allows +to mount the gocryptfs filesytem without user interaction. -**-fg, -f** -: Stay in the foreground instead of forking away. Implies "-nosyslog". - For compatability, "-f" is also accepted, but "-fg" is preferred. +#### -fg, -f +Stay in the foreground instead of forking away. Implies "-nosyslog". +For compatability, "-f" is also accepted, but "-fg" is preferred. -**-fsname string** -: Override the filesystem name (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. +#### -fsname string +Override the filesystem name (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** -: Enable fuse library debug output +#### -fusedebug +Enable fuse library debug output -**-init** -: Initialize encrypted directory +#### -init +Initialize encrypted directory -**-ko** -: Pass additonal mount options to the kernel (comma-separated list). - FUSE filesystems are 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 to enable suid-binaries, pass "suid". - "ro" (equivalent to passing the "-ro" option) and "noexec" may also be - interesting. For a complete list see the section - `FILESYSTEM-INDEPENDENT MOUNT OPTIONS` in mount(8). +#### -ko +Pass additonal mount options to the kernel (comma-separated list). +FUSE filesystems are 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 to enable suid-binaries, pass "suid". +"ro" (equivalent to passing the "-ro" option) and "noexec" may also be +interesting. For a complete list see the section +`FILESYSTEM-INDEPENDENT MOUNT OPTIONS` in mount(8). -**-longnames** -: Store names longer than 176 bytes in extra files (default true) - This flag is useful when recovering old gocryptfs filesystems using - "-masterkey". It is ignored (stays at the default) otherwise. +#### -longnames +Store names longer than 176 bytes in extra files (default true) +This flag is useful when recovering old gocryptfs filesystems using +"-masterkey". It is ignored (stays at the default) otherwise. -**-masterkey string** -: Use a explicit master key specified on the command line. This - option can be used to mount a gocryptfs filesystem without a config file. - Note that the command line, and with it the master key, is visible to - anybody on the machine who can execute "ps -auxwww". - This is meant as a recovery option for emergencies, such as if you have - forgotten your password. - - Example master key: - 6f717d8b-6b5f8e8a-fd0aa206-778ec093-62c5669b-abd229cd-241e00cd-b4d6713d +#### -masterkey string +Use a explicit master key specified on the command line. This +option can be used to mount a gocryptfs filesystem without a config file. +Note that the command line, and with it the master key, is visible to +anybody on the machine who can execute "ps -auxwww". +This is meant as a recovery option for emergencies, such as if you have +forgotten your password. -**-memprofile string** -: Write memory profile to the specified file. This is useful when debugging - memory usage of gocryptfs. +Example master key: +6f717d8b-6b5f8e8a-fd0aa206-778ec093-62c5669b-abd229cd-241e00cd-b4d6713d -**-nonempty** -: Allow mounting over non-empty directories. FUSE by default disallows - this to prevent accidential shadowing of files. +#### -memprofile string +Write memory profile to the specified file. This is useful when debugging +memory usage of gocryptfs. -**-noprealloc** -: Disable 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 cannot - run out of space in the middle of the write, which would cause the - last 4kB block to be corrupt and unreadable. +#### -nonempty +Allow mounting over non-empty directories. FUSE by default disallows +this to prevent accidential shadowing of files. - On ext4, preallocation is fast and does not cause a - noticeable performance hit. Unfortunately, on Btrfs, preallocation - is very slow, especially on rotational HDDs. The "-noprealloc" - option gives users the choice to trade robustness against - out-of-space errors for a massive speedup. - - For benchmarks and more details of the issue see - https://github.com/rfjakob/gocryptfs/issues/63 . +#### -noprealloc +Disable 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 cannot +run out of space in the middle of the write, which would cause the +last 4kB block to be corrupt and unreadable. -**-nosyslog** -: Diagnostic messages are normally redirected to syslog once gocryptfs - daemonizes. This option disables the redirection and messages will - continue be printed to stdout and stderr. +On ext4, preallocation is fast and does not cause a +noticeable performance hit. Unfortunately, on Btrfs, preallocation +is very slow, especially on rotational HDDs. The "-noprealloc" +option gives users the choice to trade robustness against +out-of-space errors for a massive speedup. -**-notifypid int** -: Send USR1 to the specified process after successful mount. This is - used internally for daemonization. +For benchmarks and more details of the issue see +https://github.com/rfjakob/gocryptfs/issues/63 . -**-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". +#### -nosyslog +Diagnostic messages are normally redirected to syslog once gocryptfs +daemonizes. This option disables the redirection and messages will +continue be printed to stdout and stderr. -**-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. +#### -notifypid int +Send USR1 to the specified process after successful mount. This is +used internally for daemonization. -**-passfile string** -: Read password from the specified file. This is a shortcut for - specifying '-extpass="/bin/cat -- FILE"'. +#### -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". -**-passwd** -: Change the password. Will ask for the old password, check if it is - correct, and ask for a new one. - - 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. 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. +#### -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. -**-plaintextnames** -: Do not encrypt file names and symlink targets +#### -passfile string +Read password from the specified file. This is a shortcut for +specifying '-extpass="/bin/cat -- FILE"'. -**-q, -quiet** -: Quiet - silence informational messages +#### -passwd +Change the password. Will ask for the old password, check if it is +correct, and ask for a new one. -**-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. +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. 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. -**-reverse** -: Reverse mode shows a read-only encrypted view of a plaintext - directory. Implies "-aessiv". +#### -plaintextnames +Do not encrypt file names and symlink targets -**-ro** -: Mount the filesystem read-only +#### -q, -quiet +Quiet - silence informational messages -**-scryptn int** -: scrypt cost parameter expressed as scryptn=log2(N). Possible values are - 10 to 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. +#### -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. -**-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 behavoir can cause very slow read speeds. - - The `-serialize_reads` - option does two things: (1) reads will be submitted one-by-one (no - concurrency) and (2) gocryptfs tries to order the reads by file - offset order. - - The ordering requires gocryptfs 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 . +#### -reverse +Reverse mode shows a read-only encrypted view of a plaintext +directory. Implies "-aessiv". -**-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. +#### -ro +Mount the filesystem read-only -**-version** -: Print version and exit. The output contains three fields seperated by ";". - Example: "gocryptfs v1.1.1-5-g75b776c; go-fuse 6b801d3; 2016-11-01 go1.7.3". - 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. +#### -scryptn int +scrypt cost parameter expressed as scryptn=log2(N). Possible values are +10 to 28, representing N=2^10 to N=2^28. -**-wpanic** -: When encountering a warning, panic and exit immediately. This is - useful in regression testing. +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. -**-zerokey** -: Use all-zero dummy master key. This options is only intended for - automated testing as it does not provide any security. +#### -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 behavoir can cause very slow read speeds. -**--** -: Stop option parsing. Helpful when CIPHERDIR may start with a - dash "-". +The `-serialize_reads` +option does two things: (1) reads will be submitted one-by-one (no +concurrency) and (2) gocryptfs tries to order the reads by file +offset order. + +The ordering requires gocryptfs 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 . + +#### -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. + +#### -version +Print version and exit. The output contains three fields seperated by ";". +Example: "gocryptfs v1.1.1-5-g75b776c; go-fuse 6b801d3; 2016-11-01 go1.7.3". +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. + +#### -wpanic +When encountering a warning, panic and exit immediately. This is +useful in regression testing. + +#### -zerokey +Use all-zero dummy master key. This options is only intended for +automated testing as it does not provide any security. + +#### -- +Stop option parsing. Helpful when CIPHERDIR may start with a +dash "-". EXAMPLES ========