annotate share/man/man1/roundup-mailgw.1 @ 7752:b2dbab2b34bc

fix(refactor): multiple fixups using ruff linter; more testing. Converting to using the ruff linter and its rulesets. Fixed a number of issues. admin.py: sort imports use immutable tuples as default value markers for parameters where a None value is valid. reduced some loops to list comprehensions for performance used ternary to simplify some if statements named some variables to make them less magic (e.g. _default_savepoint_setting = 1000) fixed some tests for argument counts < 2 becomes != 2 so 3 is an error. moved exception handlers outside of loops for performance where exception handler will abort loop anyway. renamed variables called 'id' or 'dir' as they shadow builtin commands. fix translations of form _("string %s" % value) -> _("string %s") % value so translation will be looked up with the key before substitution. end dicts, tuples with a trailing comma to reduce missing comma errors if modified simplified sorted(list(self.setting.keys())) to sorted(self.setting.keys()) as sorted consumes whole list. in if conditions put compared variable on left and threshold condition on right. (no yoda conditions) multiple noqa: suppression removed unneeded noqa as lint rulesets are a bit different do_get - refactor output printing logic: Use fast return if not special formatting is requested; use isinstance with a tuple rather than two isinstance calls; cleaned up flow and removed comments on algorithm as it can be easily read from the code. do_filter, do_find - refactor output printing logic. Reduce duplicate code. do_find - renamed variable 'value' that was set inside a loop. The loop index variable was also named 'value'. do_pragma - added hint to use list subcommand if setting was not found. Replaced condition 'type(x) is bool' with 'isinstance(x, bool)' for various types. test_admin.py added testing for do_list better test coverage for do_get includes: -S and -d for multilinks, error case for -d with non-link. better testing for do_find including all output modes better testing for do_filter including all output modes fixed expected output for do_pragma that now includes hint to use pragma list if setting not found.
author John Rouillard <rouilj@ieee.org>
date Fri, 01 Mar 2024 14:53:18 -0500
parents f4a6f14e5cd6
children d614d8e1c09d
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
7660
f4a6f14e5cd6 doc: remove charater breaking formatting.
John Rouillard <rouilj@ieee.org>
parents: 7083
diff changeset
1 .TH ROUNDUP-MAILGW 1 "27 October 2022"
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
2 .SH NAME
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
3 roundup-mailgw \- mail gateway for roundup
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
4 .SH SYNOPSIS
7082
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
5 \fBroundup-mailgw\fP [\fI-h|--help] [\fI-v\fP] [\fI--version\fP]
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
6 [\fI-c|--default-class\fP \fIdefault_class\fP]
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
7 [\fI-S|--set-value\fP \fI[class.]field=value\fP]
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
8 [\fI-O|--oauth-directory\fP \fIdirectory\fP]
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
9 [\fI-T|--oauth-token-endpoint\fP \fIendpoint-url\fP]
5905
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
10 [\fIinstance_home\fP] [\fImail source [specification]\fP]
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
11 .SH OPTIONS
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
12 .TP
7082
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
13 \fB-v\fP \fB--version\fP
4706
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
14 Print version and exit.
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
15 .TP
7082
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
16 \fB-c\fP \fB--default-class\fP \fIhyperdb class\fP
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
17 specify the default tracker class - one of issue (the default), msg,
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
18 file, user etc. Overrides the tracker's mailgw \fIdefault_class\fP setting.
5905
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
19 .TP
7082
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
20 \fB-S\fP \fB--set-value\fP \fI[class.]property\fP\fB=\fP\fIvalue\fP[\fB;\fP\fIproperty\fP\fB=\fP\fIvalue\fP]
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
21 specify the values to set on the class specified as prefix using the same
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
22 format as the Subject line property manipulations. If the class prefix
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
23 is left out it defaults to \fImsg\fP. Can also be
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
24 specified with \fB--set-value\fP (and abbreviated to \fB--set\fP).
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
25 .TP
7082
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
26 \fB-O\fP \fB--oauth-directory\fP \fIdirectory\fP
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
27 Only with OAuth authentication specify the directory containing
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
28 additional OAuth credentials.
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
29 .TP
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
30 \fB-T\fP \fB--oauth-token-endpoint\fP \fIurl\fP
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
31 Token endpoint URL of your cloud provider, only used with OAuth.
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
32 .SH DESCRIPTION
5905
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
33 The roundup mail gateway may be called in one of four ways:
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
34 .IP \(bu
5905
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
35 without arguments which will use the env var ROUNDUP_INSTANCE,
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
36 .IP \(bu
7082
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
37 with an \fIinstance_home\fP as the only argument,
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
38 .IP \(bu
7082
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
39 with both an \fIinstance_home\fP and a mail spool file, or
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
40 .IP \(bu
5905
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
41 with both an instance home and a mail source type and its specification.
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
42 .PP
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
43 \fBPIPE\fP
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
44 .br
7082
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
45 If there is no mail source specified, the mail gateway reads a single
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
46 message from the standard input and submits the message to the
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
47 roundup.mailgw module.
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
48
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
49 \fBUNIX mailbox\fP
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
50 .br
7082
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
51 In this case, the gateway reads all messages from the UNIX mail spool
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
52 file and submits each in turn to the roundup.mailgw module. The file is
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
53 emptied once all messages have been successfully handled. The file is
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
54 specified as:
7082
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
55 \fBmailbox\fP \fI/path/to/mailbox\fP
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
56
7082
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
57 In all of the following mail source types, the username and password
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
58 can be stored in a ~/.netrc file. If done so, only the server name
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
59 needs to be specified on the command-line.
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
60
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
61 The username and/or password will be prompted for if not supplied on
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
62 the command-line or in ~/.netrc.
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
63
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
64 \fBPOP\fP
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
65 .br
7082
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
66 For the mail source "pop", the gateway reads all messages from the POP
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
67 server specified and submits each in turn to the roundup.mailgw module.
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
68 The server is specified as:
4706
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
69 \fBpop\fP \fIusername\fP\fB:\fP\fIpassword\fP\fB@\fP\fIserver\fP
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
70 .br
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
71 The username and password may be omitted:
4706
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
72 \fBpop\fP \fIusername\fP\fB@\fP\fIserver\fP
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
73 \fBpop\fP \fIserver\fP
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
74 .br
5905
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
75 are both valid.
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
76
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
77 \fBPOPS\fP
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
78 .br
7082
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
79 Connect to the POP server over ssl/tls.
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
80 This supports the same notation as POP.
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
81
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
82 \fBAPOP\fP
4706
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
83 .br
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
84 Same as POP, but using Authenticated POP:
4706
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
85 \fBapop\fP \fIusername\fP\fB:\fP\fIpassword\fP\fB@\fP\fIserver\fP
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
86
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
87 \fBIMAP\fP
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
88 .br
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
89 Connect to an IMAP server. This supports the same notation as that of
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
90 POP mail.
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
91 \fBimap\fP \fIusername\fP\fB:\fP\fIpassword\fP\fB@\fP\fIserver\fP
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
92 .br
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
93 It also allows you to specify a specific mailbox other than INBOX using
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
94 this format:
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
95 \fBimap\fP \fIusername\fP\fB:\fP\fIpassword\fP\fB@\fP\fIserver mailbox\fP
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
96
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
97 \fBIMAPS\fP
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
98 .br
5905
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
99 Connect to an IMAP server over ssl/tls.
4706
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
100 This supports the same notation as IMAP.
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
101 \fBimaps\fP \fIusername\fP\fB:\fP\fIpassword\fP\fB@\fP\fIserver\fP [\fImailbox\fP]
5905
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
102
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
103 \fBIMAPS_CRAM\fP
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
104 .br
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
105 Connect to an IMAP server over ssl/tls using CRAM-MD5 authentication.
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
106 This supports the same notation as IMAP.
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
107 \fBimaps_cram\fP \fIusername\fP\fB:\fP\fIpassword\fP\fB@\fP\fIserver\fP [\fImailbox\fP]
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
108
7082
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
109 \fBIMAPS_OAUTH\fP
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
110 .br
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
111 Connect to an IMAP server over ssl/tls using OAUTH authentication.
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
112 Note that this does not support a password in imaps URLs.
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
113 Instead it uses only the user and server and a command-line option for
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
114 the directory with the files \fBaccess_token\fP, \fBrefresh_token\fP,
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
115 \fBclient_secret\fP, and \fBclient_id\fP.
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
116 By default this directory is \fBoauth\fP in your tracker home directory. The
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
117 access token is tried first and, if expired, the refresh token together
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
118 with the client secret is used to retrieve a new access token. Note that
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
119 both token files need to be \fIwriteable\fP, the access token is
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
120 continuously replaced and some cloud providers may also renew the
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
121 refresh token from time to time:
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
122 \fBimaps_oauth\fP \fIusername\fP\fB@\fP\fIserver\fP [\fImailbox\fP]
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
123 .br
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
124 The refresh and access tokens (the latter can be left empty), the
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
125 client id and the client secret need to be retrieved via cloud provider
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
126 specific protocols or websites.
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
127
5905
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
128 .SH ENVIRONMENT VARIABLES
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
129
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
130 \fBROUNDUP_INSTANCE\fP
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
131 .br
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
132 This can be used to set the instance directory. If it is set, the
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
133 \fIinstance_home\fP argument is optional.
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
134
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
135 .SH EXAMPLE
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
136 If your msg class has a messsagetype property you can set
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
137 up aliases to receive the different types of messages. Setting up
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
138 an alias in your MTA Using:
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
139
7082
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
140 tracker: |/tools/roundup/bin/roundup-mailgw
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
141 -S "msg.messagetype=reply - to all" /var/roundup/sysadmin
5905
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
142
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
143 (the lines are split for readability. In the alias file they will be
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
144 on the same line). Replace /tools/roundup/bin/roundup-mailgw by your
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
145 path to the roundup-mailgw. This creates the email alias "tracker". All
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
146 messages sent to it have their messagetype property set to "reply -
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
147 to all". The roundup tracker instance is located at
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
148 /var/roundup/sysadmin.
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
149
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
150 A comment alias would receive emails at tracker_comment with:
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
151
7082
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
152 tracker_comment: |/tools/roundup/bin/roundup-mailgw
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
153 -S "msg.messagetype=to tech" /var/roundup/sysadmin
5905
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
154
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
155 which would be a technical message. These messages can trigger
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
156 different workflows based on the messagetype.
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
157
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
158 Both examples use the default class specified in the tracker's
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
159 config.ini (usually the issue class).
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
160
7083
259f1e571470 Update change date, add security issue example.
John Rouillard <rouilj@ieee.org>
parents: 7082
diff changeset
161 You can also set properties directly on the issue class. If
259f1e571470 Update change date, add security issue example.
John Rouillard <rouilj@ieee.org>
parents: 7082
diff changeset
162 your tracker's issue has a "private" property that limits
259f1e571470 Update change date, add security issue example.
John Rouillard <rouilj@ieee.org>
parents: 7082
diff changeset
163 who can view an issue and its messages:
259f1e571470 Update change date, add security issue example.
John Rouillard <rouilj@ieee.org>
parents: 7082
diff changeset
164
259f1e571470 Update change date, add security issue example.
John Rouillard <rouilj@ieee.org>
parents: 7082
diff changeset
165 security: |/tools/roundup/bin/roundup-mailgw
259f1e571470 Update change date, add security issue example.
John Rouillard <rouilj@ieee.org>
parents: 7082
diff changeset
166 -S "issue.private=true" -S "issue.keyword+=security"
259f1e571470 Update change date, add security issue example.
John Rouillard <rouilj@ieee.org>
parents: 7082
diff changeset
167 /var/roundup/sysadmin
259f1e571470 Update change date, add security issue example.
John Rouillard <rouilj@ieee.org>
parents: 7082
diff changeset
168
259f1e571470 Update change date, add security issue example.
John Rouillard <rouilj@ieee.org>
parents: 7082
diff changeset
169 would set the private property on a issue to restrict
259f1e571470 Update change date, add security issue example.
John Rouillard <rouilj@ieee.org>
parents: 7082
diff changeset
170 visiblity and mark the issue as a security topic using a
259f1e571470 Update change date, add security issue example.
John Rouillard <rouilj@ieee.org>
parents: 7082
diff changeset
171 keyword.
259f1e571470 Update change date, add security issue example.
John Rouillard <rouilj@ieee.org>
parents: 7082
diff changeset
172
259f1e571470 Update change date, add security issue example.
John Rouillard <rouilj@ieee.org>
parents: 7082
diff changeset
173 Both examples use the default class specified in the tracker's
259f1e571470 Update change date, add security issue example.
John Rouillard <rouilj@ieee.org>
parents: 7082
diff changeset
174 config.ini (usually the issue class).
259f1e571470 Update change date, add security issue example.
John Rouillard <rouilj@ieee.org>
parents: 7082
diff changeset
175
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
176 .SH AUTHOR
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
177 This manpage was written by Bastian Kleineidam
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
178 <calvin@debian.org> for the Debian distribution of roundup.
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
179
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
180 The main author of roundup is Richard Jones
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
181 <richard@users.sourceforge.net>.
5905
76e270b35e63 issue2550885: Documentation: update the roundup-mailgw manpage
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
182
7082
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
183 Updates by John Rouillard <rouilj@users.sourceforge.net> and Ralf
f0d39308819f Update manpage of mailgw
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5905
diff changeset
184 Schlatterbeck <rsc@runtux.com>.

Roundup Issue Tracker: http://roundup-tracker.org/