sieve-connect(1)

📦
version 0.90 · 3 versions
, in alpine 3.24, arch rolling, debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

<pink>sieve-connect(1)</pink> — bestie, this is the manual page for sieve-connect, aka the managesieve command-line client. It's giving "control your Sieve scripts from the terminal" and honestly, slay. 💅

✨ SYNOPSIS ✨

Here's the exact shape of it, no cap:

 sieve-connect [-s <hostname>] [-p <portspec>] [-u <user>] [a <authzid>]
               [-m <authmech>] [-r realm] [-e execscript]
               [... longopts ...]
 sieve-connect [--localsieve <script>] [--remotesieve <script>]
               [--debug] [--dumptlsinfo]
               [--server <hostname>] [--port <portspec>] [--4|--6]
               [--user <authentication_id>] [--authzid <authzid>]
               [--realm <realm>] [--passwordfd <n>]
               [--clientkey <file> --clientcert <file>]|[--clientkeycert <file>]
               [--notlsverify|--nosslverify]
               [--tlscertfingerprint|--sslcertfingerprint <dgsttype:digest>]
               [--tlscapath <ca_directory>]|[--tlscafile <ca_file>]
               [--tlshostname <hostname>]
               [--noclearauth] [--noclearchan] [--clearchan]
               [--authmech <mechanism>]
               [--ignoreserverversion]
               [--upload|--download|--list|--delete|--checkscript|--edit|
                --activate|--deactivate]|[--exec <script>]
               [--help|--man]

🫶 DESCRIPTION 🫶

<pink>sieve-connect</pink> is a client for the "MANAGESIEVE" protocol — that's the RFC-specified protocol for manipulation of "Sieve" scripts in a repository. Translation? sieve-connect lets you control your mail-filtering rule files on a mail server. 💖

You can invoke sieve-connect with an action from the command-line so one-shot actions are easy to script, or hand it a script file, or just let it drop into an interactive command-loop. In that loop it supports tab-completion (if the supporting Perl module is available) and basic navigation of the local file-system in the style of "FTP" clients. ✨

sieve-connect supports the use of "TLS" via the "STARTTLS" command, including authentication via client certificates. sieve-connect also supports whichever "SASL" mechanisms your Authen::SASL::Perl library provides, as long as they do not require SASL protection layers. 🔥

In Interactive mode, a help command is available. Command parameters with a % in them are examined to see if they match %KEYWORD, where "KEYWORD" is always in upper-case. The list of keywords may be retrieved with the keywords command and includes items such as %DATE, %USER, etc. 🦋

💅 OPTIONS 💅

Option names may be given as the shortest unique prefix. Periodt. 💅

Up in the synopsis you'll spot --localsieve <script> and --remotesieve <script>. The remote sieve script name defaults to the same as the local sieve script name, so if only one is needed, just specify the local one; it was a deliberate decision to have the defaults this way around, to make people think about names in the local filesystem. There is no default script name. 🎀

--debug turns on diagnostic traces. --debugsasl asks the SASL library for debugging. --dumptlsinfo shows the TLS (SSL) peer information; if you also pass --debug, the server's PEM certificate will be provided as debug trace. 👑

--version shows version information. Combine it with --debug and it will show implementation dependency versions. --help and --man provide usage information. 🌸

The server can be a host or IP address, IPv4 or IPv6.

If a server is provided by --server then that takes precedence. If that option is not present, then $IMAP_SERVER from the environment is checked and, if it's not a unix-domain socket path, is used with any port specification stripped off. ✨

For TLS verification, this is the default name used for hostnames (both SNI and verification); no information derived from DNS is currently used as the trusted hostname identifier. (This is subject to change in future, given DNSSEC). --tlshostname can override the name used for TLS. 🔐

