Mercurial > p > roundup > code

annotate share/man/man1/roundup-server.1 @ 6834:5129fc03dc1f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
issue2551137, 2551138 - roundup-server SSL issues. Python3 no longer supports socket._fileobject, so fake it using SocketIO and layering io.BufferedReader as in: https://bugs.launchpad.net/python-glanceclient/+bug/1812525 Also handle SSL.ZeroReturnError exception by ignoring it. This exception is thrown when the SSL layer has been closed and a read happens. There is a warning in openssl as well as python docs that the underlying (unencrypted) socket may not be closed. In manual testing, netstat -anp didn't show any unclosed socket so.... Could it leak a fd still, unknown. This also seesm to have fixed an error when running under python2 where socket shutdown throws an error. Maybe ignoring ZeroErrorREturn handled that case? Also added doc to man page recommending not using -s and using a real web server instead. Also added doc on format of pem file passed to -e. No automated testing on this, so no test updates 8-(.
author John Rouillard <rouilj@ieee.org>
date Thu, 18 Aug 2022 14:44:16 -0400
parents da9a78957bd4
children 7a48f771cd4f
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
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
28 \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
29 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
30 option is used.
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
31 .TP
5969
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
32 \fB-L\fP
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
33 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
34 .TP
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
35 \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
36 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
37 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
38 configured trackers.
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
39 .TP
6514
a036712c96f4 Enable HTTP/1.1 support for roundup-server
John Rouillard <rouilj@ieee.org>
parents: 5969
diff changeset
40 \fB-I\fP \fIheader1[,header2,...]\fP
a036712c96f4 Enable HTTP/1.1 support for roundup-server
John Rouillard <rouilj@ieee.org>
parents: 5969
diff changeset
41 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
42 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
43 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
44 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
45 roundup.
a036712c96f4 Enable HTTP/1.1 support for roundup-server
John Rouillard <rouilj@ieee.org>
parents: 5969
diff changeset
46 .TP
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
47 \fB-s\fP
6834
5129fc03dc1f issue2551137, 2551138 - roundup-server SSL issues.
John Rouillard <rouilj@ieee.org>
parents: 6833
diff changeset
48 Enables use of SSL. SSL only works when running the server using
5129fc03dc1f issue2551137, 2551138 - roundup-server SSL issues.
John Rouillard <rouilj@ieee.org>
parents: 6833
diff changeset
49 python 3. In most cases, you will want to run a real web server
5129fc03dc1f issue2551137, 2551138 - roundup-server SSL issues.
John Rouillard <rouilj@ieee.org>
parents: 6833
diff changeset
50 (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
51 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
52 roundup-server.
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
53 .TP
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
54 \fB-e\fP \fIfile\fP
6834
5129fc03dc1f issue2551137, 2551138 - roundup-server SSL issues.
John Rouillard <rouilj@ieee.org>
parents: 6833
diff changeset
55 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
56 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
57 headers (e.g. "-----BEGIN PRIVATE KEY-----", "-----END PRIVATE
5129fc03dc1f issue2551137, 2551138 - roundup-server SSL issues.
John Rouillard <rouilj@ieee.org>
parents: 6833
diff changeset
58 KEY-----" and "-----BEGIN CERTIFICATE-----", "-----END
5129fc03dc1f issue2551137, 2551138 - roundup-server SSL issues.
John Rouillard <rouilj@ieee.org>
parents: 6833
diff changeset
59 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
60 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
61 .TP
4706
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
62 \fB-N\fP
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
63 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
64 .TP
6514
a036712c96f4 Enable HTTP/1.1 support for roundup-server
John Rouillard <rouilj@ieee.org>
parents: 5969
diff changeset
65 \fB-V\fP \fIHTTPVER\fP
a036712c96f4 Enable HTTP/1.1 support for roundup-server
John Rouillard <rouilj@ieee.org>
parents: 5969
diff changeset
66 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
67 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
68 .TP
4706
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
69 \fB-u\fP \fIUID\fP
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
70 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
71 .TP
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
72 \fB-g\fP \fIGID\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 GID.
a5a9b81f8f6b issue2550760: Several improvements to the manpages (thanks Kai Storbeck)
John Kristensen <john@jerrykan.com>
parents: 4096
diff changeset
74 .TP
5969
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
75 \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
76 Print version and exit.
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-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
79 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
80 .TP
5969
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
81 \fB--save-config\fP
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
82 Create or update configuration file and exit.
247f176f9020 issue2550885 - man page documentation roundup-server.1
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
83 .TP
4096
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
84 \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
85 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
86 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
87 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
88 "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
89 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
90 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
91 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
92 browsers like IE.
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
93 .SH EXAMPLES
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
94 .TP
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
95 .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
96 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
97 \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
98
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
99 .SH CONFIGURATION FILE
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
100 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
101 .SH AUTHOR
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
102 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
103 <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
104
ab542607f2fb Move man pages into 'share/man/man1' and simplify setup.py
Stefan Seefeld <stefan@seefeld.name>
parents:
diff changeset
105 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
106 <richard@users.sourceforge.net>.
Roundup Issue Tracker: http://roundup-tracker.org/