sieve-connect(1)                                              sieve-connect(1)


NAME
       sieve-connect - managesieve command-line client

SYNOPSIS
        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
       sieve-connect is a client for the "MANAGESIEVE" protocol, which is an
       RFC-specified protocol for manipulation of "Sieve" scripts in a
       repository.  More simply, sieve-connect lets you control your mail-
       filtering rule files on a mail server.

       sieve-connect can be invoked with an action from the command-line to
       make it easy to script one-shot actions, it can be provided with a
       script file or it can be left to enter an interactive command-loop,
       where 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.

       The remote sieve script name defaults to the same as the local sieve
       script name, so just specify the local one if only one is needed; 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.

       The --debug option turns on diagnostic traces.  The --debugsasl option
       asks the SASL library for debugging.  The --dumptlsinfo shows the TLS
       (SSL) peer information; if specified together with --debug then the
       server's PEM certificate will be provided as debug trace.

       The --version option shows version information.  When combined with
       --debug it will show implementation dependency versions.  The --help
       and --man options 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).  The --tlshostname option can be used to
       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, of 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 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.

       The --4 or --6 options 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.

       The --user option 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 be used to force a particular
       authentication mechanism.  --authzid can be used to request
       authorisation to act as the specified id.  --realm can be used to 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 the --tlscafile option if
       given, else the --tlscapath option 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 the --notlsverify option, 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 the
       --tlscertfingerprint option, 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.

       The --noclearauth option will prevent use of cleartext authentication
       mechanisms unless protected by TLS.  The --noclearchan option 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
       Connect to a Sieve server and enter interactive mode, when you already
       have a Kerberos ticket and GSSAPI/Kerberos is available:

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

       Do the same, but with $IMAP_SERVER set in environ:

           $ sieve-connect
           ReadLine support enabled.
           >

       Upload a script from the current directory, being prompted to
       authenticate; note that the script won't be activated (uploading just
       makes it available, possibly with the server having first checked it
       for errors):

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

       See a lot of what's happening under the covers:

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

       Use --passwordfd to supply the password using stdio instead of argv or
       environ, where it might show up in process listings; this example
       assumes a shell with "here-strings", such as zsh or bash:

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

ENVIRONMENT
       $IMAP_SERVER for a default IMAP server.

       $USERNAME and $LOGNAME 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 old poor hygiene
       around TLS fallback.

       $VISUAL, else $EDITOR, for the edit action.

BUGS
       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!

       When listing scripts, the format is based upon the raw server output,
       assuming that 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 -- that would mean that 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 encountered a portability
       issue in the IO::Socket::INET6 Perl library and 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 that an /etc/services
       (or substitute) entry for "sieve" as a TCP service takes precedence,
       but if that is not present, will assume 4190 as the default.  This
       change means that if you're still using port 2000 and do not have an
       /etc/services entry, updating to/beyond release 0.75 of this tool will
       break invocations which do not 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 I have not made any
       effort to fix this; whatever the default sort algorithm provides for
       SRV is what is 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 I've cut a new release since switching to key
       0x4D1E900E14C1CC04 and I 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!).

0.90                              2019-03-29                  sieve-connect(1)