projects/sievemgr

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

Add documentation
author Guido Berhoerster <guido+sievemgr@berhoerster.name>
date Sat Nov 28 23:44:45 2020 +0100 (2020-11-28)
parents
children 44c07eb8ef08
line source
1 /*
2 The sievemgr command is a ManageSieve client.
4 Usage:
6 sievemgr [-f config] info [-a account]
7 sievemgr [-f config] list [-a account]
8 sievemgr [-f config] get [-a account] script
9 sievemgr [-f config] put [-a account] script [file]
10 sievemgr [-f config] activate [-a account] script
11 sievemgr [-f config] deactivate [-a account]
12 sievemgr [-f config] delete [-a account] script
13 sievemgr [-f config] check [-a account] [file]
14 sievemgr [-f config] checkspace [-a account] script [file]
15 sievemgr [-f config] rename [-a account] old new
16 sievemgr [-f config] edit [-a account] script
18 Description:
20 sievemgr is a client for managing Sieve scripts on remote servers via the
21 ManageSieve Protocol (RFC 5804). Given valid credentials, sievemgr can be
22 invoked non-interactively in order to retrieve a list of all script scripts,
23 retrieve the scripts themselves, publish scripts on a server, or delete them.
24 Furthermore, it can be used to change the active script and to display
25 information about the server.
27 The ManageSieve server may either be referred to by a domain name or by its IP
28 address or hostname and optionally the port. If only a domain name was
29 specified a DNS service lookup is performed in order to determine the hostname
30 and port of the ManageSieve server. In case no service record exists or no
31 port was specified sievemgr will fall back to port 4190.
33 sievemgr only supports authentication using the SASL PLAIN mechanism and
34 requires support for TLS-encrypted connections via the STARTTLS command when
35 connecting to a server other than localhost.
37 Configuration File:
39 If a configuration file is not explicitly specified using the -f option
40 sievemgr will open the default configuration file in a platform-dependent
41 location:
43 * on Unix either $XDG_CONFIG_HOME/sievemegr/sievemgr.conf if
44 XDG_CONFIG_HOME is set or $HOME/.config/sievemegr/sievemgr.conf
45 * on Darwin $HOME/Library/Application Support/sievemegr/sievemgr.conf
46 * on Windows %APPDATA%\sievemgr\sievemgr.conf
48 The owner of the file must match the effective user and the permissions of the
49 file must be set to disallow access by group or others.
51 Tokens in the configuration file are seperated by spaces, tabs, and newlines
52 and there are three types of tokens: identifiers, strings, and numbers.
53 Identifiers consist of the letters a-z and A-Z, numbers of 0-9. Strings are
54 enclosed in double quotes, literal double quotes can be escaped with a
55 backslash and a literal backslash is escaped with another backslash.
57 The following tokens are recognized:
59 account "name"
60 Define an account which is referred to by name. The account
61 definition ends when another account token is encountered or at
62 the end of the file.
64 default
65 Set this as the default account.
67 host "name"
68 Specify the host- or domainname of the ManageSieve server.
70 port number
71 Specifiy the port number of the ManageSieve server. If left
72 out and the host token refers to a domainname, sievmgr will
73 query DNS for a SRV record for a ManageSieve service associated
74 with the domain and fall back to port 4190.
76 user "name"
77 Set the username of the account.
79 pass "password"
80 Set the password of the account.
82 insecure
83 Optionally specify that verification of the certificate
84 presented by the server when making a TLS connection should be
85 skipped. This renders the connection insecure and should only
86 be used for testing purposes.
88 Global Options:
90 -f config
91 Set the name of the configuration file to config.
93 Common Options:
95 -a account
96 Select account from the configuration file.
98 Subcommands:
100 sievemgr [-f config] info [-a account]
102 Displays information about the ManageSieve server. This includes conformance to
103 RFC 5804, support for TLS connections, supported extensions, available SASL
104 authentication mechanisms, and supported notification methods.
106 sievemgr [-f config] list [-a account]
108 Lists all scripts on the server and indicate which of the is the currently
109 active script.
111 sievemgr [-f config] get [-a account] script
113 Fetch the contents of script from the server.
115 sievemgr [-f config] put [-a account] script [file]
117 Submit file under the name script to the server. If file is not specified,
118 read the script from standard input. The server will reject a script if it is
119 invalid or a storage quota is exceeded.
121 sievemgr [-f config] activate [-a account] script
123 Set script as the active script on the server.
125 sievemgr [-f config] deactivate [-a account]
127 Deactivate the currently active script on the server.
129 sievemgr [-f config] delete [-a account] script
131 Delete script from the server.
133 sievemgr [-f config] check [-a account] [file]
135 Check if file is a valid sieve script. If file is not specified, read the
136 script from standard input.
138 sievemgr [-f config] checkspace [-a account] script [file]
140 Check if the script in file can be stored on the server without exceeding the
141 storage quota. If script already exists the server will take overwriting it
142 into account. If file is not specified, read the script from standard input.
144 sievemgr [-f config] rename [-a account] old new
146 Rename the script old to new.
148 sievemgr [-f config] edit [-a account] script
150 Retrieve a copy of script and start the editor referred to in the $EDITOR
151 environment variable. If the local copy has not been modified or the editor
152 exits with a non-zero exit status the local copy of script will not be
153 submitted to the server. In case of errors the local copy of the script will
154 be preserved.
155 */
156 package main