START_SERVER(1p)

📦
version 0.35 · 2 versions
  • 0.35 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
  • 0.35 · ubuntu jammy
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 START_SERVER 💖

okay so this is a page from the User Contributed Perl Documentation set, and bestie, it's the manual for start_server(1p). buckle up 🎀

✨ NAME ✨

start_server — a superdaemon for hot-deploying server programs 🌈

no fr, that's the whole vibe. it's a superdaemon. it hot-deploys your server programs. iconic.

🦋 SYNOPSIS 🦋

start_server [options] -- server-prog server-arg1 server-arg2 ...

# start Plack using Starlet listening at TCP port 8000
start_server --port=8000 -- plackup -s Starlet --max-workers=100 index.psgi

like, you put your options, then --, then the program you wanna run and its args. that second one is a real live example of starting Plack with Starlet on TCP port 8000. slay 💅

🌸 DESCRIPTION 🌸

so this script? it's a frontend of Server::Starter. that's it, that's the description. if you want more info you gotta go read the docs for the module itself, bestie. this page is just the flyer, not the whole party 🫶

👑 OPTIONS 👑

every single one, no skips, no cap.

💜 --port=(port|host:port|port=fd|host:port=fd)

the TCP port to listen to. and if you just... don't pass it? then it won't bind to any ports at all. living free, no ports, no problems ✨

if you don't give a host, the program binds to the default address of IPv4, which is "0.0.0.0". and if you wanna do IPv6 you have to wrap it in square brackets, like --port=[::1]:8080 — yes the brackets are mandatory, it's giving strict.

if an fd is specified, then start_server allocates the socket at that given number.

and here's the fun part: it binds to UDP ports if the port numbers are prefixed by "u", e.g. --port=u443 🔥

🍓 --path=path

the path at where to listen using a unix socket (optional).

🧚 --dir=path

working directory. start_server does a chdir to it before exec (optional).

⭐ --interval=seconds

the minimum interval to respawn the server program (default: 1).

💅 --signal-on-hup=SIGNAL

name of the signal that gets sent to the server process when start_server receives a SIGHUP (default: SIGTERM).

⚠️ heads up bestie: if you use this option, be sure to also use --signal-on-term below. like, for real, don't skip it.

🌈 --signal-on-term=SIGNAL

name of the signal to be sent to the server process when start_server receives a SIGTERM (default: SIGTERM).

🎀 --pid-file=filename

if set, writes the process id of the start_server process to the file.

🦋 --status-file=filename

if set, writes the status of the server process(es) to the file.

💖 --envdir=ENVDIR

a directory that contains environment variables for the server processes and the superdaemon. it's inspired by "envdir" in "daemontools". and plot twist: this can be overwritten by the environment variable "ENVDIR" 💀

✨ --log-file=file

✨ --log-file="| cmd args..."

if set, redirects STDOUT and STDERR to the given file or command. two forms, one bullet, one destiny.

💜 --daemonize

deamonizes the server (by doing fork, setsid, fork).

⚠️ must be used together with --log-file. not optional, not negotiable.

🔥 --enable-auto-restart

enables automatic restart by time. this can be overwritten by the environment variable "ENABLE_AUTO_RESTART".

🌸 --auto-restart-interval=seconds

automatic restart interval (default 360). it is used with the --enable-auto-restart option. this can be overwritten by the environment variable "AUTO_RESTART_INTERVAL".

🫶 --kill-old-delay=seconds

time to suspend to send a signal to the old worker. the default value is 5 when --enable-auto-restart is set, and 0 otherwise. this can be overwritten by the environment variable "KILL_OLD_DELAY".

👑 --backlog=size

specifies a listen backlog parameter, whose default is SOMAXCONN (usually 128 on Linux). while SOMAXCONN is enough for most loads, a large backlog is required for heavy loads. so like, if you're popular, size up 💅

⭐ --restart

this is a wrapper command that reads the pid of the start_server process from --pid-file, sends SIGHUP to the process, and waits until the server(s) of the older generation(s) die by monitoring the contents of the --status-file.

🌈 --stop

this is a wrapper command that reads the pid of the start_server process from --pid-file and sends SIGTERM to the process.

🎀 --help

prints this help.

🦋 --version

prints the version number.

💖 AUTHOR 💖

Kazuho Oku — the icon, the moment, the author 👑

🌟 SEE ALSO 🌟

  • Server::Starter

🍓 LICENSE 🍓

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's the whole page, bestie!! this was documented by the lovely folks doing User Contributed Perl Documentation, for perl v5.36.0, dated 2022-12-12 — mwah, go hot-deploy something gorgeous 💖✨🎀

📦 where this page comes from