Provided by: sieve-connect_0.87-1_all bug

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>]
                      [--noclearauth] [--noclearchan]
                      [--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.

       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 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.)

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.

       $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.

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
       <http://mail.globnix.net/mailman/listinfo/sieve-connect-announce> or you can send mail,
       mailto:sieve-connect-announce-request@spodhuis.org?subject=subscribe <mailto:sieve-
       connect-announce-request@spodhuis.org?subject=subscribe>

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!).