Mercurial > p > roundup > code

annotate share/man/man1/roundup-server.1 @ 7458:fe16ff1bede5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add extra explanation for SQL command in 1.3.3->1.4.0 upgrade path A user on IRC was confused as to where/how to add indexes. Try to clarify.
author John Rouillard <rouilj@ieee.org>
date Wed, 07 Jun 2023 10:32:21 -0400
parents 46f92ac4e170
children d614d8e1c09d
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
1 .TH ROUNDUP-SERVER 1 "27 July 2004"
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-server \- start roundup web server
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
4 .SH SYNOPSIS
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
5 \fBroundup-server\fP [\fIoptions\fP] [\fBname=\fP\fItracker home\fP]*
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
6 .SH OPTIONS
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
7 .TP
5969
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
8 \fB-C\fP \fIfile\fP or \fB--config\fP \fIfile\fP
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
9 Use options read from the configuration file (see below).
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
10 .TP
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
11 \fB-n\fP \fIhostname\fP
5138
c54720396f40 issue2550882. Reported by Karl-Philipp Richter. Fixed
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
12 Sets the host name or IP address to listen on. Default is localhost
c54720396f40 issue2550882. Reported by Karl-Philipp Richter. Fixed
John Rouillard <rouilj@ieee.org>
parents: 4706
diff changeset
13 (127.0.0.1). Use 0.0.0.0 to listen on all interfaces on the system.
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
14 .TP
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
15 \fB-p\fP \fIport\fP
4706
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
16 Sets the port to listen on (default: 8080).
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
17 .TP
5969
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
18 \fB-d\fP \fIPIDfile\fP
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
19 Run the server in the background and write the server's PID to the
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
20 file indicated by PIDfile. The -l (or -L) option \fBmust\fP be
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
21 specified if -d is used.
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
22 .TP
6830
36cf8a12a26b add thread option to roundup-server.1 man page.
John Rouillard <rouilj@ieee.org>
parents: 6514
diff changeset
23 \fB-t\fP \fBfork|thread|debug|none\fP
6831
e0b29e3fe995 Expand on explanation for multiprocess-mode in roundup-server.1.
John Rouillard <rouilj@ieee.org>
parents: 6830
diff changeset
24 Control multi-process mode. \fBdebug\fP and \fBnone\fP are always
6833
da9a78957bd4 Fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 6831
diff changeset
25 available. If an invalid mode is specified the server starts in
6831
e0b29e3fe995 Expand on explanation for multiprocess-mode in roundup-server.1.
John Rouillard <rouilj@ieee.org>
parents: 6830
diff changeset
26 \fBnone\fP (also called single) mode. Default fork.
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
27 .TP
7387
46f92ac4e170 - issue2551275 - Allow configuring max_children in roundup-server.
John Rouillard <rouilj@ieee.org>
parents: 7335
diff changeset
28 \fB-m\fP \fImax_children\fP
46f92ac4e170 - issue2551275 - Allow configuring max_children in roundup-server.
John Rouillard <rouilj@ieee.org>
parents: 7335
diff changeset
29 Set the maximum number of child processes (servers). This value
46f92ac4e170 - issue2551275 - Allow configuring max_children in roundup-server.
John Rouillard <rouilj@ieee.org>
parents: 7335
diff changeset
30 may need to be increased on a heavily loaded site. Default 40.
46f92ac4e170 - issue2551275 - Allow configuring max_children in roundup-server.
John Rouillard <rouilj@ieee.org>
parents: 7335
diff changeset
31 .TP
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
32 \fB-l\fP \fIfile\fP
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
33 Sets a filename to log to (instead of stdout). This is required if the -d
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
34 option is used.
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
35 .TP
5969
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
36 \fB-L\fP
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
37 Have the server log using the Python logger with key roundup.http.
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
38 .TP
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
39 \fB-i\fP \fIfile\fP
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
40 Sets a filename to use as a template for generating the tracker index page.
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
41 The variable "trackers" is available to the template and is a dict of all
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
42 configured trackers.
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
43 .TP
6514
a036712c96f4 Enable HTTP/1.1 support for roundup-server
John Rouillard <rouilj@ieee.org>
parents: 5969
diff changeset
44 \fB-I\fP \fIheader1[,header2,...]\fP
a036712c96f4 Enable HTTP/1.1 support for roundup-server
John Rouillard <rouilj@ieee.org>
parents: 5969
diff changeset
45 Pass the header(s) and their values to the backend. This allow-list
a036712c96f4 Enable HTTP/1.1 support for roundup-server
John Rouillard <rouilj@ieee.org>
parents: 5969
diff changeset
46 of header variables can be used by custom code in the tracker or with
a036712c96f4 Enable HTTP/1.1 support for roundup-server
John Rouillard <rouilj@ieee.org>
parents: 5969
diff changeset
47 a tracker's \fBhttp_auth_header\fP configuration option to allows a
a036712c96f4 Enable HTTP/1.1 support for roundup-server
John Rouillard <rouilj@ieee.org>
parents: 5969
diff changeset
48 front end server to authenticate a user and pass the user identity to
a036712c96f4 Enable HTTP/1.1 support for roundup-server
John Rouillard <rouilj@ieee.org>
parents: 5969
diff changeset
49 roundup.
a036712c96f4 Enable HTTP/1.1 support for roundup-server
John Rouillard <rouilj@ieee.org>
parents: 5969
diff changeset
50 .TP
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
51 \fB-s\fP
6835
7a48f771cd4f Clean up docs on roundup-sever SSL use.
John Rouillard <rouilj@ieee.org>
parents: 6834
diff changeset
52 Enables use of SSL. In most cases, you will want to run a real web server
6834
5129fc03dc1f issue2551137, 2551138 - roundup-server SSL issues.
John Rouillard <rouilj@ieee.org>
parents: 6833
diff changeset
53 (Apache, Nginx) as a proxy to roundup-server running without SSL.
5129fc03dc1f issue2551137, 2551138 - roundup-server SSL issues.
John Rouillard <rouilj@ieee.org>
parents: 6833
diff changeset
54 The real web server can filter/rate limit/firewall requests to
5129fc03dc1f issue2551137, 2551138 - roundup-server SSL issues.
John Rouillard <rouilj@ieee.org>
parents: 6833
diff changeset
55 roundup-server.
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
56 .TP
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
57 \fB-e\fP \fIfile\fP
6834
5129fc03dc1f issue2551137, 2551138 - roundup-server SSL issues.
John Rouillard <rouilj@ieee.org>
parents: 6833
diff changeset
58 Sets a filename containing the PEM file to use for SSL. The PEM file
5129fc03dc1f issue2551137, 2551138 - roundup-server SSL issues.
John Rouillard <rouilj@ieee.org>
parents: 6833
diff changeset
59 must include both the private key and certificate with appropriate
5129fc03dc1f issue2551137, 2551138 - roundup-server SSL issues.
John Rouillard <rouilj@ieee.org>
parents: 6833
diff changeset
60 headers (e.g. "-----BEGIN PRIVATE KEY-----", "-----END PRIVATE
5129fc03dc1f issue2551137, 2551138 - roundup-server SSL issues.
John Rouillard <rouilj@ieee.org>
parents: 6833
diff changeset
61 KEY-----" and "-----BEGIN CERTIFICATE-----", "-----END
5129fc03dc1f issue2551137, 2551138 - roundup-server SSL issues.
John Rouillard <rouilj@ieee.org>
parents: 6833
diff changeset
62 CERTIFICATE-----". If no file is specified, a temporary self-signed
5129fc03dc1f issue2551137, 2551138 - roundup-server SSL issues.
John Rouillard <rouilj@ieee.org>
parents: 6833
diff changeset
63 certificate will be used.
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
64 .TP
4706
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
65 \fB-N\fP
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
66 Log client machine names instead of IP addresses (much slower).
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
67 .TP
6514
a036712c96f4 Enable HTTP/1.1 support for roundup-server
John Rouillard <rouilj@ieee.org>
parents: 5969
diff changeset
68 \fB-V\fP \fIHTTPVER\fP
a036712c96f4 Enable HTTP/1.1 support for roundup-server
John Rouillard <rouilj@ieee.org>
parents: 5969
diff changeset
69 By default roundup-server uses HTTP/1.1 to enable keepalives for faster
a036712c96f4 Enable HTTP/1.1 support for roundup-server
John Rouillard <rouilj@ieee.org>
parents: 5969
diff changeset
70 response. HTTPVER can be set to \fBHTTP/1.0\fP to disable keepalives.
a036712c96f4 Enable HTTP/1.1 support for roundup-server
John Rouillard <rouilj@ieee.org>
parents: 5969
diff changeset
71 .TP
4706
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
72 \fB-u\fP \fIUID\fP
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
73 Runs the Roundup web server as this UID.
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
74 .TP
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
75 \fB-g\fP \fIGID\fP
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
76 Runs the Roundup web server as this GID.
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
77 .TP
5969
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
78 \fB-v\fP or \fB--version\fP
4706
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
79 Print version and exit.
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
80 .TP
5969
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
81 \fB-h\fP or \fB--help\fP
4706
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
82 Print help and exit.
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
83 .TP
5969
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
84 \fB--save-config\fP
7335
b84718ea4228 document result of running save-config in a tracker home directory
John Rouillard <rouilj@ieee.org>
parents: 6835
diff changeset
85 Create configuration file and exit. The old config.ini will be saved to
b84718ea4228 document result of running save-config in a tracker home directory
John Rouillard <rouilj@ieee.org>
parents: 6835
diff changeset
86 config.bak. Note that this command doesn't attempt to load or verify
b84718ea4228 document result of running save-config in a tracker home directory
John Rouillard <rouilj@ieee.org>
parents: 6835
diff changeset
87 an existing config.ini. Running this in a tracker home directory will
b84718ea4228 document result of running save-config in a tracker home directory
John Rouillard <rouilj@ieee.org>
parents: 6835
diff changeset
88 move the existing config.ini to config.bak and replace it with the
b84718ea4228 document result of running save-config in a tracker home directory
John Rouillard <rouilj@ieee.org>
parents: 6835
diff changeset
89 roundup-server's config.ini. This will make the tracker in the
b84718ea4228 document result of running save-config in a tracker home directory
John Rouillard <rouilj@ieee.org>
parents: 6835
diff changeset
90 directory fail to start until the original config.ini is restored.
5969
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
91 .TP
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
92 \fBname=\fP\fItracker home\fP
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
93 Sets the tracker home(s) to use. The \fBname\fP variable is how the tracker is
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
94 identified in the URL (it's the first part of the URL path). The \fItracker
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
95 home\fP variable is the directory that was identified when you did
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
96 "roundup-admin init". You may specify any number of these name=home pairs on
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
97 the command-line. For convenience, you may edit the TRACKER_HOMES variable in
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
98 the roundup-server file instead. Make sure the name part doesn't include any
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
99 url-unsafe characters like spaces, as these confuse the cookie handling in
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
100 browsers like IE.
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
101 .SH EXAMPLES
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
102 .TP
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
103 .B roundup-server -p 9000 bugs=/var/tracker reqs=/home/roundup/group1
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
104 Start the server on port \fB9000\fP serving two trackers; one under
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
105 \fB/bugs\fP and one under \fB/reqs\fP.
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
106
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
107 .SH CONFIGURATION FILE
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
108 See the "admin_guide" in the Roundup "doc" directory.
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
109 .SH AUTHOR
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
110 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
111 <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
112
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
113 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
114 <richard@users.sourceforge.net>.
Roundup Issue Tracker: http://roundup-tracker.org/