view cmd/sievemgr/doc.go @ 22:fc5e6970a0d5 default tip

Add support for specifying an authorization identity on the command line
author Guido Berhoerster <guido+sievemgr@berhoerster.name>
date Wed, 17 Feb 2021 07:50:55 +0100
parents 2b799ca75d96
children
line wrap: on
line source

/*
The sievemgr command is a ManageSieve client.

Usage:

	sievemgr [-f config] info [-A authzid] [-a account]
	sievemgr [-f config] list [-A authzid] [-a account]
	sievemgr [-f config] get [-A authzid] [-a account] script
	sievemgr [-f config] put [-A authzid] [-a account] script [file]
	sievemgr [-f config] activate [-A authzid] [-a account] script
	sievemgr [-f config] deactivate [-A authzid] [-a account]
	sievemgr [-f config] delete [-A authzid] [-a account] script
	sievemgr [-f config] check [-A authzid] [-a account] [file]
	sievemgr [-f config] checkspace [-A authzid] [-a account] script [file]
	sievemgr [-f config] rename [-A authzid] [-a account] old new
	sievemgr [-f config] edit [-A authzid] [-a account] script
	sievemgr [-f config] man

Description:

sievemgr is a client for managing Sieve scripts on remote servers via the
ManageSieve Protocol (RFC 5804). Given valid credentials, sievemgr can be
invoked non-interactively in order to retrieve a list of all script scripts,
retrieve the scripts themselves, publish scripts on a server, or delete them.
Furthermore, it can be used to change the active script and to display
information about the server.

The ManageSieve server may either be referred to by a domain name or by its IP
address or hostname and optionally the port.  If only a domain name was
specified a DNS service lookup is performed in order to determine the hostname
and port of the ManageSieve server.  In case no service record exists or no
port was specified sievemgr will fall back to port 4190.

sievemgr only supports authentication using the SASL PLAIN mechanism and
requires support for TLS-encrypted connections via the STARTTLS command when
connecting to a server other than localhost.

Configuration File:

If a configuration file is not explicitly specified using the -f option
sievemgr will open the default configuration file in a platform-dependent
location:

	* on Unix either $XDG_CONFIG_HOME/sievemegr/sievemgr.conf if
	  XDG_CONFIG_HOME is set or $HOME/.config/sievemegr/sievemgr.conf
	* on Darwin $HOME/Library/Application Support/sievemegr/sievemgr.conf
	* on Windows %APPDATA%\sievemgr\sievemgr.conf

The owner of the file must match the effective user and the permissions of the
file must be set to disallow access by group or others.

Tokens in the configuration file are seperated by spaces, tabs, and newlines
and there are three types of tokens: identifiers, strings, and numbers.
Identifiers consist of the letters a-z and A-Z, numbers of 0-9.  Strings are
enclosed in double quotes, literal double quotes can be escaped with a
backslash and a literal backslash is escaped with another backslash.

The following tokens are recognized:

	account "name"
		Define an account which is referred to by name. The account
		definition ends when another account token is encountered or at
		the end of the file.

	default
		Set this as the default account.

	host "name"
		Specify the host- or domainname of the ManageSieve server.

	port number
		Specifiy the port number of the ManageSieve server.  If left
		out and the host token refers to a domainname, sievmgr will
		query DNS for a SRV record for a ManageSieve service associated
		with the domain and fall back to port 4190.

	user "name"
		Set the username of the account.

	pass "password"
		Set the password of the account.

	insecure
		Optionally specify that verification of the certificate
		presented by the server when making a TLS connection should be
		skipped.  This renders the connection insecure and should only
		be used for testing purposes.

An example configuration with two accounts is provided below:

	account "work" host "mail.example.com" port 2000 user "foo"
	account "private" default host "example.net" user "baz" pass "qux"

The first account must be explicitly referred to by its name "work".  sievemgr
will directly connect to the host "mail.example.com" using the non-standard
port 2000 since both host and port are given.  The user will be prompted for
the account password before authentication is performed with the username
"foo".

The second account is the default account, host and port name of the server
will be determined by looking up the corresponding SRV record associated with
the domain "example.net". Authentication will be performed non-interactively
with the username "baz" and password "qux".

Global Options:

	-f config
		Set the name of the configuration file to config.

Common Options:

	-A authzid
		Specify the authorization identity to assume if permitted by
		the given account credentials.

	-a account
		Select account from the configuration file.

Subcommands:

	sievemgr [-f config] info [-A authzid] [-a account]

Displays information about the ManageSieve server. This includes conformance to
RFC 5804, support for TLS connections, supported extensions, available SASL
authentication mechanisms, and supported notification methods.

	sievemgr [-f config] list [-A authzid] [-a account]

Lists all scripts on the server and indicate which of the is the currently
active script.

	sievemgr [-f config] get [-A authzid] [-a account] script

Fetch the contents of script from the server.

	sievemgr [-f config] put [-A authzid] [-a account] script [file]

Submit file under the name script to the server.  If file is not specified,
read the script from standard input.  The server will reject a script if it is
invalid or a storage quota is exceeded.

	sievemgr [-f config] activate [-A authzid] [-a account] script

Set script as the active script on the server.

	sievemgr [-f config] deactivate [-A authzid] [-a account]

Deactivate the currently active script on the server.

	sievemgr [-f config] delete [-A authzid] [-a account] script

Delete script from the server.

	sievemgr [-f config] check [-A authzid] [-a account] [file]

Check if file is a valid sieve script.  If file is not specified, read the
script from standard input.

	sievemgr [-f config] checkspace [-A authzid] [-a account] script [file]

Check if the script in file can be stored on the server without exceeding the
storage quota.  If script already exists the server will take overwriting it
into account.  If file is not specified, read the script from standard input.

	sievemgr [-f config] rename [-A authzid] [-a account] old new

Rename the script old to new.

	sievemgr [-f config] edit [-A authzid] [-a account] script

Retrieve a copy of script and start the editor referred to in the $EDITOR
environment variable.  If the local copy has not been modified or the editor
exits with a non-zero exit status the local copy of script will not be
submitted to the server.  In case of errors the local copy of the script will
be preserved.

	sievemgr [-f config] man

Display the user manual.
*/
package main