Mercurial > p > roundup > code

comparison doc/admin_guide.txt @ 7279:0bf616cfa178

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Move mail gateway and roundup-admin doc to admin guide from user guide A little step toward diataxis. Move the mail gateway setup doc/manual and roundup-admin out of the user_guide. Make the user_guide a tutorial/reference for the UI via email and web.
author John Rouillard <rouilj@ieee.org>
date Tue, 25 Apr 2023 12:12:43 -0400
parents 16d6d81b4565
children 1aad478fc03f
comparison
equal deleted inserted replaced
7278:e2f257ef737f 7279:0bf616cfa178
1016 1016
1017 1. Create a new local account on the Roundup server 1017 1. Create a new local account on the Roundup server
1018 2. Set the scheduled task to run in the context of this user instead 1018 2. Set the scheduled task to run in the context of this user instead
1019 of your normal login 1019 of your normal login
1020 1020
1021 Mail gateway script command line
1022 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1023
1024 Usage::
1025
1026 usage: roundup_mailgw.py [-h] [-v] [-c DEFAULT_CLASS] [-I OAUTH_CLIENT_ID]
1027 [-O OAUTH_DIRECTORY] [-S SET_VALUE]
1028 [-T OAUTH_TOKEN_ENDPOINT]
1029 [args ...]
1030
1031
1032 The roundup mail gateway may be called in one of three ways:
1033
1034 - without arguments. Then the env var ROUNDUP_INSTANCE will be tried.
1035 - with an instance home as the only argument,
1036 - with both an instance home and a mail spool file, or
1037 - with an instance home, a mail source type and its specification.
1038
1039 It also supports optional ``-S`` (or ``--set-value``) arguments that allows you
1040 to set fields for a class created by the roundup-mailgw. The format for
1041 this option is [class.]property=value where class can be omitted and
1042 defaults to msg. The ``-S`` options uses the same
1043 property=value[;property=value] notation accepted by the command line
1044 roundup command or the commands that can be given on the Subject line of
1045 an email message (if you're using multiple properties delimited with a
1046 semicolon the class must be specified only once in the beginning).
1047
1048 It can let you set the type of the message on a per e-mail address basis
1049 by calling roundup-mailgw with different email addresses and other
1050 settings.
1051
1052 PIPE:
1053 If there is no mail source specified, the mail gateway reads a single
1054 message from the standard input and submits the message to the
1055 roundup.mailgw module.
1056
1057 UNIX mailbox:
1058 In this case, the gateway reads all messages from the UNIX mail spool
1059 file and submits each in turn to the roundup.mailgw module. The file is
1060 emptied once all messages have been successfully handled. The file is
1061 specified as::
1062
1063 mailbox /path/to/mailbox
1064
1065 In all of the following mail source types, the username and password
1066 can be stored in a ``~/.netrc`` file. If done so, only the server name
1067 needs to be specified on the command-line.
1068 The username and/or password will be prompted for if not supplied on
1069 the command-line or in ``~/.netrc``.
1070
1071 POP:
1072 For the mail source "pop", the gateway reads all messages from the POP
1073 server specified and submits each in turn to the roundup.mailgw module.
1074 The server is specified as::
1075
1076 pop username:password@server
1077
1078 The username and password may be omitted::
1079
1080 pop username@server
1081 pop server
1082
1083 are both valid.
1084
1085 POPS:
1086 Connect to a POP server over tls/ssl.
1087 This supports the same notation as POP::
1088
1089 pops username:password@server
1090
1091 APOP:
1092 Same as POP, but using Authenticated POP::
1093
1094 apop username:password@server
1095
1096 IMAP:
1097 Connect to an IMAP server. This supports the same notation as that of
1098 POP mail::
1099
1100 imap username:password@server
1101
1102 It also allows you to specify a specific mailbox other than INBOX using
1103 this format::
1104
1105 imap username:password@server mailbox
1106
1107 IMAPS:
1108 Connect to an IMAP server over tls/ssl.
1109 This supports the same notation as IMAP::
1110
1111 imaps username:password@server [mailbox]
1112
1113 IMAPS_CRAM:
1114 Connect to an IMAP server over tls/ssl using CRAM-MD5 authentication.
1115 This supports the same notation as IMAP::
1116
1117 imaps_cram username:password@server [mailbox]
1118
1119 IMAPS_OAUTH:
1120 Connect to an IMAP server over tls/ssl using OAUTH authentication.
1121 Note that this does not support a password in imaps URLs.
1122 Instead it uses only the user and server and a command-line option for
1123 the directory with the files ``access_token``, ``refresh_token``,
1124 ``client_secret``, and ``client_id``.
1125 By default this directory is ``oauth`` in your tracker home directory. The
1126 access token is tried first and, if expired, the refresh token together
1127 with the client secret is used to retrieve a new access token. Note that
1128 both token files need to be *writeable*, the access token is
1129 continuously replaced and some cloud providers may also renew the
1130 refresh token from time to time::
1131
1132 imaps_oauth username@server [mailbox]
1133
1134 The refresh and access tokens (the latter can be left empty), the
1135 client id and the client secret need to be retrieved via cloud provider
1136 specific protocols or websites.
1137
1138 You need the requests_ library installed for OAuth.
1139
1140 .. _requests: https://requests.readthedocs.io/en/latest/
1141
1142
1021 .. index:: ! roundup-admin 1143 .. index:: ! roundup-admin
1144 single: roundup-admin; usage
1145 single: roundup-admin; data formats
1022 single: roundup-admin; man page reference 1146 single: roundup-admin; man page reference
1147 pair: roundup-admin; designator
1023 1148
1024 Using roundup-admin 1149 Using roundup-admin
1025 =================== 1150 ===================
1026 1151
1027 Part of the installation includes a man page for roundup-admin. Ypu 1152 Part of the installation includes a man page for roundup-admin. Ypu
1034 * install and initialize a new tracker 1159 * install and initialize a new tracker
1035 * export/import tracker data for migrating between backends 1160 * export/import tracker data for migrating between backends
1036 * creating a new user fom the command line 1161 * creating a new user fom the command line
1037 * list/find users in the tracker 1162 * list/find users in the tracker
1038 1163
1039 A brief (incomplete) summary is:: 1164 The basic usage is::
1040 1165
1041 roundup-admin help 1166 Usage: roundup-admin [options] [<command> <arguments>]
1042 roundup-admin -i <tracker_dir> get [-list] designator[, designator,...] propname 1167
1043 roundup-admin -i <tracker_dir> set designator[, designator,...] propname=value ... 1168 Options:
1044 roundup-admin -i <tracker_dir> find [-list] classname propname=value ... 1169 -i instance home -- specify the issue tracker "home directory" to administer
1045 1170 -u -- the user[:password] to use for commands
1046 Run ``roundup-admin help commands`` for a complete list of subcommands. 1171 -d -- print full designators not just class id numbers
1172 -c -- when outputting lists of data, comma-separate them.
1173 Same as '-S ","'.
1174 -S <string> -- when outputting lists of data, string-separate them
1175 -s -- when outputting lists of data, space-separate them.
1176 Same as '-S " "'.
1177 -V -- be verbose when importing
1178 -v -- report Roundup and Python versions (and quit)
1179
1180 Only one of -s, -c or -S can be specified.
1181
1182 Help:
1183 roundup-admin -h
1184 roundup-admin help -- this help
1185 roundup-admin help <command> -- command-specific help
1186 roundup-admin help all -- all available help
1187
1188 Commands:
1189 commit
1190 create classname property=value ...
1191 display designator[,designator]*
1192 export [[-]class[,class]] export_dir
1193 exporttables [[-]class[,class]] export_dir
1194 filter classname propname=value ...
1195 find classname propname=value ...
1196 genconfig <filename>
1197 get property designator[,designator]*
1198 help topic
1199 history designator [skipquiet]
1200 import import_dir
1201 importtables export_dir
1202 initialise [adminpw]
1203 install [template [backend [key=val[,key=val]]]]
1204 list classname [property]
1205 migrate
1206 pack period | date
1207 perftest [mode] [arguments]*
1208 pragma setting=value
1209 reindex [classname|designator]*
1210 restore designator[,designator]*
1211 retire designator[,designator]*
1212 rollback
1213 security [Role name]
1214 set items property=value property=value ...
1215 specification classname
1216 table classname [property[,property]*]
1217 templates [trace_search]
1218 updateconfig <filename>
1219 Commands may be abbreviated as long as the abbreviation
1220 matches only one command, e.g. l == li == lis == list.
1047 1221
1048 One thing to note, The ``-u user`` setting does not currently operate 1222 One thing to note, The ``-u user`` setting does not currently operate
1049 like a user logging in via the web. The user running roundup-admin 1223 like a user logging in via the web. The user running roundup-admin
1050 must have read access to the tracker home directory. As a result the 1224 must have read access to the tracker home directory. As a result the
1051 user has access to the files and the database info contained in 1225 user has access to the files and the database info contained in
1059 roundup-admin could be used with sudo to provide secure 1233 roundup-admin could be used with sudo to provide secure
1060 command line access to a tracker. 1234 command line access to a tracker.
1061 1235
1062 In general you should forget that there is a -u parameter. 1236 In general you should forget that there is a -u parameter.
1063 1237
1238 All commands (except help) require a tracker specifier. This is just the
1239 path to the roundup tracker you're working with. A roundup tracker is
1240 where roundup keeps the database and configuration file that defines an
1241 issue tracker. It may be thought of as the issue tracker's "home
1242 directory". It may be specified in the environment variable
1243 ``TRACKER_HOME`` or on the command line as "``-i tracker``".
1244
1245 A designator is a classname and an itemid concatenated, eg. bug1,
1246 user10, ... Property values are represented as strings in command
1247 arguments and in the printed results:
1248
1249 - Strings are, well, strings.
1250 - Password values will display as their encoded value.
1251 - Date values are printed in the full date format in the local time
1252 zone, and accepted in the full format or any of the partial formats
1253 explained below.::
1254
1255 Input of... Means...
1256 "2000-04-17.03:45" 2000-04-17.03:45:00
1257 "2000-04-17" 2000-04-17.00:00:00
1258 "01-25" yyyy-01-25.00:00:00
1259 "08-13.22:13" yyyy-08-13.22:13:00
1260 "11-07.09:32:43" yyyy-11-07.09:32:43
1261 "14:25" yyyy-mm-dd.14:25:00
1262 "8:47:11" yyyy-mm-dd.08:47:11
1263 "2003" 2003-01-01.00:00:00
1264 "2003-04" 2003-04-01.00:00:00
1265 "." "right now"
1266
1267 - Link values are printed as item designators. When given as an
1268 argument, item designators and key strings are both accepted.
1269 - Multilink values are printed as lists of item designators joined by
1270 commas. When given as an argument, item designators and key strings
1271 are both accepted; an empty string, a single item, or a list of items
1272 joined by commas is accepted.
1273
1274 When multiple items are specified to the roundup get or roundup set
1275 commands, the specified properties are retrieved or set on all the
1276 listed items. When multiple results are returned by the roundup get or
1277 roundup find commands, they are printed one per line (default) or joined
1278 by commas (with the "``-c``" option).
1279
1280 Where the command changes data, a login name/password is required. The
1281 login may be specified as either "``name``" or "``name:password``".
1282
1283 - ``ROUNDUP_LOGIN`` environment variable
1284 - the "``-u``" command-line option
1285
1286 If either the name or password is not supplied, they are obtained from
1287 the command-line.
1288
1289 The ``-u user`` setting does not currently operate like a
1290 user logging in via the web. The user running roundup-admin
1291 must have read access to the tracker home directory. As a
1292 result the user has access to the files and the database
1293 info contained in config.ini.
1294
1295 Using ``-u user`` sets the actor/user parameter in the
1296 journal. Changes that are made are attributed to that
1297 user. The password is ignored if provided. Any existing
1298 username has full access to the data just like the admin
1299 user. This is an area for further development so that
1300 roundup-admin could be used with sudo to provide secure
1301 command line access to a tracker.
1302
1303 When you initialise a new tracker instance you are prompted for the
1304 admin password. If you want to initialise a tracker non-interactively
1305 you can put the initialise command and password on the command
1306 line. But this allows others on the host to see the password (using
1307 the ps command). To initialise a tracker non-interactively without
1308 exposing the password, create a file (e.g init_tracker) set to mode
1309 600 (so only the owner can read it) with the contents:
1310
1311 initialise admin_password
1312
1313 and feed it to roundup-admin on standard input. E.G.
1314
1315 cat init_tracker | roundup-admin -i tracker_dir
1316
1317 (for more details see https://issues.roundup-tracker.org/issue2550789.)
1318
1319 .. index:: ! roundup-admin; usage in scripts
1320
1321 Using with the shell
1322 --------------------
1323
1324 With version 0.6.0 or newer of roundup (which introduced support for
1325 multiple designators to display and the -d, -S and -s flags):
1326
1327 To find all messages regarding chatting issues that contain the word
1328 "spam", for example, you could execute the following command from the
1329 directory where the database dumps its files::
1330
1331 shell% for issue in `roundup-admin -ds find issue status=chatting`; do
1332 > grep -l spam `roundup-admin -ds ' ' get messages $issue`
1333 > done
1334 msg23
1335 msg49
1336 msg50
1337 msg61
1338 shell%
1339
1340 Or, using the -dc option, this can be written as a single command::
1341
1342 shell% grep -l spam `roundup get messages \
1343 \`roundup -dc find issue status=chatting\``
1344 msg23
1345 msg49
1346 msg50
1347 msg61
1348 shell%
1349
1350 You can also display issue contents::
1351
1352 shell% roundup-admin display `roundup-admin -dc get messages \
1353 issue3,issue1`
1354 files: []
1355 inreplyto: None
1356 recipients: []
1357 author: 1
1358 date: 2003-02-16.21:23:03
1359 messageid: None
1360 summary: jkdskldjf
1361 files: []
1362 inreplyto: None
1363 recipients: []
1364 author: 1
1365 date: 2003-02-15.01:59:11
1366 messageid: None
1367 summary: jlkfjadsf
1368
1369 or status::
1370
1371 shell% roundup-admin get name `/tools/roundup/bin/roundup-admin \
1372 -dc -i /var/roundup/sysadmin get status issue3,issue1`
1373 unread
1374 deferred
1375
1376 or status on a single line::
1377
1378 shell% echo `roundup-admin get name \`/tools/roundup/bin/roundup-admin \
1379 -dc -i /var/roundup/sysadmin get status issue3,issue1\``
1380 unread deferred
1381
1382 which is the same as::
1383
1384 shell% roundup-admin -s get name `/tools/roundup/bin/roundup-admin \
1385 -dc -i /var/roundup/sysadmin get status issue3,issue1`
1386 unread deferred
1387
1388 Also the tautological::
1389
1390 shell% roundup-admin get name \
1391 `roundup-admin -dc get status \`roundup-admin -dc find issue \
1392 status=chatting\``
1393 chatting
1394 chatting
1395
1396 Remember the roundup commands that accept multiple designators accept
1397 them ',' separated so using '-dc' is almost always required.
1398
1399
1064 .. _`customisation documentation`: customizing.html 1400 .. _`customisation documentation`: customizing.html
1065 .. _`upgrading documentation`: upgrading.html 1401 .. _`upgrading documentation`: upgrading.html
1066 .. _`installation documentation`: installation.html 1402 .. _`installation documentation`: installation.html
Roundup Issue Tracker: http://roundup-tracker.org/