diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/build.md | 6 | ||||
| -rw-r--r-- | doc/development.md | 14 | ||||
| -rw-r--r-- | doc/interimap.1.md | 29 | ||||
| -rw-r--r-- | doc/pullimap.1.md | 28 |
4 files changed, 45 insertions, 32 deletions
diff --git a/doc/build.md b/doc/build.md index d704f71..4a4f80d 100644 --- a/doc/build.md +++ b/doc/build.md @@ -66,9 +66,9 @@ the `CSS` environment variable (the value of which defaults to For instance, use - $ CSS="https://guilhem.org/static/css/bootstrap.min.css" \ - HTML_ROOTDIR="$XDG_RUNTIME_DIR/interimap" \ - make html + $ env CSS="https://guilhem.org/static/css/bootstrap.min.css" \ + HTML_ROOTDIR="$XDG_RUNTIME_DIR/interimap" \ + make html to generate the HTML documentation under directory `$XDG_RUNTIME_DIR/interimap` (which needs to exist) using a remote CSS file. diff --git a/doc/development.md b/doc/development.md index 708712f..f4578b9 100644 --- a/doc/development.md +++ b/doc/development.md @@ -72,7 +72,7 @@ pre-authenticated [IMAP4rev1] in the test environment for username `testuser`, list mailboxes, and exit, run: $ env -i PATH="/usr/bin:/bin" USER="testuser" \ - doveadm -c "$BASEDIR/dovecot.conf" exec imap + doveadm -c "$BASEDIR/dovecot.conf" exec imap S: * PREAUTH [CAPABILITY IMAP4rev1 …] Logged in as testuser C: a LIST "" "*" S: * LIST (\HasNoChildren) "." INBOX @@ -88,10 +88,10 @@ the latter to create a mailbox `foo`, add a sample message to it, and finally mark it as `\Seen`. $ env -i PATH="/usr/bin:/bin" USER="testuser" \ - doveadm -c "$BASEDIR/dovecot.conf" mailbox create "foo" + doveadm -c "$BASEDIR/dovecot.conf" mailbox create "foo" <!-- --> $ env -i PATH="/usr/bin:/bin" USER="testuser" HOME="$BASEDIR/testuser" \ - doveadm -c "$BASEDIR/dovecot.conf" exec dovecot-lda -e -m "foo" <<-EOF + doveadm -c "$BASEDIR/dovecot.conf" exec dovecot-lda -e -m "foo" <<-EOF From: <sender@example.net> To: <recipient@example.net> Subject: Hello world! @@ -102,7 +102,7 @@ finally mark it as `\Seen`. EOF <!-- --> $ env -i PATH="/usr/bin:/bin" USER="testuser" \ - doveadm -c "$BASEDIR/dovecot.conf" flags add "\\Seen" mailbox "foo" "*" + doveadm -c "$BASEDIR/dovecot.conf" flags add "\\Seen" mailbox "foo" "*" Normally [`dovecot-lda`(1)][Dovecot LDA] tries to do a userdb lookup in order to determine the user's home directory. Since we didn't configure @@ -145,7 +145,7 @@ You can now run [`interimap`(1)] with `--watch` set, here to one second to observe synchronization steps early. $ env -i PATH="$PATH" perl -I./lib -T ./interimap --config="$BASEDIR/interimap.conf" \ - --watch=1 --debug + --watch=1 --debug Use instructions from the [previous section][Mail storage access] (substituting `testuser` with `local` or `remote`) in order to simulate @@ -169,12 +169,12 @@ Create a [`pullimap`(1)] configuration file with as section `[foo]`. Run [`pullimap`(1)] without `--idle` in order to create the state file. $ env -i PATH="$PATH" perl -I./lib -T ./pullimap --config="$BASEDIR/pullimap.conf" \ - --no-delivery foo + --no-delivery foo You can now run [`pullimap`(1)] with `--idle` set. $ env -i PATH="$PATH" perl -I./lib -T ./pullimap --config="$BASEDIR/pullimap.conf" \ - --no-delivery --idle --debug foo + --no-delivery --idle --debug foo Use instructions from the [previous section][Mail storage access] in order to simulate activity on the “remote” server (in the relevant diff --git a/doc/interimap.1.md b/doc/interimap.1.md index f10ced6..7df0100 100644 --- a/doc/interimap.1.md +++ b/doc/interimap.1.md @@ -376,7 +376,8 @@ Valid options are: *null-stderr* : Whether to redirect *command*'s standard error to `/dev/null` for - `type=tunnel`. (Default: `NO`.) + `type=tunnel`. This option is ignored when the `--debug` flag is + set. (Default: `NO`.) *SSL_protocols* @@ -396,25 +397,31 @@ Valid options are: *SSL_fingerprint* -: Fingerprint of the server certificate's Subject Public Key Info, in - the form `[ALGO$]DIGEST_HEX` where `ALGO` is the used algorithm (by - default `sha256`). +: Space-separated list of acceptable fingerprints for the server + certificate's Subject Public Key Info, in the form + `[ALGO$]DIGEST_HEX` where `ALGO` is the digest algorithm (by default + `sha256`). Attempting to connect to a server with a non-matching certificate SPKI fingerprint causes `interimap` to abort the connection during the SSL/TLS handshake. The following command can be used to compute the SHA-256 digest of a certificate's Subject Public Key Info: - openssl x509 -in /path/to/server/certificate.pem -pubkey \ - | openssl pkey -pubin -outform DER \ - | openssl dgst -sha256 + $ openssl x509 -in /path/to/server/certificate.pem -pubkey \ + | openssl pkey -pubin -outform DER \ + | openssl dgst -sha256 + + Specifying multiple digest values can be useful in key rollover + scenarios and/or when the server supports certificates of different + types (for instance RSA+ECDSA). In that case the connection is + aborted when none of the specified digests matches. *SSL_verify* : Whether to verify the server certificate chain. Note that using *SSL_fingerprint* to specify the fingerprint of the - server certificate is an orthogonal authentication measure as it - ignores the CA chain. + server certificate provides an independent server authentication + measure as it ignores the CA chain. (Default: `YES`.) *SSL_CApath* @@ -427,7 +434,7 @@ Valid options are: *SSL_CAfile* : File containing trusted certificates to use during server - certificate authentication if `SSL_verify=YES`. + certificate verification if `SSL_verify=YES`. Supported extensions {#supported-extensions} ==================== @@ -469,7 +476,7 @@ Known bugs and limitations * Because the [IMAP protocol][RFC 3501] doesn't provide a way for clients to determine whether a disappeared mailbox was deleted or renamed, `interimap` aborts when a known mailbox disappeared from one - server but not the other. The `--delete` (resp. `rename`) command + server but not the other. The `--delete` (resp. `--rename`) command should be used instead to delete (resp. rename) the mailbox on both servers as well as within `interimap`'s internal database. diff --git a/doc/pullimap.1.md b/doc/pullimap.1.md index 5028a14..98ec2ef 100644 --- a/doc/pullimap.1.md +++ b/doc/pullimap.1.md @@ -216,25 +216,31 @@ Valid options are: *SSL_fingerprint* -: Fingerprint of the server certificate's Subject Public Key Info, in - the form `[ALGO$]DIGEST_HEX` where `ALGO` is the used algorithm (by - default `sha256`). +: Space-separated list of acceptable fingerprints for the server + certificate's Subject Public Key Info, in the form + `[ALGO$]DIGEST_HEX` where `ALGO` is the digest algorithm (by default + `sha256`). Attempting to connect to a server with a non-matching certificate SPKI fingerprint causes `pullimap` to abort the connection during the SSL/TLS handshake. The following command can be used to compute the SHA-256 digest of a certificate's Subject Public Key Info: - openssl x509 -in /path/to/server/certificate.pem -pubkey \ - | openssl pkey -pubin -outform DER \ - | openssl dgst -sha256 + $ openssl x509 -in /path/to/server/certificate.pem -pubkey \ + | openssl pkey -pubin -outform DER \ + | openssl dgst -sha256 + + Specifying multiple digest values can be useful in key rollover + scenarios and/or when the server supports certificates of different + types (for instance RSA+ECDSA). In that case the connection is + aborted when none of the specified digests matches. *SSL_verify* : Whether to verify the server certificate chain. Note that using *SSL_fingerprint* to specify the fingerprint of the - server certificate is an orthogonal authentication measure as it - ignores the CA chain. + server certificate provides an independent server authentication + measure as it ignores the CA chain. (Default: `YES`.) *SSL_CApath* @@ -247,7 +253,7 @@ Valid options are: *SSL_CAfile* : File containing trusted certificates to use during server - certificate authentication if `SSL_verify=YES`. + certificate verification if `SSL_verify=YES`. Control flow {#control-flow} ============ @@ -369,8 +375,8 @@ Standards [RFC 4731]: https://tools.ietf.org/html/rfc4731 [INI file]: https://en.wikipedia.org/wiki/INI_file -[`fetchmail`(1)]: http://www.fetchmail.info/ +[`fetchmail`(1)]: https://www.fetchmail.info/ [`getmail`(1)]: http://pyropus.ca/software/getmail/ -[`write`(2)]: http://man7.org/linux/man-pages/man2/write.2.html +[`write`(2)]: https://man7.org/linux/man-pages/man2/write.2.html [`ciphers`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/ciphers.html [`verify`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/verify.html |