# HG changeset patch # User Guido Berhoerster # Date 1606603485 -3600 # Node ID 7ce77ceeacccc754630d2df7d6b5544d6dcc336d # Parent 8caacf702c0dc7d6c92888cea24728d4a92e2e66 Add documentation diff -r 8caacf702c0d -r 7ce77ceeaccc cmd/sievemgr/doc.go --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/cmd/sievemgr/doc.go Sat Nov 28 23:44:45 2020 +0100 @@ -0,0 +1,156 @@ +/* +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