feat(ctl): add gunicornc control interface

Add a control socket server and CLI client for runtime management
of Gunicorn instances, similar to birdc for BIRD routing daemon.

Features:
- Control socket server running in arbiter process (asyncio/threaded)
- gunicornc CLI with interactive and single-command modes
- JSON protocol with length-prefixed framing
- Commands: show workers/stats/config/listeners/dirty, worker add/remove/kill,
  dirty add/remove, reload, reopen, shutdown
- Stats tracking (uptime, workers spawned/killed, reloads)
- Configurable socket path and permissions

New config options:
- control_socket: Unix socket path (default: gunicorn.ctl)
- control_socket_mode: Socket permissions (default: 0o600)
- --no-control-socket: Disable control socket

Author: benoitc

gunicorn/arbiter.py

@@ -74,6 +74,17 @@ def __init__(self, app):
         self.dirty_arbiter = None
         self.dirty_pidfile = None  # Well-known location for orphan detection
 
+        # Control socket server
+        self._control_server = None
+
+        # Stats tracking
+        self._stats = {
+            'start_time': None,
+            'workers_spawned': 0,
+            'workers_killed': 0,
+            'reloads': 0,
+        }
+
         cwd = util.getcwd()
 
         args = sys.argv[:]
@@ -133,6 +144,9 @@ def start(self):
         """
         self.log.info("Starting gunicorn %s", __version__)
 
+        # Initialize stats tracking
+        self._stats['start_time'] = time.time()
+
         if 'GUNICORN_PID' in os.environ:
             self.master_pid = int(os.environ.get('GUNICORN_PID'))
             self.proc_name = self.proc_name + ".2"
@@ -179,6 +193,9 @@ def start(self):
         if self.cfg.dirty_workers > 0 and self.cfg.dirty_apps:
             self.spawn_dirty_arbiter()
 
+        # Start control socket server
+        self._start_control_server()
+
         self.cfg.when_ready(self)
 
     def init_signals(self):
@@ -351,6 +368,9 @@ def wakeup(self):
 
     def halt(self, reason=None, exit_status=0):
         """ halt arbiter """
+        # Stop control socket server first
+        self._stop_control_server()
+
         self.stop()
 
         log_func = self.log.info if exit_status == 0 else self.log.error
@@ -477,6 +497,9 @@ def reexec(self):
         os.execvpe(self.START_CTX[0], self.START_CTX['args'], environ)
 
     def reload(self):
+        # Track reload stats
+        self._stats['reloads'] += 1
+
         old_address = self.cfg.address
 
         # reset old environment
@@ -667,6 +690,7 @@ def spawn_worker(self):
         if pid != 0:
             worker.pid = pid
             self.WORKERS[pid] = worker
+            self._stats['workers_spawned'] += 1
             return pid
 
         # Do not inherit the temporary files of other workers
@@ -737,6 +761,9 @@ def kill_worker(self, pid, sig):
          """
         try:
             os.kill(pid, sig)
+            # Track kills only on SIGTERM/SIGKILL (actual termination signals)
+            if sig in (signal.SIGTERM, signal.SIGKILL):
+                self._stats['workers_killed'] += 1
         except OSError as e:
             if e.errno == errno.ESRCH:
                 try:
@@ -906,3 +933,51 @@ def manage_dirty_arbiter(self):
         if self.cfg.dirty_workers > 0 and self.cfg.dirty_apps:
             self.log.info("Spawning dirty arbiter...")
             self.spawn_dirty_arbiter()
+
+    # =========================================================================
+    # Control Socket Management
+    # =========================================================================
+
+    def _get_control_socket_path(self):
+        """Get the control socket path, making relative paths absolute."""
+        socket_path = self.cfg.control_socket
+        if not os.path.isabs(socket_path):
+            socket_path = os.path.join(util.getcwd(), socket_path)
+        return socket_path
+
+    def _start_control_server(self):
+        """\
+        Start the control socket server.
+
+        The server runs in a background thread and accepts commands
+        via Unix socket.
+        """
+        if self.cfg.control_socket_disable:
+            self.log.debug("Control socket disabled")
+            return
+
+        # Lazy import to avoid circular imports and gevent compatibility
+        from gunicorn.ctl.server import ControlSocketServer
+
+        socket_path = self._get_control_socket_path()
+        socket_mode = self.cfg.control_socket_mode
+
+        try:
+            self._control_server = ControlSocketServer(
+                self, socket_path, socket_mode
+            )
+            self._control_server.start()
+        except Exception as e:
+            self.log.warning("Failed to start control socket: %s", e)
+            self._control_server = None
+
+    def _stop_control_server(self):
+        """\
+        Stop the control socket server.
+        """
+        if self._control_server:
+            try:
+                self._control_server.stop()
+            except Exception as e:
+                self.log.debug("Error stopping control server: %s", e)
+            self._control_server = None

gunicorn/config.py

@@ -3113,3 +3113,63 @@ def dirty_worker_exit(arbiter, worker):
 
         .. versionadded:: 25.0.0
         """
+
+
+# Control Socket Settings
+
+class ControlSocket(Setting):
+    name = "control_socket"
+    section = "Control"
+    cli = ["--control-socket"]
+    meta = "PATH"
+    validator = validate_string
+    default = "gunicorn.ctl"
+    desc = """\
+        Unix socket path for control interface.
+
+        The control socket allows runtime management of Gunicorn via the
+        ``gunicornc`` command-line tool. Commands include viewing worker
+        status, adjusting worker count, and graceful reload/shutdown.
+
+        By default, creates ``gunicorn.ctl`` in the working directory.
+        Set an absolute path for a fixed location (e.g., ``/var/run/gunicorn.ctl``).
+
+        Use ``--no-control-socket`` to disable.
+
+        .. versionadded:: 25.1.0
+        """
+
+
+class ControlSocketMode(Setting):
+    name = "control_socket_mode"
+    section = "Control"
+    cli = ["--control-socket-mode"]
+    meta = "INT"
+    validator = validate_pos_int
+    type = auto_int
+    default = 0o600
+    desc = """\
+        Permission mode for control socket.
+
+        Restricts who can connect to the control socket. Default ``0600``
+        allows only the socket owner. Set to ``0660`` to allow group access.
+
+        .. versionadded:: 25.1.0
+        """
+
+
+class ControlSocketDisable(Setting):
+    name = "control_socket_disable"
+    section = "Control"
+    cli = ["--no-control-socket"]
+    validator = validate_bool
+    action = "store_true"
+    default = False
+    desc = """\
+        Disable control socket.
+
+        When set, no control socket is created and ``gunicornc`` cannot
+        connect to this Gunicorn instance.
+
+        .. versionadded:: 25.1.0
+        """

gunicorn/ctl/__init__.py

@@ -0,0 +1,16 @@
+#
+# This file is part of gunicorn released under the MIT license.
+# See the NOTICE for more information.
+
+"""
+Gunicorn Control Interface
+
+Provides a control socket server for runtime management and
+a CLI client (gunicornc) for interacting with running Gunicorn instances.
+"""
+
+from gunicorn.ctl.server import ControlSocketServer
+from gunicorn.ctl.client import ControlClient
+from gunicorn.ctl.protocol import ControlProtocol
+
+__all__ = ['ControlSocketServer', 'ControlClient', 'ControlProtocol']