projects/sievemgr

changeset 9:7ce77ceeaccc

Add documentation
author Guido Berhoerster <guido+sievemgr@berhoerster.name>
date Sat Nov 28 23:44:45 2020 +0100 (10 months ago)
parents 8caacf702c0d
children 44c07eb8ef08
files cmd/sievemgr/doc.go
line diff
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/cmd/sievemgr/doc.go	Sat Nov 28 23:44:45 2020 +0100
     1.3 @@ -0,0 +1,156 @@
     1.4 +/*
     1.5 +The sievemgr command is a ManageSieve client.
     1.6 +
     1.7 +Usage:
     1.8 +
     1.9 +	sievemgr [-f config] info [-a account]
    1.10 +	sievemgr [-f config] list [-a account]
    1.11 +	sievemgr [-f config] get [-a account] script
    1.12 +	sievemgr [-f config] put [-a account] script [file]
    1.13 +	sievemgr [-f config] activate [-a account] script
    1.14 +	sievemgr [-f config] deactivate [-a account]
    1.15 +	sievemgr [-f config] delete [-a account] script
    1.16 +	sievemgr [-f config] check [-a account] [file]
    1.17 +	sievemgr [-f config] checkspace [-a account] script [file]
    1.18 +	sievemgr [-f config] rename [-a account] old new
    1.19 +	sievemgr [-f config] edit [-a account] script
    1.20 +
    1.21 +Description:
    1.22 +
    1.23 +sievemgr is a client for managing Sieve scripts on remote servers via the
    1.24 +ManageSieve Protocol (RFC 5804). Given valid credentials, sievemgr can be
    1.25 +invoked non-interactively in order to retrieve a list of all script scripts,
    1.26 +retrieve the scripts themselves, publish scripts on a server, or delete them.
    1.27 +Furthermore, it can be used to change the active script and to display
    1.28 +information about the server.
    1.29 +
    1.30 +The ManageSieve server may either be referred to by a domain name or by its IP
    1.31 +address or hostname and optionally the port.  If only a domain name was
    1.32 +specified a DNS service lookup is performed in order to determine the hostname
    1.33 +and port of the ManageSieve server.  In case no service record exists or no
    1.34 +port was specified sievemgr will fall back to port 4190.
    1.35 +
    1.36 +sievemgr only supports authentication using the SASL PLAIN mechanism and
    1.37 +requires support for TLS-encrypted connections via the STARTTLS command when
    1.38 +connecting to a server other than localhost.
    1.39 +
    1.40 +Configuration File:
    1.41 +
    1.42 +If a configuration file is not explicitly specified using the -f option
    1.43 +sievemgr will open the default configuration file in a platform-dependent
    1.44 +location:
    1.45 +
    1.46 +	* on Unix either $XDG_CONFIG_HOME/sievemegr/sievemgr.conf if
    1.47 +	  XDG_CONFIG_HOME is set or $HOME/.config/sievemegr/sievemgr.conf
    1.48 +	* on Darwin $HOME/Library/Application Support/sievemegr/sievemgr.conf
    1.49 +	* on Windows %APPDATA%\sievemgr\sievemgr.conf
    1.50 +
    1.51 +The owner of the file must match the effective user and the permissions of the
    1.52 +file must be set to disallow access by group or others.
    1.53 +
    1.54 +Tokens in the configuration file are seperated by spaces, tabs, and newlines
    1.55 +and there are three types of tokens: identifiers, strings, and numbers.
    1.56 +Identifiers consist of the letters a-z and A-Z, numbers of 0-9.  Strings are
    1.57 +enclosed in double quotes, literal double quotes can be escaped with a
    1.58 +backslash and a literal backslash is escaped with another backslash.
    1.59 +
    1.60 +The following tokens are recognized:
    1.61 +
    1.62 +	account "name"
    1.63 +		Define an account which is referred to by name. The account
    1.64 +		definition ends when another account token is encountered or at
    1.65 +		the end of the file.
    1.66 +
    1.67 +	default
    1.68 +		Set this as the default account.
    1.69 +
    1.70 +	host "name"
    1.71 +		Specify the host- or domainname of the ManageSieve server.
    1.72 +
    1.73 +	port number
    1.74 +		Specifiy the port number of the ManageSieve server.  If left
    1.75 +		out and the host token refers to a domainname, sievmgr will
    1.76 +		query DNS for a SRV record for a ManageSieve service associated
    1.77 +		with the domain and fall back to port 4190.
    1.78 +
    1.79 +	user "name"
    1.80 +		Set the username of the account.
    1.81 +
    1.82 +	pass "password"
    1.83 +		Set the password of the account.
    1.84 +
    1.85 +	insecure
    1.86 +		Optionally specify that verification of the certificate
    1.87 +		presented by the server when making a TLS connection should be
    1.88 +		skipped.  This renders the connection insecure and should only
    1.89 +		be used for testing purposes.
    1.90 +
    1.91 +Global Options:
    1.92 +
    1.93 +	-f config
    1.94 +		Set the name of the configuration file to config.
    1.95 +
    1.96 +Common Options:
    1.97 +
    1.98 +	-a account
    1.99 +		Select account from the configuration file.
   1.100 +
   1.101 +Subcommands:
   1.102 +
   1.103 +	sievemgr [-f config] info [-a account]
   1.104 +
   1.105 +Displays information about the ManageSieve server. This includes conformance to
   1.106 +RFC 5804, support for TLS connections, supported extensions, available SASL
   1.107 +authentication mechanisms, and supported notification methods.
   1.108 +
   1.109 +	sievemgr [-f config] list [-a account]
   1.110 +
   1.111 +Lists all scripts on the server and indicate which of the is the currently
   1.112 +active script.
   1.113 +
   1.114 +	sievemgr [-f config] get [-a account] script
   1.115 +
   1.116 +Fetch the contents of script from the server.
   1.117 +
   1.118 +	sievemgr [-f config] put [-a account] script [file]
   1.119 +
   1.120 +Submit file under the name script to the server.  If file is not specified,
   1.121 +read the script from standard input.  The server will reject a script if it is
   1.122 +invalid or a storage quota is exceeded.
   1.123 +
   1.124 +	sievemgr [-f config] activate [-a account] script
   1.125 +
   1.126 +Set script as the active script on the server.
   1.127 +
   1.128 +	sievemgr [-f config] deactivate [-a account]
   1.129 +
   1.130 +Deactivate the currently active script on the server.
   1.131 +
   1.132 +	sievemgr [-f config] delete [-a account] script
   1.133 +
   1.134 +Delete script from the server.
   1.135 +
   1.136 +	sievemgr [-f config] check [-a account] [file]
   1.137 +
   1.138 +Check if file is a valid sieve script.  If file is not specified, read the
   1.139 +script from standard input.
   1.140 +
   1.141 +	sievemgr [-f config] checkspace [-a account] script [file]
   1.142 +
   1.143 +Check if the script in file can be stored on the server without exceeding the
   1.144 +storage quota.  If script already exists the server will take overwriting it
   1.145 +into account.  If file is not specified, read the script from standard input.
   1.146 +
   1.147 +	sievemgr [-f config] rename [-a account] old new
   1.148 +
   1.149 +Rename the script old to new.
   1.150 +
   1.151 +	sievemgr [-f config] edit [-a account] script
   1.152 +
   1.153 +Retrieve a copy of script and start the editor referred to in the $EDITOR
   1.154 +environment variable.  If the local copy has not been modified or the editor
   1.155 +exits with a non-zero exit status the local copy of script will not be
   1.156 +submitted to the server.  In case of errors the local copy of the script will
   1.157 +be preserved.
   1.158 +*/
   1.159 +package main