Provided by: starman_0.4014-3_all bug

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.

       --read-timeout
           The number of seconds Starman will wait for a request on a new connection before
           closing it. 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. You may need this if your proxy / load
           balancer likes to keep a pool of open connections while waiting for clients (eg.
           Amazon ELB).

           Defaults to 5.

       --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".

       --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.

       --disable-proctitle
           Disable the behavior to set proctitle to "starman (master)" and "starman (worker)"
           respectively on master and workers.

       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 send "QUIT" signal when superdaemon received "HUP",
           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 the "start_server"
           daemon process as well.

       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).

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.

SEE ALSO

       Starman