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