.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "STARMAN 1p"
.TH STARMAN 1p "2012-05-18" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
starman \- Starman launcher
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  starman \-\-listen :5001 \-\-listen /tmp/starman.sock
\&  starman \-\-workers 32 \-\-port 8080
.Ve
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\-l, \-\-listen" 4
.IX Item "-l, --listen"
.Vb 1
\&  \-\-listen HOST:PORT \-\-listen :PORT \-\-listen UNIX_SOCKET
.Ve
.Sp
Specifies the \s-1TCP\s0 address, ports and \s-1UNIX\s0 domain sockets to bind to
wait for requests. You can repeat as many times as you want and mix
\&\s-1TCP\s0 and \s-1UNIX\s0 domain sockets.
.Sp
Defaults to any \s-1IP\s0 address and port 5000.
.IP "\-\-host" 4
.IX Item "--host"
.Vb 1
\&  \-\-host 127.0.0.1
.Ve
.Sp
Specifies the address to bind.
.Sp
This option is for a compatiblity with plackup and you're
recommended to use \f(CW\*(C`\-\-listen\*(C'\fR instead.
.IP "\-\-port" 4
.IX Item "--port"
.Vb 1
\&  \-\-port 8080
.Ve
.Sp
Specifies the port to bind.
.Sp
This option is for a compatiblity with plackup and you're
recommended to use \f(CW\*(C`\-\-listen\*(C'\fR instead.
.IP "\-S, \-\-socket" 4
.IX Item "-S, --socket"
.Vb 1
\&  \-S /tmp/starman.sock
.Ve
.Sp
Specifies the path to \s-1UNIX\s0 domain socket to bind.
.Sp
This option is for a compatiblity with plackup and you're
recommended to use \f(CW\*(C`\-\-listen\*(C'\fR instead.
.IP "\-\-workers" 4
.IX Item "--workers"
Specifies the number of worker pool. Defaults to 5.
.Sp
Starman by default sets up other spare server configuration based on this
workers value, making sure there are \fBalways only\fR \f(CW\*(C`N\*(C'\fR worker
processes running. So even if there're no idle workers, Starman won't
spawn off spare processes since that's mostly what you want to do by
fine tuning the memory usage etc. in the production environment.
.IP "\-\-backlog" 4
.IX Item "--backlog"
Specifies the number of backlog (listen queue size) of listener sockets. Defaults to 1024.
.Sp
On production systems, setting a very low value can allow failover on
frontend proxy (like nginx) to happen more quickly, if you have
multiple Starman clusters.
.Sp
If you're doing simple benchmarks and getting connection errors,
increasing this parameter can help avoid them. You should also
consider increasing \f(CW\*(C`net.core.somaxconn\*(C'\fR. Note that this is not
recommended for real production system if you have another cluster to
failover (see above).
.IP "\-\-max\-requests" 4
.IX Item "--max-requests"
Number of the requests to process per one worker process. Defaults to 1000.
.IP "\-\-preload\-app" 4
.IX Item "--preload-app"
This option lets Starman preload the specified \s-1PSGI\s0 application in the
master parent process before preforking children. This allows memory
savings with copy-on-write memory management. When not set (default),
forked children loads the application in the initialization hook.
.Sp
Enabling this option can cause bad things happen when resources like
sockets or database connections are opened at load time by the master
process and shared by multiple children.
.Sp
Since Starman 0.2000, this option defaults to false, and you should
explicitly set this option to preload the application in the master
process.
.Sp
Alternatively, you can use \-M command line option (plackup's common
option) to preload the \fImodules\fR rather than the <application>
itself.
.Sp
.Vb 1
\&  starman \-MCatalyst \-MDBIx::Class myapp.psgi
.Ve
.Sp
will load the modules in the master process for memory savings with
CoW, but the actual loading of \f(CW\*(C`myapp.psgi\*(C'\fR is done per children,
allowing resource managements such as database connection safer.
.Sp
If you enable this option, sending \f(CW\*(C`HUP\*(C'\fR signal to the master process
\&\fIwill not\fR pick up any code changes you make. See \*(L"\s-1SIGNALS\s0\*(R" for
details.
.IP "\-\-disable\-keepalive" 4
.IX Item "--disable-keepalive"
Disable Keep-alive persistent connections. It is an useful workaround
if you run Starman behind a broken frontend proxy that tries to pool
connections more than a number of backend workers (i.e. Apache
mpm_prefork + mod_proxy).
.IP "\-\-keepalive\-timeout" 4
.IX Item "--keepalive-timeout"
The number of seconds Starman will wait for a subsequent request
before closing the connection if Keep-alive persistent connections
are enabled. Setting this to a high value may cause performance
problems in heavily loaded servers. The higher the timeout, the
more backend workers will be kept occupied waiting on connections
with idle clients.
.Sp
Defaults to 1.
.IP "\-\-user" 4
.IX Item "--user"
To listen on a low-numbered (<1024) port, it will be necessary to
start the server as root. Use the \f(CW\*(C`\-\-user\*(C'\fR option to specify a userid
or username that the server process should switch to after binding to
the port.
.Sp
Defaults to the current userid.
.IP "\-\-group" 4
.IX Item "--group"
Specify the group id or group name that the server should switch to after
binding to the port.  This option is usually used with \f(CW\*(C`\-\-user\*(C'\fR.
.Sp
Defaults to the current group id.
.IP "\-\-pid" 4
.IX Item "--pid"
Specify the pid file path. Use it with \f(CW\*(C`\-D|\-\-daemonize\*(C'\fR option,
described in \f(CW\*(C`plackup \-h\*(C'\fR.
.IP "\-\-error\-log" 4
.IX Item "--error-log"
Specify the pathname of a file where the error log should be written.
This enables you to still have access to the errors when using \f(CW\*(C`\-\-daemonize\*(C'\fR.
.PP
Starman passes through other options given to Plack::Runner, the
common backend that plackup uses, so the most options explained in
\&\f(CW\*(C`plackup \-h\*(C'\fR such as \f(CW\*(C`\-\-access\-log\*(C'\fR or \f(CW\*(C`\-\-daemonize\*(C'\fR works fine in
starman too.
.PP
Setting the environment variable \f(CW\*(C`STARMAN_DEBUG\*(C'\fR to 1 makes the
Starman server runninng in the debug mode.
.SH "SIGNALS"
.IX Header "SIGNALS"
.IP "\s-1HUP\s0" 4
.IX Item "HUP"
Sending \f(CW\*(C`HUP\*(C'\fR signal to the master process will restart all the workers
gracefully (meaning the currently running requests will shut down once
the request is complete), and by default, the workers will pick up the
code changes you make by reloading the application.
.Sp
If you enable \f(CW\*(C`\-\-preload\-app\*(C'\fR option, however, the code will be only
loaded in the startup process and will not pick up the code changes
you made. If you want to preload the app \fIand\fR do graceful restarts
by reloading the code changes, you're recommended to use
Server::Starter, configured to send \f(CW\*(C`QUIT\*(C'\fR signal when superdaemon
received \f(CW\*(C`HUP\*(C'\fR, i.e:
.Sp
.Vb 1
\&    start_server \-\-port 8080 \-\-signal\-on\-hup=QUIT \-\- starman \-\-preload\-app myapp.psgi
.Ve
.IP "\s-1TTIN\s0, \s-1TTOU\s0" 4
.IX Item "TTIN, TTOU"
Sending \f(CW\*(C`TTIN\*(C'\fR signal to the master process will dynamically increase
the number of workers, and \f(CW\*(C`TTOU\*(C'\fR signal will decrease it.
.IP "\s-1INT\s0, \s-1TERM\s0" 4
.IX Item "INT, TERM"
Sending \f(CW\*(C`INT\*(C'\fR or \f(CW\*(C`TERM\*(C'\fR signal to the master process will kill all
the workers immediately and shut down the server.
.IP "\s-1QUIT\s0" 4
.IX Item "QUIT"
Sending \f(CW\*(C`QUIT\*(C'\fR signal to the master process will gracefully shutdown
the workers (meaning the currently running requests will shut down
once the request is complete).
.SH "DIFFERENCES WITH PLACKUP"
.IX Header "DIFFERENCES WITH PLACKUP"
\&\f(CW\*(C`starman\*(C'\fR executable is basically the equivalent of using \f(CW\*(C`plackup\*(C'\fR
with \f(CW\*(C`Starman\*(C'\fR server handler i.e. \f(CW\*(C`plackup \-s Starman\*(C'\fR, except that
\&\f(CW\*(C`starman\*(C'\fR delay loads the application with the Delayed loader by
default, which can be disabled with \f(CW\*(C`\-\-preload\-app\*(C'\fR.
.PP
\&\f(CW\*(C`starman\*(C'\fR command also automatically sets the environment (\f(CW\*(C`\-E\*(C'\fR) to
the value of \fIdeployment\fR.
.PP
You're recommended to use \f(CW\*(C`starman\*(C'\fR unless there's a reason to stick to
\&\f(CW\*(C`plackup\*(C'\fR for compatiblity.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Starman