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>]
[--noclearauth] [--noclearchan]
[--authmech <mechanism>]
[--upload│--download│--list│--delete│
--activate│--deactivate]│[--exec <script>]
[--help│--man]
DESCRIPTION
sieve-connect is a client for the "MANAGESIEVE" protocol, which is an
Internet Draft 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(2000). The
--4 or --6 options may be used to coerce IPv4 or IPv6.
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.
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.
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.
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.
PREREQUISITES
Perl. Authen::SASL. IO::Socket::INET6. IO::Socket::SSL (at least
version 0.97). Pod::Usage. 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!).