Next, unless --nosrv is given, checks are made for SRV records so as to search for a default server; if the Mozilla::PublicSuffix Perl module is available, these checks are done for every level of the hostname upto (but not including) the public suffix. If that module is not available, a crude heuristic is used: as long as there are three dots in the hostname, SRV records for the part of the hostname after the first dot are tried. If this is inappropriate, install Mozilla::PublicSuffix. 🧚

If no SRV records are found which point to a sieve, imaps or imap protocol service, or if a record is found which says "no such service in this domain" (by having a target of "."), then the final default server is localhost. 🏠

The --port value can be any Perl port specification, default is sieve(4190). A port from an SRV record will take precedence. The Perl specification provides a name to look up in the system services database (/etc/services) followed in parentheses by a default value to use if the name is not found. Thus this default will honour a value of 2000 from /etc/services. 🔥

--4 or --6 may be used to coerce IPv4 or IPv6. 🌈

By default, the server is taken to be a domain, for which SRV records are looked up; use --nosrv to inhibit SRV record lookup. 🛑

--user will be required unless you're on a Unix system with getpwuid() available and your Cyrus account name matches your system account name. --authmech can force a particular authentication mechanism. --authzid can request authorisation to act as the specified id. --realm can try to pass realm information to the authentication mechanism. If you want to provide a password programmatically, use --passwordfd to state which file descriptor (typically 0) the password can be read from. Everything until the newline before EOF is the password, so it can contain embedded newlines. Do not provide passwords on a command-line or in a process environment. 💀

Unless modified at install/packaging time, by default SSL certificate authority certificates are searched for. The first attempt is to try, in turn, for environment variables $SSL_CERT_DIR & $SSL_CERT_FILE which are the names supported by the OpenSSL library and so often supported by client commands. Next, if the OpenSSL command "version" is available and the output "OPENSSLDIR" can be parsed and the "certs" directory exists within that directory, then that location will be used. Finally, a fixed list of common locations are searched and the first one to exist is used. Invoking with --debug will show more details during the "setup:" phase. 🔍

Precedence above these defaults is given to --tlscafile if given, else --tlscapath if that is given. The former is one file containing certificates, the latter is a directory. 📁

Alternatively, if you are willing to accept the risk of man-in-the-middle active attacks and you are unable to arrange for the relevant Certificate Authority certificate to be available, then you can lower your safety with --notlsverify, also spelt --nosslverify. 😭

If verification is requested (the default) but TLS is not available, we do not fall back to cleartext insecure communications. Use --clearchan to change that, or set $SIEVECONNECT_INSECURE_CLEARTEXT_FALLBACK non-empty in the environment. 🚨

If you don't want to (only) rely on CA systems you can explicitly set an expected server certificate fingerprint using --tlscertfingerprint, also spelt --sslcertfingerprint. If you wish to ignore CA validation, you still need to disable that explicitly (see above), as the default is to add an extra constraint (pinning, within valid CA certificates). This option specifies the X.509 certificate fingerprint (not a public key fingerprint), as given by OpenSSL. The first part of the value should be an algorithm name, such as "sha256" or "sha1". That is followed by a colon, and then the fingerprint data in its usual colon-delimited hexadecimal notation. Eg: --tlscertfingerprint sha256:24:B4:..28-more-fields..:A8:58 🔐

For SSL client certificate authentication, either --clientkeycert may be used to refer to a file with both the key and cert present or both --clientkey and --clientcert should point to the relevant files. The data should be in PEM file-format. 🎀

--noclearauth will prevent use of cleartext authentication mechanisms unless protected by TLS. --noclearchan will mandate use of some confidentiality layer; at this time only TLS is supported. 🛡️

By default, the server's "VERSION" capability will be used to filter the commands available. Use --ignoreserverversion to prevent this. 👑

