NAME¶
starman - Starman launcher
SYNOPSIS¶
starman --listen :5001 --listen /tmp/starman.sock
starman --workers 32 --port 8080
OPTIONS¶
- -l, --listen
-
--listen HOST:PORT --listen :PORT --listen UNIX_SOCKET
Specifies the TCP address, ports and UNIX domain sockets to bind to wait for
requests. You can repeat as many times as you want and mix TCP and UNIX
domain sockets.
Defaults to any IP address and port 5000.
- --host
-
--host 127.0.0.1
Specifies the address to bind.
This option is for a compatiblity with plackup and you're recommended to use
"--listen" instead.
- --port
-
--port 8080
Specifies the port to bind.
This option is for a compatiblity with plackup and you're recommended to use
"--listen" instead.
- -S, --socket
-
-S /tmp/starman.sock
Specifies the path to UNIX domain socket to bind.
This option is for a compatiblity with plackup and you're recommended to use
"--listen" instead.
- --workers
- Specifies the number of worker pool. Defaults to 5.
Starman by default sets up other spare server configuration based on this
workers value, making sure there are always only "N"
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.
- --backlog
- Specifies the number of backlog (listen queue size) of
listener sockets. Defaults to 1024.
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.
If you're doing simple benchmarks and getting connection errors, increasing
this parameter can help avoid them. You should also consider increasing
"net.core.somaxconn". Note that this is not recommended for real
production system if you have another cluster to failover (see
above).
- --max-requests
- Number of the requests to process per one worker process.
Defaults to 1000.
- --preload-app
- This option lets Starman preload the specified PSGI
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.
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.
Since Starman 0.2000, this option defaults to false, and you should
explicitly set this option to preload the application in the master
process.
Alternatively, you can use -M command line option (plackup's common option)
to preload the modules rather than the <application> itself.
starman -MCatalyst -MDBIx::Class myapp.psgi
will load the modules in the master process for memory savings with CoW, but
the actual loading of "myapp.psgi" is done per children,
allowing resource managements such as database connection safer.
If you enable this option, sending "HUP" signal to the master
process will not pick up any code changes you make. See
"SIGNALS" for details.
- --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).
- --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.
Defaults to 1.
- --user
- To listen on a low-numbered (<1024) port, it will be
necessary to start the server as root. Use the "--user" option
to specify a userid or username that the server process should switch to
after binding to the port.
Defaults to the current userid.
- --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
"--user".
Defaults to the current group id.
- --pid
- Specify the pid file path. Use it with
"-D|--daemonize" option, described in "plackup
-h".
- --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
"--daemonize".
Starman passes through other options given to Plack::Runner, the common backend
that plackup uses, so the most options explained in "plackup -h"
such as "--access-log" or "--daemonize" works fine in
starman too.
Setting the environment variable "STARMAN_DEBUG" to 1 makes the
Starman server runninng in the debug mode.
SIGNALS¶
- HUP
- Sending "HUP" 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.
If you enable "--preload-app" 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 and do graceful restarts
by reloading the code changes, you're recommended to use Server::Starter,
configured to send "QUIT" signal when superdaemon received
"HUP", i.e:
start_server --port 8080 --signal-on-hup=QUIT -- starman --preload-app myapp.psgi
- TTIN, TTOU
- Sending "TTIN" signal to the master process will
dynamically increase the number of workers, and "TTOU" signal
will decrease it.
- INT, TERM
- Sending "INT" or "TERM" signal to the
master process will kill all the workers immediately and shut down the
server.
- QUIT
- Sending "QUIT" signal to the master process will
gracefully shutdown the workers (meaning the currently running requests
will shut down once the request is complete).
DIFFERENCES WITH PLACKUP¶
"starman" executable is basically the equivalent of using
"plackup" with "Starman" server handler i.e. "plackup
-s Starman", except that "starman" delay loads the application
with the Delayed loader by default, which can be disabled with
"--preload-app".
"starman" command also automatically sets the environment
("-E") to the value of
deployment.
You're recommended to use "starman" unless there's a reason to stick
to "plackup" for compatiblity.
SEE ALSO¶
Starman