1STARMAN(1)            User Contributed Perl Documentation           STARMAN(1)
2
3
4

NAME

6       starman - Starman launcher
7

SYNOPSIS

9         starman --listen :5001 --listen /tmp/starman.sock
10         starman --workers 32 --port 8080
11

OPTIONS

13       -l, --listen
14             --listen HOST:PORT --listen :PORT --listen UNIX_SOCKET
15             --listen HOST:PORT:ssl
16
17           Specifies the TCP address, ports and UNIX domain sockets to bind to
18           wait for requests. You can repeat as many times as you want and mix
19           TCP and UNIX domain sockets.
20
21           For TCP sockets you can append ":ssl" after the port to specify
22           that connections on that port should use SSL. Note that the SSL
23           support is experimental and hasn't been widely tested.
24
25           Defaults to any IP address and port 5000.
26
27       --host
28             --host 127.0.0.1
29
30           Specifies the address to bind.
31
32           This option is for a compatibility with plackup and you're
33           recommended to use "--listen" instead.
34
35       --port
36             --port 8080
37
38           Specifies the port to bind.
39
40           This option is for a compatibility with plackup and you're
41           recommended to use "--listen" instead.
42
43       -S, --socket
44             -S /tmp/starman.sock
45
46           Specifies the path to UNIX domain socket to bind.
47
48           This option is for a compatibility with plackup and you're
49           recommended to use "--listen" instead.
50
51       --workers
52           Specifies the number of worker pool. Defaults to 5.
53
54           Starman by default sets up other spare server configuration based
55           on this workers value, making sure there are always only "N" worker
56           processes running. So even if there're no idle workers, Starman
57           won't spawn off spare processes since that's mostly what you want
58           to do by fine tuning the memory usage etc. in the production
59           environment.
60
61       --backlog
62           Specifies the number of backlog (listen queue size) of listener
63           sockets. Defaults to 1024.
64
65           On production systems, setting a very low value can allow failover
66           on frontend proxy (like nginx) to happen more quickly, if you have
67           multiple Starman clusters.
68
69           If you're doing simple benchmarks and getting connection errors,
70           increasing this parameter can help avoid them. You should also
71           consider increasing "net.core.somaxconn". Note that this is not
72           recommended for real production system if you have another cluster
73           to failover (see above).
74
75       --max-requests
76           Number of the requests to process per one worker process. Defaults
77           to 1000.
78
79       --preload-app
80           This option lets Starman preload the specified PSGI application in
81           the master parent process before preforking children. This allows
82           memory savings with copy-on-write memory management. When not set
83           (default), forked children loads the application in the
84           initialization hook.
85
86           Enabling this option can cause bad things happen when resources
87           like sockets or database connections are opened at load time by the
88           master process and shared by multiple children.
89
90           Since Starman 0.2000, this option defaults to false, and you should
91           explicitly set this option to preload the application in the master
92           process.
93
94           Alternatively, you can use -M command line option (plackup's common
95           option) to preload the modules rather than the <application>
96           itself.
97
98             starman -MCatalyst -MDBIx::Class myapp.psgi
99
100           will load the modules in the master process for memory savings with
101           CoW, but the actual loading of "myapp.psgi" is done per children,
102           allowing resource managements such as database connection safer.
103
104           If you enable this option, sending "HUP" signal to the master
105           process will not pick up any code changes you make. See "SIGNALS"
106           for details.
107
108       --disable-keepalive
109           Disable Keep-alive persistent connections. It is an useful
110           workaround if you run Starman behind a broken frontend proxy that
111           tries to pool connections more than a number of backend workers
112           (i.e. Apache mpm_prefork + mod_proxy).
113
114       --keepalive-timeout
115           The number of seconds Starman will wait for a subsequent request
116           before closing the connection if Keep-alive persistent connections
117           are enabled. Setting this to a high value may cause performance
118           problems in heavily loaded servers. The higher the timeout, the
119           more backend workers will be kept occupied waiting on connections
120           with idle clients.
121
122           Defaults to 1.
123
124       --read-timeout
125           The number of seconds Starman will wait for a request on a new
126           connection before closing it. Setting this to a high value may
127           cause performance problems in heavily loaded servers. The higher
128           the timeout, the more backend workers will be kept occupied waiting
129           on connections with idle clients. You may need this if your proxy /
130           load balancer likes to keep a pool of open connections while
131           waiting for clients (eg. Amazon ELB).
132
133           Defaults to 5.
134
135       --user
136           To listen on a low-numbered (<1024) port, it will be necessary to
137           start the server as root. Use the "--user" option to specify a
138           userid or username that the server process should switch to after
139           binding to the port.
140
141           Defaults to the current userid.
142
143       --group
144           Specify the group id or group name that the server should switch to
145           after binding to the port.  This option is usually used with
146           "--user".
147
148           Defaults to the current group id.
149
150       --pid
151           Specify the pid file path. Use it with "-D|--daemonize" option,
152           described in "plackup -h".
153
154       --error-log
155           Specify the pathname of a file where the error log should be
156           written.  This enables you to still have access to the errors when
157           using "--daemonize".
158
159       --ssl-cert
160           Specify the path to SSL certificate file.
161
162       --ssl-key
163           Specify the path to SSL key file.
164
165       --enable-ssl
166           Enable SSL on all TCP sockets. This is an experimental feature.
167
168       --disable-proctitle
169           Disable the behavior to set proctitle to "starman (master)" and
170           "starman (worker)" respectively on master and workers.
171
172       Starman passes through other options given to Plack::Runner, the common
173       backend that plackup uses, so the most options explained in "plackup
174       -h" such as "--access-log" or "--daemonize" works fine in starman too.
175
176       Setting the environment variable "STARMAN_DEBUG" to 1 makes the Starman
177       server running in the debug mode.
178

