Mercurial > p > roundup > code
comparison doc/user_guide.txt @ 7279:0bf616cfa178
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 | e2f257ef737f |
| children | 8bc4246480bf |
comparison
equal
deleted
inserted
replaced
| 7278:e2f257ef737f | 7279:0bf616cfa178 |
|---|---|
| 49 3. using the `command line tool`_. | 49 3. using the `command line tool`_. |
| 50 | 50 |
| 51 The last is usually only used by administrators. Most users will use the | 51 The last is usually only used by administrators. Most users will use the |
| 52 web and e-mail interfaces. All three are explained below. | 52 web and e-mail interfaces. All three are explained below. |
| 53 | 53 |
| 54 .. _command line tool: admin_guide.html#using-roundup-admin | |
| 54 | 55 |
| 55 Issue life cycles in Roundup | 56 Issue life cycles in Roundup |
| 56 ---------------------------- | 57 ---------------------------- |
| 57 | 58 |
| 58 New issues may be submitted via the web or e-mail. | 59 New issues may be submitted via the web or e-mail. |
| 666 | 667 |
| 667 If the author of the message is also in the nosy list for the item that | 668 If the author of the message is also in the nosy list for the item that |
| 668 the message is attached to, then the config var ``MESSAGES_TO_AUTHOR`` | 669 the message is attached to, then the config var ``MESSAGES_TO_AUTHOR`` |
| 669 is queried to determine if they get a nosy list copy of the message too. | 670 is queried to determine if they get a nosy list copy of the message too. |
| 670 | 671 |
| 671 | |
| 672 Mail gateway script command line | |
| 673 -------------------------------- | |
| 674 | |
| 675 Usage:: | |
| 676 | |
| 677 usage: roundup_mailgw.py [-h] [-v] [-c DEFAULT_CLASS] [-I OAUTH_CLIENT_ID] | |
| 678 [-O OAUTH_DIRECTORY] [-S SET_VALUE] | |
| 679 [-T OAUTH_TOKEN_ENDPOINT] | |
| 680 [args ...] | |
| 681 | |
| 682 | |
| 683 The roundup mail gateway may be called in one of three ways: | |
| 684 | |
| 685 - without arguments. Then the env var ROUNDUP_INSTANCE will be tried. | |
| 686 - with an instance home as the only argument, | |
| 687 - with both an instance home and a mail spool file, or | |
| 688 - with an instance home, a mail source type and its specification. | |
| 689 | |
| 690 It also supports optional ``-S`` (or ``--set-value``) arguments that allows you | |
| 691 to set fields for a class created by the roundup-mailgw. The format for | |
| 692 this option is [class.]property=value where class can be omitted and | |
| 693 defaults to msg. The ``-S`` options uses the same | |
| 694 property=value[;property=value] notation accepted by the command line | |
| 695 roundup command or the commands that can be given on the Subject line of | |
| 696 an email message (if you're using multiple properties delimited with a | |
| 697 semicolon the class must be specified only once in the beginning). | |
| 698 | |
| 699 It can let you set the type of the message on a per e-mail address basis | |
| 700 by calling roundup-mailgw with different email addresses and other | |
| 701 settings. | |
| 702 | |
| 703 PIPE: | |
| 704 If there is no mail source specified, the mail gateway reads a single | |
| 705 message from the standard input and submits the message to the | |
| 706 roundup.mailgw module. | |
| 707 | |
| 708 UNIX mailbox: | |
| 709 In this case, the gateway reads all messages from the UNIX mail spool | |
| 710 file and submits each in turn to the roundup.mailgw module. The file is | |
| 711 emptied once all messages have been successfully handled. The file is | |
| 712 specified as:: | |
| 713 | |
| 714 mailbox /path/to/mailbox | |
| 715 | |
| 716 In all of the following mail source types, the username and password | |
| 717 can be stored in a ``~/.netrc`` file. If done so, only the server name | |
| 718 needs to be specified on the command-line. | |
| 719 The username and/or password will be prompted for if not supplied on | |
| 720 the command-line or in ``~/.netrc``. | |
| 721 | |
| 722 POP: | |
| 723 For the mail source "pop", the gateway reads all messages from the POP | |
| 724 server specified and submits each in turn to the roundup.mailgw module. | |
| 725 The server is specified as:: | |
| 726 | |
| 727 pop username:password@server | |
| 728 | |
| 729 The username and password may be omitted:: | |
| 730 | |
| 731 pop username@server | |
| 732 pop server | |
| 733 | |
| 734 are both valid. | |
| 735 | |
| 736 POPS: | |
| 737 Connect to a POP server over tls/ssl. | |
| 738 This supports the same notation as POP:: | |
| 739 | |
| 740 pops username:password@server | |
| 741 | |
| 742 APOP: | |
| 743 Same as POP, but using Authenticated POP:: | |
| 744 | |
| 745 apop username:password@server | |
| 746 | |
| 747 IMAP: | |
| 748 Connect to an IMAP server. This supports the same notation as that of | |
| 749 POP mail:: | |
| 750 | |
| 751 imap username:password@server | |
| 752 | |
| 753 It also allows you to specify a specific mailbox other than INBOX using | |
| 754 this format:: | |
| 755 | |
| 756 imap username:password@server mailbox | |
| 757 | |
| 758 IMAPS: | |
| 759 Connect to an IMAP server over tls/ssl. | |
| 760 This supports the same notation as IMAP:: | |
| 761 | |
| 762 imaps username:password@server [mailbox] | |
| 763 | |
| 764 IMAPS_CRAM: | |
| 765 Connect to an IMAP server over tls/ssl using CRAM-MD5 authentication. | |
| 766 This supports the same notation as IMAP:: | |
| 767 | |
| 768 imaps_cram username:password@server [mailbox] | |
| 769 | |
| 770 IMAPS_OAUTH: | |
| 771 Connect to an IMAP server over tls/ssl using OAUTH authentication. | |
| 772 Note that this does not support a password in imaps URLs. | |
| 773 Instead it uses only the user and server and a command-line option for | |
| 774 the directory with the files ``access_token``, ``refresh_token``, | |
| 775 ``client_secret``, and ``client_id``. | |
| 776 By default this directory is ``oauth`` in your tracker home directory. The | |
| 777 access token is tried first and, if expired, the refresh token together | |
| 778 with the client secret is used to retrieve a new access token. Note that | |
| 779 both token files need to be *writeable*, the access token is | |
| 780 continuously replaced and some cloud providers may also renew the | |
| 781 refresh token from time to time:: | |
| 782 | |
| 783 imaps_oauth username@server [mailbox] | |
| 784 | |
| 785 The refresh and access tokens (the latter can be left empty), the | |
| 786 client id and the client secret need to be retrieved via cloud provider | |
| 787 specific protocols or websites. | |
| 788 | |
| 789 You need the requests_ library installed for OAuth. | |
| 790 | |
| 791 .. _requests: https://requests.readthedocs.io/en/latest/ | |
| 792 | |
| 793 .. index:: ! roundup-admin | |
| 794 single: roundup-admin; usage | |
| 795 single: roundup-admin; data formats | |
| 796 pair: roundup-admin; designator | |
| 797 | |
| 798 Command Line Tool | |
| 799 ================= | |
| 800 | |
| 801 The basic usage is:: | |
| 802 | |
| 803 Usage: roundup-admin [options] [<command> <arguments>] | |
| 804 | |
| 805 Options: | |
| 806 -i instance home -- specify the issue tracker "home directory" to administer | |
| 807 -u -- the user[:password] to use for commands | |
| 808 -d -- print full designators not just class id numbers | |
| 809 -c -- when outputting lists of data, comma-separate them. | |
| 810 Same as '-S ","'. | |
| 811 -S <string> -- when outputting lists of data, string-separate them | |
| 812 -s -- when outputting lists of data, space-separate them. | |
| 813 Same as '-S " "'. | |
| 814 -V -- be verbose when importing | |
| 815 -v -- report Roundup and Python versions (and quit) | |
| 816 | |
| 817 Only one of -s, -c or -S can be specified. | |
| 818 | |
| 819 Help: | |
| 820 roundup-admin -h | |
| 821 roundup-admin help -- this help | |
| 822 roundup-admin help <command> -- command-specific help | |
| 823 roundup-admin help all -- all available help | |
| 824 | |
| 825 Commands: | |
| 826 commit | |
| 827 create classname property=value ... | |
| 828 display designator[,designator]* | |
| 829 export [[-]class[,class]] export_dir | |
| 830 exporttables [[-]class[,class]] export_dir | |
| 831 filter classname propname=value ... | |
| 832 find classname propname=value ... | |
| 833 genconfig <filename> | |
| 834 get property designator[,designator]* | |
| 835 help topic | |
| 836 history designator [skipquiet] | |
| 837 import import_dir | |
| 838 importtables export_dir | |
| 839 initialise [adminpw] | |
| 840 install [template [backend [key=val[,key=val]]]] | |
| 841 list classname [property] | |
| 842 migrate | |
| 843 pack period | date | |
| 844 perftest [mode] [arguments]* | |
| 845 pragma setting=value | |
| 846 reindex [classname|designator]* | |
| 847 restore designator[,designator]* | |
| 848 retire designator[,designator]* | |
| 849 rollback | |
| 850 security [Role name] | |
| 851 set items property=value property=value ... | |
| 852 specification classname | |
| 853 table classname [property[,property]*] | |
| 854 templates [trace_search] | |
| 855 updateconfig <filename> | |
| 856 Commands may be abbreviated as long as the abbreviation | |
| 857 matches only one command, e.g. l == li == lis == list. | |
| 858 | |
| 859 All commands (except help) require a tracker specifier. This is just the | |
| 860 path to the roundup tracker you're working with. A roundup tracker is | |
| 861 where roundup keeps the database and configuration file that defines an | |
| 862 issue tracker. It may be thought of as the issue tracker's "home | |
| 863 directory". It may be specified in the environment variable | |
| 864 ``TRACKER_HOME`` or on the command line as "``-i tracker``". | |
| 865 | |
| 866 A designator is a classname and an itemid concatenated, eg. bug1, | |
| 867 user10, ... Property values are represented as strings in command | |
| 868 arguments and in the printed results: | |
| 869 | |
| 870 - Strings are, well, strings. | |
| 871 - Password values will display as their encoded value. | |
| 872 - Date values are printed in the full date format in the local time | |
| 873 zone, and accepted in the full format or any of the partial formats | |
| 874 explained below.:: | |
| 875 | |
| 876 Input of... Means... | |
| 877 "2000-04-17.03:45" 2000-04-17.03:45:00 | |
| 878 "2000-04-17" 2000-04-17.00:00:00 | |
| 879 "01-25" yyyy-01-25.00:00:00 | |
| 880 "08-13.22:13" yyyy-08-13.22:13:00 | |
| 881 "11-07.09:32:43" yyyy-11-07.09:32:43 | |
| 882 "14:25" yyyy-mm-dd.14:25:00 | |
| 883 "8:47:11" yyyy-mm-dd.08:47:11 | |
| 884 "2003" 2003-01-01.00:00:00 | |
| 885 "2003-04" 2003-04-01.00:00:00 | |
| 886 "." "right now" | |
| 887 | |
| 888 - Link values are printed as item designators. When given as an | |
| 889 argument, item designators and key strings are both accepted. | |
| 890 - Multilink values are printed as lists of item designators joined by | |
| 891 commas. When given as an argument, item designators and key strings | |
| 892 are both accepted; an empty string, a single item, or a list of items | |
| 893 joined by commas is accepted. | |
| 894 | |
| 895 When multiple items are specified to the roundup get or roundup set | |
| 896 commands, the specified properties are retrieved or set on all the | |
| 897 listed items. When multiple results are returned by the roundup get or | |
| 898 roundup find commands, they are printed one per line (default) or joined | |
| 899 by commas (with the "``-c``" option). | |
| 900 | |
| 901 Where the command changes data, a login name/password is required. The | |
| 902 login may be specified as either "``name``" or "``name:password``". | |
| 903 | |
| 904 - ``ROUNDUP_LOGIN`` environment variable | |
| 905 - the "``-u``" command-line option | |
| 906 | |
| 907 If either the name or password is not supplied, they are obtained from | |
| 908 the command-line. | |
| 909 | |
| 910 The ``-u user`` setting does not currently operate like a | |
| 911 user logging in via the web. The user running roundup-admin | |
| 912 must have read access to the tracker home directory. As a | |
| 913 result the user has access to the files and the database | |
| 914 info contained in config.ini. | |
| 915 | |
| 916 Using ``-u user`` sets the actor/user parameter in the | |
| 917 journal. Changes that are made are attributed to that | |
| 918 user. The password is ignored if provided. Any existing | |
| 919 username has full access to the data just like the admin | |
| 920 user. This is an area for further development so that | |
| 921 roundup-admin could be used with sudo to provide secure | |
| 922 command line access to a tracker. | |
| 923 | |
| 924 When you initialise a new tracker instance you are prompted for the | |
| 925 admin password. If you want to initialise a tracker non-interactively | |
| 926 you can put the initialise command and password on the command | |
| 927 line. But this allows others on the host to see the password (using | |
| 928 the ps command). To initialise a tracker non-interactively without | |
| 929 exposing the password, create a file (e.g init_tracker) set to mode | |
| 930 600 (so only the owner can read it) with the contents: | |
| 931 | |
| 932 initialise admin_password | |
| 933 | |
| 934 and feed it to roundup-admin on standard input. E.G. | |
| 935 | |
| 936 cat init_tracker | roundup-admin -i tracker_dir | |
| 937 | |
| 938 (for more details see https://issues.roundup-tracker.org/issue2550789.) | |
| 939 | |
| 940 .. index:: ! roundup-admin; usage in scripts | |
| 941 | |
| 942 Using with the shell | |
| 943 -------------------- | |
| 944 | |
| 945 With version 0.6.0 or newer of roundup (which introduced support for | |
| 946 multiple designators to display and the -d, -S and -s flags): | |
| 947 | |
| 948 To find all messages regarding chatting issues that contain the word | |
| 949 "spam", for example, you could execute the following command from the | |
| 950 directory where the database dumps its files:: | |
| 951 | |
| 952 shell% for issue in `roundup-admin -ds find issue status=chatting`; do | |
| 953 > grep -l spam `roundup-admin -ds ' ' get messages $issue` | |
| 954 > done | |
| 955 msg23 | |
| 956 msg49 | |
| 957 msg50 | |
| 958 msg61 | |
| 959 shell% | |
| 960 | |
| 961 Or, using the -dc option, this can be written as a single command:: | |
| 962 | |
| 963 shell% grep -l spam `roundup get messages \ | |
| 964 \`roundup -dc find issue status=chatting\`` | |
| 965 msg23 | |
| 966 msg49 | |
| 967 msg50 | |
| 968 msg61 | |
| 969 shell% | |
| 970 | |
| 971 You can also display issue contents:: | |
| 972 | |
| 973 shell% roundup-admin display `roundup-admin -dc get messages \ | |
| 974 issue3,issue1` | |
| 975 files: [] | |
| 976 inreplyto: None | |
| 977 recipients: [] | |
| 978 author: 1 | |
| 979 date: 2003-02-16.21:23:03 | |
| 980 messageid: None | |
| 981 summary: jkdskldjf | |
| 982 files: [] | |
| 983 inreplyto: None | |
| 984 recipients: [] | |
| 985 author: 1 | |
| 986 date: 2003-02-15.01:59:11 | |
| 987 messageid: None | |
| 988 summary: jlkfjadsf | |
| 989 | |
| 990 or status:: | |
| 991 | |
| 992 shell% roundup-admin get name `/tools/roundup/bin/roundup-admin \ | |
| 993 -dc -i /var/roundup/sysadmin get status issue3,issue1` | |
| 994 unread | |
| 995 deferred | |
| 996 | |
| 997 or status on a single line:: | |
| 998 | |
| 999 shell% echo `roundup-admin get name \`/tools/roundup/bin/roundup-admin \ | |
| 1000 -dc -i /var/roundup/sysadmin get status issue3,issue1\`` | |
| 1001 unread deferred | |
| 1002 | |
| 1003 which is the same as:: | |
| 1004 | |
| 1005 shell% roundup-admin -s get name `/tools/roundup/bin/roundup-admin \ | |
| 1006 -dc -i /var/roundup/sysadmin get status issue3,issue1` | |
| 1007 unread deferred | |
| 1008 | |
| 1009 Also the tautological:: | |
| 1010 | |
| 1011 shell% roundup-admin get name \ | |
| 1012 `roundup-admin -dc get status \`roundup-admin -dc find issue \ | |
| 1013 status=chatting\`` | |
| 1014 chatting | |
| 1015 chatting | |
| 1016 | |
| 1017 Remember the roundup commands that accept multiple designators accept | |
| 1018 them ',' separated so using '-dc' is almost always required. | |
| 1019 |