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 --listen HOST:PORT:ssl
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.
For TCP sockets you can append
:ssl
after the port to specify that connections on that port should use SSL. Note that the SSL support is experimental and hasn't been widely tested.Defaults to any IP address and port 5000.
- --host
-
--host 127.0.0.1
Specifies the address to bind.
This option is for a compatibility with plackup and you're recommended to use
--listen
instead. - --port
-
--port 8080
Specifies the port to bind.
This option is for a compatibility 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 compatibility 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 inplackup -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
. - --ssl-cert
-
Specify the path to SSL certificate file.
- --ssl-key
-
Specify the path to SSL key file.
- --enable-ssl
-
Enable SSL on all TCP sockets. This is an experimental feature.
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 running 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 sendQUIT
signal when superdaemon receivedHUP
, i.e:start_server --interval 5 --port 8080 --signal-on-hup=QUIT -- \ starman --preload-app myapp.psgi
You will then send the HUP signal to
start_server
process to gracefully reload the starman cluster (master and workers).With Server::Starter 0.12 or later, you should also be able to set
--signal-on-term
to QUIT so that you can safely shutdown Starman first and then stop thestart_server
daemon process as well. - TTIN, TTOU
-
Sending
TTIN
signal to the master process will dynamically increase the number of workers, andTTOU
signal will decrease it. - INT, TERM
-
Sending
INT
orTERM
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).
RELOADING THE APPLICATION
You're recommended to use signals (see above) to reload the application, and are strongly discouraged to use -r
or -R
(reloading flag) from plackup. These options will make a separate directory watcher process, and makes your life difficult if you want to combine with other process daemon tools such as Server::Starter.
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 compatibility.