SIGNALS

180       HUP Sending "HUP" signal to the master process will restart all the
181           workers gracefully (meaning the currently running requests will
182           shut down once the request is complete), and by default, the
183           workers will pick up the code changes you make by reloading the
184           application.
185
186           If you enable "--preload-app" option, however, the code will be
187           only loaded in the startup process and will not pick up the code
188           changes you made. If you want to preload the app and do graceful
189           restarts by reloading the code changes, you're recommended to use
190           Server::Starter, configured to send "QUIT" signal when superdaemon
191           received "HUP", i.e:
192
193               start_server --interval 5 --port 8080 --signal-on-hup=QUIT -- \
194                 starman --preload-app myapp.psgi
195
196           You will then send the HUP signal to "start_server" process to
197           gracefully reload the starman cluster (master and workers).
198
199           With Server::Starter 0.12 or later, you should also be able to set
200           "--signal-on-term" to QUIT so that you can safely shutdown Starman
201           first and then stop the "start_server" daemon process as well.
202
203       TTIN, TTOU
204           Sending "TTIN" signal to the master process will dynamically
205           increase the number of workers, and "TTOU" signal will decrease it.
206
207       INT, TERM
208           Sending "INT" or "TERM" signal to the master process will kill all
209           the workers immediately and shut down the server.
210
211       QUIT
212           Sending "QUIT" signal to the master process will gracefully
213           shutdown the workers (meaning the currently running requests will
214           shut down once the request is complete).
215

RELOADING THE APPLICATION

217       You're recommended to use signals (see above) to reload the
218       application, and are strongly discouraged to use "-r" or "-R"
219       (reloading flag) from plackup. These options will make a separate
220       directory watcher process, and makes your life difficult if you want to
221       combine with other process daemon tools such as Server::Starter.
222

DIFFERENCES WITH PLACKUP

224       "starman" executable is basically the equivalent of using "plackup"
225       with "Starman" server handler i.e. "plackup -s Starman", except that
226       "starman" delay loads the application with the Delayed loader by
227       default, which can be disabled with "--preload-app".
228
229       "starman" command also automatically sets the environment ("-E") to the
230       value of deployment.
231
232       You're recommended to use "starman" unless there's a reason to stick to
233       "plackup" for compatibility.
234

SEE ALSO

236       Starman
237
238
239
240perl v5.34.0                      2021-07-22                        STARMAN(1)
Impressum