code-d30e534b078a/share/man/man1/roundup-admin.10000644000000000000000000002632514511366522017237 0ustar 00000000000000.TH ROUNDUP-ADMIN 1 "24 January 2003" .SH NAME roundup-admin \- administrate roundup trackers .SH SYNOPSIS \fBroundup-admin\fP [\fIoptions\fP] \fI\fP \fI\fP .SH OPTIONS .TP \fB-i\fP \fIinstance home\fP Specify the issue tracker "home directory" to administer .TP \fB-u\fP \fIuser\fP[\fB:\fP\fIpassword\fP] The user and password to use for commands (partial implemention, see Security Notes below). .TP \fB-h\fP Print help text. .TP \fB-d\fP Print full designators (e.g. issue1) not just id numbers (1). .TP \fB-c\fP When outputting lists of data, comma-separate them. Same as \fB-S ","\fP. .TP \fB-S\fP \fIstring\fP When outputting lists of data, separate items with given string. .TP \fB-s\fP When outputting lists of data, space-separate them. Same as \fB-S " "\fP. .TP \fB-P pragma=value\fP Set a pragma on the command line. Multiple \fB-P\fP options can be specified to set multiple pragmas. .TP \fB-V\fP Be verbose when importing data. .TP \fB-v\fP Report Roundup and Python versions and quit. .PP Only one of \fB-s\fP, \fB-c\fP or \fB-S\fP can be specified. .SH COMMANDS If no command is provided on the command line, roundup-admin will enter an interactive mode. More details about these commands are available using the help command. A designator is a classname and a nodeid concatenated, eg. bug1, user10, .... Roundup-admin takes a number of commands: .TP \fBhelp\fP prints help (same as \fB-h\fP) .TP \fBhelp\fP \fI\fP Print command-specific help .TP \fBhelp all\fP Print available help for all commands. .TP \fBcommit\fP Commit changes made to the database during an interactive session. The changes made during an interactive session are not automatically written to the database - they must be committed using this command. One-off commands on the command-line are automatically committed if they are successful. See also rollback. .TP \fBcreate\fP \fIclassname property=value ...\fP This creates a new entry of the given class using the property name=value arguments provided on the command line after the "create" command. .TP \fBdisplay\fP \fIdesignator[,designator]*\fP This lists the properties and their associated values for the given node. The pragma \fBdisplay_header\fP can be used to add a header between designators that includes the active/retired status of the item. .TP \fBexport\fP \fI[[-]class[,class]] export_dir\fP Export the database to colon-separated-value files. To exclude the files (e.g. for the msg or file class), use the exporttables command. Optionally limit the export to just the named classes or exclude the named classes, if the 1st argument starts with '-'. This action exports the current data from the database into colon-separated-value files that are placed in the nominated destination directory. .TP \fBexporttables\fP \fI[[-]class[,class]] export_dir\fP Export the database to colon-separated-value files, excluding the files below $TRACKER_HOME/db/files/ (which can be archived separately). To include the files, use the export command. .TP \fBfilter\fP \fIclassname propname=value ...\fP Find the nodes of the given class with a given property value. Multiple values can be specified by separating them with commas. If property is a string, all values must match. I.E. it's an 'and' operation. If the property is a link/multilink any value matches. I.E. an 'or' operation. .TP \fBfind\fP \fIclassname propname=value ...\fP Find the nodes of the given class with a given link property value. .TP \fBgenconfig\fP \fI\fP Generate a new tracker config file (ini style) with default values in \fI\fP. Note that this does not preserve any settings from the current tracker. Use updateconfig for that. .TP \fBget\fP \fIproperty designator[,designator]*\fP Get the given property of one or more designator(s). Retrieves the property value of the nodes specified by the designators. .TP \fBhistory\fP \fIdesignator [skipquiet]\fP Lists the journal entries viewable by the user for the node identified by the designator. If skipquiet is the second argument, journal entries for quiet properties are not shown. .TP \fBimport\fP \fIimport_dir\fP Import a database from the directory containing CSV files, two per class to import. The imported nodes will have the same nodeid as defined in the import file, thus replacing any existing content. The new nodes are added to the existing database - if you want to create a new database using the imported data, then create a new database (or, tediously, retire all the old data). See also export. .TP \fBimporttables\fP \fIimport_dir\fP Import a database from the directory containing CSV files, two per class to import. The imported nodes will have the same nodeid as defined in the import file, thus replacing any existing content. This only imports database tables. It does not import files/message content. It is used to import data exported by exporttables. See also exporttables. .TP \fBinitialise\fP \fI[adminpw]\fP Initialise a new Roundup tracker. The administrator details will be set at this step. .TP \fBinstall\fP \fI[template [backend [key=val[,key=val]]]]\fP Install a new roundup tracker. The command will prompt for the tracker home directory (if not supplied through TRACKER_HOME or the -i option). The template and backend may be specified on the command-line as arguments, in that order. Command line arguments following the backend allows you to pass initial values for config options. For example, passing "web_http_auth=no,rdbms_user=dinsdale" will override defaults for options http_auth in section [web] and user in section [rdbms]. Please be careful to not use spaces in this argument! (Enclose whole argument in quotes if you need spaces in option value). The initialise command must be called after this command in order to initialise the tracker's database. You may edit the tracker's initial database contents before running that command by editing the tracker's dbinit.py module init() function. See also initopts help. .TP \fBlist\fP \fIclassname [property]\fP Lists all instances of the given class. If the property is not specified, the "label" property is used. The label property is tried in order: the key, "name", "title" and then the first property, alphabetically. With \fB-c\fP, \fB-S\fP or \fB-s\fP print a list of item id's if no property specified. If property specified, print list of that property for every class instance. The pragma \fBshow_retired\fP can be used to print only retired items or to print retired and active items. The default is to print only active items. .TP \fBmigrate\fP Update a tracker's database to be compatible with the Roundup codebase. You should run the "migrate" command for your tracker once you've installed the latest codebase. Do this before you use the web, command-line or mail interface and before any users access the tracker. This command will respond with either "Tracker updated" (if you've not previously run it on an RDBMS backend) or "No migration action required" (if you have run it, or have used another interface to the tracker, or possibly because you are using anydbm). It's safe to run this even if it's not required, so just get into the habit. .TP \fBpack\fP \fIperiod | date\fP Remove journal entries older than a period of time specified or before a certain date. .TP \fBperftest\fP \fI[mode] [arguments]*\fP Run performance test. For example test the effect of changing password hashing parameters. .TP \fBpragma\fP \fIsetting=value\fP|\fBlist\fP Set internal settings to a value. E.G. pragma verbose=True pragma verbose=yes pragma verbose=on pragma verbose=1 will turn on verbose mode for roundup-admin. pragma list will show all settings and their current values. If verbose is enabled hidden settings and descriptions will be shown. .TP \fBreindex\fP \fI[classname|classname:#-#|designator]*\fP This will re-generate the search indexes for a tracker. You can specify a specific item (or items) (e.g. issue23), range(s) of items (e.g. issue:1-1000), class(es) (e.g. issue) or reindex all items in the database if no arguments are supplied. .TP \fBrestore\fP \fIdesignator[,designator]*\fP Restore the retired node specified by designator. The given nodes will become available for users again. .TP \fBretire\fP \fIdesignator[,designator]*\fP This action indicates that a particular node is not to be retrieved by the list or find commands, and its key value may be re-used. See also restore. .TP \fBrollback\fP Undo all changes that are pending commit to the database. The changes made during an interactive session are not automatically written to the database - they must be committed manually. This command undoes all those changes, so a commit immediately after would make no changes to the database. .TP \fBsecurity\fP \fI[Role name]\fP Display the Permissions available to one or all Roles. .TP \fBset\fP \fIitems property=value property=value ...\fP Set the given properties of one or more items(s). The items are specified as a class or as a comma-separated list of item designators (ie "designator[,designator,...]"). This command sets the properties to the values for all designators given. If the value is missing (ie. "property=") then the property is un-set. If the property is a multilink, you specify the linked ids for the multilink as comma-separated numbers (ie "1,2,3"). .TP \fBspecification\fP \fIclassname\fP Show the properties for a classname. .TP \fBtemplates\fP \fI[trace_search]]\fP Lists the names, location and description of all known templates. .TP \fBtable\fP \fIclassname [property[,property]*]\fP Lists all instances of the given class. If the properties are not specified, all properties are displayed. By default, the column widths are the width of the largest value. The pragma \fBshow_retired\fP can be used to print only retired items or to print retired and active items. The default is to print only active items. .TP \fBupdateconfig\fP \fI\fP This is used when updating software. It merges the \fBconfig.ini\fP from the tracker with new settings from the new software. The merged/updated config file is written to \fI\fP. .PP Commands may be abbreviated as long as the abbreviation matches only one command, e.g. l == li == lis == list. .SH SECURITY NOTES The \fB-u user\fP setting does not currently operate like a user logging in via the web. The user running roundup-admin must have read access to the tracker home directory. As a result the user has access to the files and the database info contained in config.ini. Using \fB-u user\fP sets the actor/user parameter in the journal. Changes that are made are attributed to that user. The password is ignored if provided. Any existing username has full access to the data just like the admin user. This is an area for further development so that roundup-admin could be used with sudo to provide secure command line access to a tracker. .SH ENVIRONMENT VARIABLES .TP \fBROUNDUP_LOGIN\fP Provides an alternate way to set the user. .SH FURTHER HELP roundup-admin -h roundup-admin help -- this help roundup-admin help -- command-specific help roundup-admin help all -- all available help .SH AUTHOR This manpage was written by Bastian Kleineidam for the Debian distribution of roundup. The main author of roundup is Richard Jones . code-d30e534b078a/share/man/man1/roundup-demo.10000644000000000000000000000643214511366522017070 0ustar 00000000000000.TH ROUNDUP-SERVER 1 "27 July 2004" .SH NAME roundup-demo \- create a roundup "demo" tracker and launch its web interface .SH SYNOPSIS \fBroundup_demo\fP [\fB\-h\fP] [\fB-b\fP \fIBIND_ADDRESS\fP] [\fB-b\fP {\fBanydbm\fP,\fBmysql\fP,\fBsqlite\fP,\fBpostgresql\fP}] [\fB-t\fb {\fBminimal\fP,\fBjinja2\fP,\fBclassic\fP,\fBresponsive\fP,\fBdevel\fP}] [\fB-p\fP \fIPORT\fP] [\fB-P\fP \fIURLPORT\fP] [\fB-V\fP] [\fIdirectory\fP] [\fIbackend\fP] [\fBnuke\fP] .SH OPTIONS .TP \fIdirectory\fP The home directory for the new demo tracker. (*) .TP \fIbackend\fP Choose backend database. Depricated, use \fB-b\fP. .TP \fBnuke\fP Create a fresh demo tracker (deleting the existing one if any). E.G. .EX roundup-demo -b sqlite -t classic ./mytracker nuke .EE will remove an existing tracker (if present) from the directory \fB./mytracker\fP. Then it will create and serve a new empty classic tracker using the sqlite backend. .TP \fB-h\fP, \fB--help\fP Show the help message and exit .TP \fB-b\fp \fIBIND_ADDRESS\fI, \fB--bind_address\fP \fIBIND_ADDRESS\fP Choose address for server to listen at. Use 0.0.0.0 to bind to all addreses. Default: 127.0.0.1. .TP \fB-b\fP {\fBanydbm\fP,\fBmysql\fP,\fBsqlite\fP,\fBpostgresql\fP}, \ \fB--backend_db\fP {\fBanydbm\fP,\fBmysql\fP,\fBsqlite\fP,\fBpostgresql\fP} Choose backend database. Default: sqlite. Available backends are subject to availability on your system. .TP \fB-t\fP \ {\fBminimal\fP,\fBjinja2\fP,\fBclassic\fP,\fBresponsive\fP,\fBdevel\fP}, \ \fP--template\fB \ {\fBminimal\fP,\fBjinja2\fP,\fBclassic\fP,\fBresponsive\fP,\fBdevel\fP} Use specified template when building tracker. (*) .TP \fB-p\fP \fIPORT\fP, \fB--port\fP \fIPORT\fP Listen at this port. Default: search for open port starting at 8917. .TP \fB-P\fP \fIURLPORT\fP, \fB--urlport\fP \fIURLPORT\fP When using docker this option passes the docker external port to the demo instance. If using \fBdocker ... -p 9090:8917 ...\fP this should be set to \fB-P 9090\fP. Default: as selected by \fB--port\fP. .TP \fB-V\fP, \fB--version\fP Show program's version number and exit .PP If items marked with (*) are missing, they will be asked for interactively when setting up the tracker. .SH DESCRIPTION This command creates a fresh demo tracker for you to experiment with. The email features of Roundup will be turned off (so the nosy feature won't send email). It does this by removing the \fBnosyreaction.py\fP module from the demo tracker's \fIdetectors\fP directory. If you wish to send email to promote the trcker to production, you will need to copy \fBnosyreaction.py\fP from the default tracker templates directory. The \fBtemplates\fP command from roundup-admin(1) can help you locate a replacement. If you wish, you may modify the demo tracker by editing its configuration files and HTML templates. See the \fIcustomisation\fP manual for information about how to do that. Once you've fiddled with the demo tracker, you may use it as a template for creating your real, live tracker. Simply run the \fIroundup-admin\fP command to install the tracker from inside the demo tracker home directory, and it will be listed as an available template for installation. No data will be copied over. .SH SEE ALSO .SH AUTHOR This manpage was written by Richard Jones and extensively modified by John Rouillard . code-d30e534b078a/share/man/man1/roundup-mailgw.10000644000000000000000000001513614511366522017425 0ustar 00000000000000>.TH ROUNDUP-MAILGW 1 "27 October 2022" .SH NAME roundup-mailgw \- mail gateway for roundup .SH SYNOPSIS \fBroundup-mailgw\fP [\fI-h|--help] [\fI-v\fP] [\fI--version\fP] [\fI-c|--default-class\fP \fIdefault_class\fP] [\fI-S|--set-value\fP \fI[class.]field=value\fP] [\fI-O|--oauth-directory\fP \fIdirectory\fP] [\fI-T|--oauth-token-endpoint\fP \fIendpoint-url\fP] [\fIinstance_home\fP] [\fImail source [specification]\fP] .SH OPTIONS .TP \fB-v\fP \fB--version\fP Print version and exit. .TP \fB-c\fP \fB--default-class\fP \fIhyperdb class\fP specify the default tracker class - one of issue (the default), msg, file, user etc. Overrides the tracker's mailgw \fIdefault_class\fP setting. .TP \fB-S\fP \fB--set-value\fP \fI[class.]property\fP\fB=\fP\fIvalue\fP[\fB;\fP\fIproperty\fP\fB=\fP\fIvalue\fP] specify the values to set on the class specified as prefix using the same format as the Subject line property manipulations. If the class prefix is left out it defaults to \fImsg\fP. Can also be specified with \fB--set-value\fP (and abbreviated to \fB--set\fP). .TP \fB-O\fP \fB--oauth-directory\fP \fIdirectory\fP Only with OAuth authentication specify the directory containing additional OAuth credentials. .TP \fB-T\fP \fB--oauth-token-endpoint\fP \fIurl\fP Token endpoint URL of your cloud provider, only used with OAuth. .SH DESCRIPTION The roundup mail gateway may be called in one of four ways: .IP \(bu without arguments which will use the env var ROUNDUP_INSTANCE, .IP \(bu with an \fIinstance_home\fP as the only argument, .IP \(bu with both an \fIinstance_home\fP and a mail spool file, or .IP \(bu with both an instance home and a mail source type and its specification. .PP \fBPIPE\fP .br If there is no mail source specified, the mail gateway reads a single message from the standard input and submits the message to the roundup.mailgw module. \fBUNIX mailbox\fP .br In this case, the gateway reads all messages from the UNIX mail spool file and submits each in turn to the roundup.mailgw module. The file is emptied once all messages have been successfully handled. The file is specified as: \fBmailbox\fP \fI/path/to/mailbox\fP In all of the following mail source types, the username and password can be stored in a ~/.netrc file. If done so, only the server name needs to be specified on the command-line. The username and/or password will be prompted for if not supplied on the command-line or in ~/.netrc. \fBPOP\fP .br For the mail source "pop", the gateway reads all messages from the POP server specified and submits each in turn to the roundup.mailgw module. The server is specified as: \fBpop\fP \fIusername\fP\fB:\fP\fIpassword\fP\fB@\fP\fIserver\fP .br The username and password may be omitted: \fBpop\fP \fIusername\fP\fB@\fP\fIserver\fP \fBpop\fP \fIserver\fP .br are both valid. \fBPOPS\fP .br Connect to the POP server over ssl/tls. This supports the same notation as POP. \fBAPOP\fP .br Same as POP, but using Authenticated POP: \fBapop\fP \fIusername\fP\fB:\fP\fIpassword\fP\fB@\fP\fIserver\fP \fBIMAP\fP .br Connect to an IMAP server. This supports the same notation as that of POP mail. \fBimap\fP \fIusername\fP\fB:\fP\fIpassword\fP\fB@\fP\fIserver\fP .br It also allows you to specify a specific mailbox other than INBOX using this format: \fBimap\fP \fIusername\fP\fB:\fP\fIpassword\fP\fB@\fP\fIserver mailbox\fP \fBIMAPS\fP .br Connect to an IMAP server over ssl/tls. This supports the same notation as IMAP. \fBimaps\fP \fIusername\fP\fB:\fP\fIpassword\fP\fB@\fP\fIserver\fP [\fImailbox\fP] \fBIMAPS_CRAM\fP .br Connect to an IMAP server over ssl/tls using CRAM-MD5 authentication. This supports the same notation as IMAP. \fBimaps_cram\fP \fIusername\fP\fB:\fP\fIpassword\fP\fB@\fP\fIserver\fP [\fImailbox\fP] \fBIMAPS_OAUTH\fP .br Connect to an IMAP server over ssl/tls using OAUTH authentication. Note that this does not support a password in imaps URLs. Instead it uses only the user and server and a command-line option for the directory with the files \fBaccess_token\fP, \fBrefresh_token\fP, \fBclient_secret\fP, and \fBclient_id\fP. By default this directory is \fBoauth\fP in your tracker home directory. The access token is tried first and, if expired, the refresh token together with the client secret is used to retrieve a new access token. Note that both token files need to be \fIwriteable\fP, the access token is continuously replaced and some cloud providers may also renew the refresh token from time to time: \fBimaps_oauth\fP \fIusername\fP\fB@\fP\fIserver\fP [\fImailbox\fP] .br The refresh and access tokens (the latter can be left empty), the client id and the client secret need to be retrieved via cloud provider specific protocols or websites. .SH ENVIRONMENT VARIABLES \fBROUNDUP_INSTANCE\fP .br This can be used to set the instance directory. If it is set, the \fIinstance_home\fP argument is optional. .SH EXAMPLE If your msg class has a messsagetype property you can set up aliases to receive the different types of messages. Setting up an alias in your MTA Using: tracker: |/tools/roundup/bin/roundup-mailgw -S "msg.messagetype=reply - to all" /var/roundup/sysadmin (the lines are split for readability. In the alias file they will be on the same line). Replace /tools/roundup/bin/roundup-mailgw by your path to the roundup-mailgw. This creates the email alias "tracker". All messages sent to it have their messagetype property set to "reply - to all". The roundup tracker instance is located at /var/roundup/sysadmin. A comment alias would receive emails at tracker_comment with: tracker_comment: |/tools/roundup/bin/roundup-mailgw -S "msg.messagetype=to tech" /var/roundup/sysadmin which would be a technical message. These messages can trigger different workflows based on the messagetype. Both examples use the default class specified in the tracker's config.ini (usually the issue class). You can also set properties directly on the issue class. If your tracker's issue has a "private" property that limits who can view an issue and its messages: security: |/tools/roundup/bin/roundup-mailgw -S "issue.private=true" -S "issue.keyword+=security" /var/roundup/sysadmin would set the private property on a issue to restrict visiblity and mark the issue as a security topic using a keyword. Both examples use the default class specified in the tracker's config.ini (usually the issue class). .SH AUTHOR This manpage was written by Bastian Kleineidam for the Debian distribution of roundup. The main author of roundup is Richard Jones . Updates by John Rouillard and Ralf Schlatterbeck . code-d30e534b078a/share/man/man1/roundup-server.10000644000000000000000000001042514511366522017447 0ustar 00000000000000.TH ROUNDUP-SERVER 1 "27 July 2004" .SH NAME roundup-server \- start roundup web server .SH SYNOPSIS \fBroundup-server\fP [\fIoptions\fP] [\fBname=\fP\fItracker home\fP]* .SH OPTIONS .TP \fB-C\fP \fIfile\fP or \fB--config\fP \fIfile\fP Use options read from the configuration file (see below). .TP \fB-n\fP \fIhostname\fP Sets the host name or IP address to listen on. Default is localhost (127.0.0.1). Use 0.0.0.0 to listen on all interfaces on the system. .TP \fB-p\fP \fIport\fP Sets the port to listen on (default: 8080). .TP \fB-d\fP \fIPIDfile\fP Run the server in the background and write the server's PID to the file indicated by PIDfile. The -l (or -L) option \fBmust\fP be specified if -d is used. .TP \fB-t\fP \fBfork|thread|debug|none\fP Control multi-process mode. \fBdebug\fP and \fBnone\fP are always available. If an invalid mode is specified the server starts in \fBnone\fP (also called single) mode. Default fork. .TP \fB-m\fP \fImax_children\fP Set the maximum number of child processes (servers). This value may need to be increased on a heavily loaded site. Default 40. .TP \fB-l\fP \fIfile\fP Sets a filename to log to (instead of stdout). This is required if the -d option is used. .TP \fB-L\fP Have the server log using the Python logger with key roundup.http. .TP \fB-i\fP \fIfile\fP Sets a filename to use as a template for generating the tracker index page. The variable "trackers" is available to the template and is a dict of all configured trackers. .TP \fB-I\fP \fIheader1[,header2,...]\fP Pass the header(s) and their values to the backend. This allow-list of header variables can be used by custom code in the tracker or with a tracker's \fBhttp_auth_header\fP configuration option to allows a front end server to authenticate a user and pass the user identity to roundup. .TP \fB-s\fP Enables use of SSL. In most cases, you will want to run a real web server (Apache, Nginx) as a proxy to roundup-server running without SSL. The real web server can filter/rate limit/firewall requests to roundup-server. .TP \fB-e\fP \fIfile\fP Sets a filename containing the PEM file to use for SSL. The PEM file must include both the private key and certificate with appropriate headers (e.g. "-----BEGIN PRIVATE KEY-----", "-----END PRIVATE KEY-----" and "-----BEGIN CERTIFICATE-----", "-----END CERTIFICATE-----". If no file is specified, a temporary self-signed certificate will be used. .TP \fB-N\fP Log client machine names instead of IP addresses (much slower). .TP \fB-V\fP \fIHTTPVER\fP By default roundup-server uses HTTP/1.1 to enable keepalives for faster response. HTTPVER can be set to \fBHTTP/1.0\fP to disable keepalives. .TP \fB-u\fP \fIUID\fP Runs the Roundup web server as this UID. .TP \fB-g\fP \fIGID\fP Runs the Roundup web server as this GID. .TP \fB-v\fP or \fB--version\fP Print version and exit. .TP \fB-h\fP or \fB--help\fP Print help and exit. .TP \fB--save-config\fP Create configuration file and exit. The old config.ini will be saved to config.bak. Note that this command doesn't attempt to load or verify an existing config.ini. Running this in a tracker home directory will move the existing config.ini to config.bak and replace it with the roundup-server's config.ini. This will make the tracker in the directory fail to start until the original config.ini is restored. .TP \fBname=\fP\fItracker home\fP Sets the tracker home(s) to use. The \fBname\fP variable is how the tracker is identified in the URL (it's the first part of the URL path). The \fItracker home\fP variable is the directory that was identified when you did "roundup-admin init". You may specify any number of these name=home pairs on the command-line. For convenience, you may edit the TRACKER_HOMES variable in the roundup-server file instead. Make sure the name part doesn't include any url-unsafe characters like spaces, as these confuse the cookie handling in browsers like IE. .SH EXAMPLES .TP .B roundup-server -p 9000 bugs=/var/tracker reqs=/home/roundup/group1 Start the server on port \fB9000\fP serving two trackers; one under \fB/bugs\fP and one under \fB/reqs\fP. .SH CONFIGURATION FILE See the "admin_guide" in the Roundup "doc" directory. .SH AUTHOR This manpage was written by Bastian Kleineidam for the Debian distribution of roundup. The main author of roundup is Richard Jones .