STARMAN(1p)

✨ STARMAN 💅

okay bestie, so this is starman, a Perl thing, and it's the launcher 🌟 for it. It's user-contributed Perl documentation, iykyk. Get comfy, we're going through it together 🫶

---

🌸 SYNOPSIS 🌸

literally the whole vibe in two lines:

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

---

🎀 OPTIONS 🎀

• -l, --listen — this is the main character fr fr. its forms are:

--listen HOST:PORT --listen :PORT --listen UNIX_SOCKET
--listen HOST:PORT:ssl

It tells starman which TCP addresses, ports and UNIX domain sockets to bind to so it can sit there waiting for requests. You can repeat this flag as MANY times as you want, and mix TCP and UNIX domain sockets together, no cap 🦋

For TCP sockets you can stick :ssl right after the port to say connections on that port should use SSL. but heads up! the SSL support is experimental and hasn't been widely tested. it's giving "we tried" 😭

Defaults to any IP address and port 5000.

• --host — the format is:

--host 127.0.0.1

Specifies the address to bind.

This one exists for compatibility with plackup, and honestly you're recommended to use --listen instead 💅

• --port — the format is:

--port 8080

Specifies the port to bind.

Again, compatibility with plackup vibes — you're recommended to use --listen instead.

• -S, --socket — the format is:

-S /tmp/starman.sock

Specifies the path to the UNIX domain socket to bind.

Yep, you guessed it: compatibility with plackup, and you're recommended to use --listen instead 🎀

• --workers — sets the size of the 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 are no idle workers, Starman won't spawn off spare processes — because that's mostly what you actually want, like fine tuning memory usage and stuff in a production environment. it's intentional bestie, not a bug 🌈

• --backlog — specifies the backlog size (the listen queue size) of listener sockets. Defaults to 1024.

On production systems, setting a very low value can let failover on a frontend proxy (like nginx) happen more quickly, if you have multiple Starman clusters. slay for failover 🍓

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. But note! that's not recommended for real production systems if you have another cluster to failover to (see above). balance, bestie ⚖️

• --max-requests — the number of 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 (and that's the default), forked children load the application in the initialization hook.

Enabled this and bad things can happen when resources like sockets or database connections are opened at load time by the master process and then shared by multiple children. be careful, bestie, that's the scary part 💀

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 the -M command line option (plackup's common option) to preload the modules rather than the <application> itself. So like:

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 child, making management of resources such as database connections safer. chef's kiss 👑

If you enable this option, sending a HUP signal to the master process will not pick up any code changes you make. See "SIGNALS" for the details 🙈

• --disable-keepalive — disables Keep-alive persistent connections. It's a genuinely useful workaround if you run Starman behind a broken frontend proxy that tries to pool more connections than there are backend workers (i.e. Apache mpm_prefork + mod_proxy). fix your proxy or use this, either way 😭
• --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. drop those privileges, queen 👑

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. they're a package deal fr fr 🫶

Defaults to the current group id.

• --pid — specify the pid file path. Use it with the -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. so you're not just sending your server into the void and hearing nothing back 🌸
• --ssl-cert — specify the path to the SSL certificate file.
• --ssl-key — specify the path to the SSL key file.
• --enable-ssl — enable SSL on all TCP sockets. This is an experimental feature. you've been warned bestie 💀
• --disable-proctitle — disable the behavior of setting proctitle to starman (master) and starman (worker) respectively on master and workers. if you hate labels, this one's for you ✨

Starman passes through other options given to Plack::Runner — that's the common backend that plackup uses — so most options explained in plackup -h (such as --access-log or --daemonize) work fine in starman, too. teamwork makes the dream work 🌈

Setting the environment variable STARMAN_DEBUG to 1 makes the Starman server run in 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. iconic behavior honestly 🌟

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). chef's kiss, no downtime 💅

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. orderly exits only ✨

• TTIN, TTOU — sending TTIN signal to the master process will dynamically increase the number of workers, and TTOU signal will decrease it. scale up, scale down, main character energy 📈📉
• INT, TERM — sending INT or TERM signal to the master process will kill all the workers immediately and shut down the server. no goodbyes, just gone 💀
• 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). the polite version 🎀

---

🦋 RELOADING THE APPLICATION 🦋

You're recommended to use signals (see above) to reload the application, and are strongly discouraged from using -r or -R (the reloading flag) from plackup. These options will make a separate directory watcher process, and make your life difficult if you want to combine with other process daemon tools such as Server::Starter. just don't, bestie 😭

---

🌈 DIFFERENCES WITH PLACKUP 🌈

The starman executable is basically the equivalent of using plackup with the 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. subtle but important 🫶

The 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. bestie trust, go with starman 👑

---

⭐ SEE ALSO ⭐

Starman — that's the one, that's the reference 💜

---

and that's the whole page babes!! 🎀 this was documented for perl v5.40.1 and it's dated 2026-05-05 — iconic date, no notes 💅✨ go slay some requests 🦋