The remaining options denote actions. One, and only one, action may be present. If no action is present, the interactive mode is entered. If the exec action is present, commands are read from the script instead. 🎬

  • --upload — will upload a script to the server. ⬆️
  • --download — will download a script from the server. ⬇️
  • --list — will list the scripts which exist on the server. One of those scripts might be marked ACTIVE. 📜
  • --delete — will delete a script from the server. 🗑️
  • --checkscript — will ask the server to validate the local file provided. ✅
  • --edit — will download a script, invoke an editor upon it, ask the server to check the results (and offer to re-edit if the server rejects it) and finally upload the result. 📝
  • --activate — will mark the specified remote script as the active one. 🔛
  • --deactivate — will remove the active mark from the specified remote script without activating a replacement. 🔚
  • --exec — will take a file-name containing commands as though given in the normal read-eval-print loop. 🌀

Note that --check and --edit require a server which advertises a "VERSION" capability, see --ignoreserverversion to override. 🚩

(If --server is not explicitly stated, it may be provided at the end of the command-line for compatibility with sieveshell.) 💖

🎀 EXAMPLES 🎀

Okay bestie, real talk, these are the receipts. Live footage. 💖

Connect to a Sieve server and hop into interactive mode, when you've already got a Kerberos ticket and GSSAPI/Kerberos is available:

$ sieve-connect --server imap.example.org
ReadLine support enabled.
>

Same energy, but with $IMAP_SERVER chillin' in the environ:

$ sieve-connect
ReadLine support enabled.
>

Upload a script from the current directory, and get prompted to authenticate. Heads up: the script won't be activated — uploading just makes it available, possibly after the server has checked it for errors first:

$ sieve-connect --server imap.example.org --user fred@example.org \
     --localsieve fred.siv --upload
Sieve/IMAP Password: [password here, not shown]
$

Wanna see a lot of what's happening under the covers? Say less:

$ sieve-connect --debug
[ snip 30 or so lines ]
>

Use --passwordfd to hand over the password via stdio instead of argv or environ, where it might show up in process listings. This example assumes a shell with "here-strings", like zsh or bash:

$   password='...'
$ sieve-connect --authmech digest-md5 --passwordfd=5 5<<<"$password"
ReadLine support enabled.
>

🌸 ENVIRONMENT 🌸

  • $IMAP_SERVER — sets a default IMAP server. Convenient. Iconic. 💅
  • $USERNAME and $LOGNAME — used where the getpwuid() function is not available.
  • $SSL_CERT_DIR and $SSL_CERT_FILE — for locating default Certificate Authority trust anchors.
  • $SIEVECONNECT_INSECURE_CLEARTEXT_FALLBACK — to preserve the old poor hygiene around TLS fallback. 😭
  • $VISUAL, else $EDITOR — used for the edit action.

💀 BUGS 💀

Okay so, the tea:

  • If the authentication protocol negotiates a protection layer, then things will rapidly Go Bad. A mitigating factor is that no protection layer should be negotiated whilst under STARTTLS protection. Just use TLS, bestie. Fr fr. 🔥
  • When listing scripts, the format is based on the raw server output, assuming the server uses quoted-strings for the script names. The output is just passed back on the basis that it's a fairly good interface to pass to a program. But a server could choose to use literal strings, even though the results are defined as line-break separated — which would mean some linebreaks are special. Hopefully no server will do this. 🙈
  • If sieve-connect fails to connect to an IPv4 server without the -4 option being explicitly passed, then you've hit a portability issue in the IO::Socket::INET6 Perl library and you need to upgrade that.
  • Most historical implementations used port 2000 for ManageSieve. RFC5804 allocates port 4190. This tool uses a port-spec of sieve(4190) as the default port, which means an /etc/services (or substitute) entry for sieve as a TCP service takes precedence — but if that's not present, it'll assume 4190 as the default. This change means that if you're still using port 2000 and don't have an /etc/services entry, updating to/beyond release 0.75 of this tool will break invocations that don't specify a port. The specification of the default port was moved to the user-configurable section at the top of the script, and administrators may wish to override the shipped default. You can bypass all of this mess by publishing SRV records, per RFC5804.
  • The Net::DNS Perl module does not (at time of writing) provide full support for weighted prioritised SRV records, and no effort has been made to fix this. Whatever the default sort algorithm provides for SRV is what gets used for ordering.
  • If you don't specify a server and don't export $IMAP_SERVER in the environment, then the search mechanism is safer and more thorough if the Mozilla::PublicSuffix Perl module is installed. In particular, if your hostname is also your domain name and the parent domain is administered by someone you don't trust, then you'll regret not installing that module. 😭
  • Probably need to sit down and work through the final RFC and see if any functionality is still missing.

