.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.3.
.TH PORTSERVER.PY "1" "July 2021" "portserver.py 1.5.0~b1" "User Commands"
.SH NAME
portserver.py \- server to hand out unused port numbers
.SH DESCRIPTION
usage: portserver.py [\-h] [\-\-portserver_static_pool PORTSERVER_STATIC_POOL]
.TP
[\-\-portserver_address PORTSERVER_ADDRESS] [\-\-verbose]
[\-\-debug]
.SS "optional arguments:"
.TP
\fB\-h\fR, \fB\-\-help\fR
show this help message and exit
.TP
\fB\-\-portserver_static_pool\fR PORTSERVER_STATIC_POOL
Comma separated N\-P Range(s) of ports to manage
(inclusive).
.TP
\fB\-\-portserver_address\fR PORTSERVER_ADDRESS, \fB\-\-portserver_unix_socket_address\fR PORTSERVER_ADDRESS
Address of AF_UNIX socket on which to listen on Unix
(first @ is a NUL) or the name of the pipe on Windows
(first @ is the \e\e.\epipe\e prefix).
.TP
\fB\-\-verbose\fR
Enable verbose messages.
.TP
\fB\-\-debug\fR
Enable full debug messages.
.SH "PORT SERVER"
A port server is intended to be run as a daemon, for use by all processes
running on the host. It coordinates uses of network ports by anything using a
portpicker library. If you are using hosts as part of a test automation
cluster, each one should run a port server as a daemon. You should set the
PORTSERVER_ADDRESS=@unittest-portserver environment variable on all of your
test runners so that portpicker makes use of it.

A port server listens on a unix socket, reads a pid from a new connection,
tests the ports it is managing and replies with a port assignment port for
that pid. A port is only reclaimed for potential reassignment to another
process after the process it was originally assigned to has died. Processes
that need multiple ports can simply issue multiple requests and are guaranteed
they will each be unique.
.SH "TYPICAL USAGE"
                                                                                
 1) Run one instance of this process on each of your unittest farm hosts.       
 2) Set the PORTSERVER_ADDRESS environment variable in your test runner         
    environment to let the portpicker library know to use a port server         
    rather than attempt to find ports on its own.                               
                                                                                
 $ /path/to/portserver.py &                                                      
 $ export PORTSERVER_ADDRESS=@unittest-portserver                                
 $ # ... launch a bunch of unittest runners using portpicker ...