START_SERVER(1)

📦
version 0.35 · 6 versions
, in fedora 43

💖 START_SERVER(1) 💖

okay bestie, gather round, because this is START_SERVER(1) from the User Contributed Perl Documentation section and it is so much cooler than it sounds. it's a superdaemon for hot-deploying server programs and it's giving main character energy fr fr 🦋

✨ NAME ✨

start_server — a superdaemon for hot-deploying server programs 👑

🌸 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, the -- is the vibe check divider between your flags and the server program's flags. everything after it belongs to the server program, no cap.

🎀 DESCRIPTION 🎀

so this script is literally a frontend of Server::Starter. that's it, that's the whole description. for more info you gotta go read the documentation of the module — this page is just the little door into the bigger house. iykyk 💅

💅 OPTIONS 💅

okay here's the menu, and no we are NOT skipping any of them:

  • --port=(port|host:port|port=fd|host:port=fd) — the TCP port to listen to. if you just... don't include it, it will not bind to any ports at all, and that's valid of you tbh.
    • if no host is specified, the program binds to the default address of IPv4, which is 0.0.0.0 🌈
    • for an IPv6 address you must use square brackets, like --port=[::1]:8080 — the brackets are the outfit, the address is the girlie 🎀
    • if fd is specified, then start_server allocates the socket at the given number.
    • and get this — it binds to UDP ports when the port numbers are prefixed by u, like --port=u443 ✨ (the u stands for "u thought it was TCP? wrong")
  • --path=path — the path where to listen using a unix socket. it's optional, but lowkey iconic.
  • --dir=path — working directory. start_server does a chdir to it before exec. also optional.
  • --interval=seconds — the minimum interval to respawn the server program. default is 1 second ⏱️
  • --signal-on-hup=SIGNAL — the name of the signal sent to the server process when start_server receives a SIGHUP. default: SIGTERM. ⚠️ and bestie, listen: if you use this option, be sure to also use --signal-on-term below. they're a package deal, don't split them up 😭
  • --signal-on-term=SIGNAL — the name of the signal sent to the server process when start_server receives a SIGTERM. default: SIGTERM.
  • --pid-file=filename — if set, it writes the process id of the start_server process into the file. cute lil receipt 🧾
  • --status-file=filename — if set, it writes the status of the server process(es) into the file. another receipt, this one's about the workers 🫶
  • --envdir=ENVDIR — a directory containing environment variables for the server processes and the superdaemon. it's inspired by envdir in daemontools ✨ and it 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. yes, the pipe version pipes into a command, we love a multitasker 💅
  • --daemonize — daemonizes the server, by doing fork, setsid, fork (the triple threat 💀). must be used together with --log-file. no log file, no daemon, periodt.
  • --enable-auto-restart — enables automatic restart by time. can be overwritten by the environment variable ENABLE_AUTO_RESTART. ⏰
  • --auto-restart-interval=seconds — the automatic restart interval. default is 360. it's used with the --enable-auto-restart option. can be overwritten by the environment variable AUTO_RESTART_INTERVAL.
  • --kill-old-delay=seconds — the time to suspend before sending a signal to the old worker. the default value is 5 when --enable-auto-restart is set, and 0 otherwise. 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 if you're getting slammed, bump it.
  • --restart — a wrapper command that reads the pid of the start_server process from --pid-file, sends SIGHUP to the process, and then waits until the server(s) of the older generation(s) die by monitoring the contents of the --status-file. it's the "out with the old, in with the new" button 🌸
  • --stop — a wrapper command that reads the pid of the start_server process from --pid-file and sends SIGTERM to the process. the peace-out button 👋
  • --help — prints this help.
  • --version — prints the version number.

👑 AUTHOR 👑

Kazuho Oku — the icon, the legend, the moment. we stan 🫶

🌈 SEE ALSO 🌈

  • Server::Starter — go read it, bestie, this page is literally just its frontend.

📜 LICENSE 📜

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. (yes, that's the whole thing, and yes it's iconic 💜)

and that's the whole page, bestie!! 💖 this was perl v5.42.0, dated 2025-07-25, and it's the START_SERVER(1) page from the User Contributed Perl Documentation. go hot-deploy something gorgeous ✨🦋

📦 where this page comes from