✨ NON-BUGS ✨

  • Actually uses STARTTLS. 💅
  • Can handle script names with embedded whitespace.
  • Author needs access to a server which handles embedded quote characters properly to complete testing of that.

🦋 HISTORY 🦋

sieve-connect was written as a demonstration for the info-cyrus mailing-list, 2006-11-14. It was a single-action-and-quit script for scripting purposes. The command-loop code was written (two days) later and deliberately designed to be compatible with sieveshell.

Versions prior to 0.85 did not actually verify the peer certificate identity, although this author stupidly believed that it did. API/expectations mismatch. 💀

Versions prior to 0.88 defaulted to falling back to cleartext in the absence of STARTTLS if CA information was configured locally and verification requested (the default). Today, this is no longer acceptable for client-server communications; either verify-and-require-TLS or don't-verify-and-fallback-to-cleartext. This is the new policy going forward; use --clearchan to allow fallback while still trying to verify TLS (but why?) or --notlsverify to skip verification. Or add $SIEVECONNECT_INSECURE_CLEARTEXT_FALLBACK non-empty in the environment to avoid the implicit noclearchan-when-verify-enabled.

👑 AUTHOR 👑

Phil Pennock <phil-perl@spodhuis.org> is guilty, m'Lud. 🫶

There is a low-volume announcement list for new releases; the web interface is at <http://mail.globnix.net/mailman/listinfo/sieve-connect-announce> or you can send mail, <mailto:sieve-connect-announce-request@spodhuis.org?subject=subscribe>

🌈 AVAILABILITY 🌈

Releases are made available at <http://people.spodhuis.org/phil.pennock/software/> in the form of a tarball and an associated detached PGP signature. All releases are signed, always, and always have been. The signing key is in the PGP Strong Set (which means there's a stronger chance that you can verify the identity of the key owner). Historically, releases were signed with key 0x403043153903637F. If you're reading this text from a release, then a new release has been cut since switching to key 0x4D1E900E14C1CC04, and you should expect that 4096RSA key to be used, barring major incident.

The source code is available via Git; the authoritative public-facing repository is currently <https://github.com/philpennock/sieve-connect> and pull-requests and bug-reports are accepted there. 🎀

⭐ PREREQUISITES ⭐

  • Perl.
  • Authen::SASL.
  • IO::Socket::INET6.
  • IO::Socket::SSL (at least version 1.14).
  • Pod::Usage.
  • Net::DNS for SRV lookup.
  • Pod::Simple::Text for built-in man command (optional).
  • Term::ReadKey to get passwords without echo.
  • Various other Perl modules which are believed to be standard.
  • Term::ReadLine will significantly improve interactive mode.
  • Term::ReadLine::Gnu will improve it further by allowing tab-completion.
  • Mozilla::PublicSuffix is highly recommended and will improve security. 💖

🧚 INTEROPERABILITY 🧚

sieve-connect is regularly tested with the timsieved server distributed with the Cyrus IMAP server. Further interoperability testing is underway, more is desired (test accounts appreciated!). 🫶

That's the whole page, bestie — version 0.90, dated 2019-03-29, straight out of the sieve-connect(1) manual. Go forth and ManageSieve responsibly. 💜✨

📦 where this page comes from