projects/sievemgr
changeset 9:7ce77ceeaccc
Add documentation
author | Guido Berhoerster <guido+sievemgr@berhoerster.name> |
---|---|
date | Sat Nov 28 23:44:45 2020 +0100 (3 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