view cmd/sievemgr/doc.go @ 9:7ce77ceeaccc

Add documentation
author Guido Berhoerster <guido+sievemgr@berhoerster.name>
date Sat, 28 Nov 2020 23:44:45 +0100
parents
children 44c07eb8ef08
line wrap: on
line source

/*
The sievemgr command is a ManageSieve client.

Usage:

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

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.

Global Options:

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

Common Options:

	-a account
		Select account from the configuration file.

Subcommands:

	sievemgr [-f config] info [-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 account]

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

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

Fetch the contents of script from the server.

	sievemgr [-f config] put [-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 account] script

Set script as the active script on the server.

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

Deactivate the currently active script on the server.

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

Delete script from the server.

	sievemgr [-f config] check [-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 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 account] old new

Rename the script old to new.

	sievemgr [-f config] edit [-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.
*/
package main