Provided by: sieve-connect_0.83-1_all 
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]
[--noclearauth] [--noclearchan]
[--authmech <mechanism>]
[--ignoreserverversion]
[--upload|--download|--list|--delete|--check
--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
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 server can be a host or IP address, IPv4 or IPv6; the default is $IMAP_SERVER from the
environment (if it's not a unix-domain socket path) with any port specificaion stripped
off, else localhost. The port can be any Perl port specification, default is sieve(4190).
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.
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.
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.
It is believed that the names of the actions are sufficiently self-descriptive for any
English-speaker who can safely be allowed unaccompanied computer usage.
(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.
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, to 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.
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.
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 0.97).
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.
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!).