Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 ]
	   >

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.88				  2016-08-29		      sieve-connect(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | ENVIRONMENT | BUGS | NON-BUGS | HISTORY | AUTHOR | AVAILABILITY | PREREQUISITES | INTEROPERABILITY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sieve-connect&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help