twistd

twistd [global_options] [application_options]

The most common usage involves specifying an application file:
twistd [global_options] -y application.tac|py

twistd also supports various built-in plugins/applications:
twistd [global_options] [plugin_specific_options]

-y file, --python=file
    Specifies the Python application file (
.tac or .py) that twistd should run.
This is the most common way to define the application.

--logfile=file
    Redirects all standard output and error to the
specified log file. This is crucial for capturing
application logs when running as a daemon.

--pidfile=file
    Creates and manages a PID file at the given path.
This file contains the process ID of the running
twistd instance, used for stopping or checking
the daemon's status.

--uid=uid, --gid=gid
    Changes the process's effective user ID (UID)
and group ID (GID) after startup. This is a
security measure to run the application with reduced privileges.

--chroot=directory
    Changes the root directory of the process using
chroot(). This creates an isolated environment,
enhancing security by limiting file system access.

--nodaemon
    Prevents twistd from detaching from the
controlling terminal. Useful for debugging
applications directly in the foreground.

--syslog
    Directs log output to the system's syslog service instead of a file.

--reactor=name
    Specifies which Twisted reactor to use
(e.g., epoll, kqueue, poll, select).
This can influence performance on different operating systems.

--stop
    Sends a shutdown signal to a running twistd daemon,
typically causing it to terminate gracefully. Requires a PID file
to be specified with --pidfile.

--reopen
    Causes twistd to close and re-open its log files,
useful for log rotation utilities like logrotate.

twistd is a command-line tool provided by the
Twisted network programming framework for Python.
Its primary purpose is to run Twisted applications
as robust, long-running daemon processes in the background.
It handles many common tasks associated with daemonization,
abstracting away complexities like detaching from the controlling terminal,
redirecting standard I/O (stdin, stdout, stderr) to files,
creating and managing a Process ID (PID) file,
and optionally changing the process's user and group permissions
for enhanced security. twistd loads a specified Python application
(typically a .tac file or a Python script using twistd.run())
and manages its lifecycle, allowing for graceful startup, shutdown,
and error handling. It's an indispensable tool for deploying production-grade
Twisted servers and services, ensuring they operate reliably
and independently of the user's session.

• Twisted Dependency: twistd requires the Twisted framework
  to be installed in the Python environment where it's executed.


• Debugging: Debugging a daemonized application can be challenging.
  Using the --nodaemon option during development is highly recommended
  to run the application in the foreground and see immediate output.


• PID File Management: Proper management of the PID file specified
  with --pidfile is crucial. If the PID file is not cleaned up
  after an abnormal shutdown, twistd might refuse to start,
  indicating a false "already running" condition.


• Application Structure: The application file (.tac or .py)
  must correctly define a Twisted application callable (an Application object)
  for twistd to execute it.

twistd primarily expects a Twisted Application configuration file,
traditionally named with a .tac extension. These files contain a variable
named application which is an instance of twisted.application.service.Application.
While .py files can also be used, they typically require a call to
twistd.run() within the script itself, making .tac files the preferred
and more standard approach for twistd deployments as they directly define
the application object without needing an explicit run call.

To gracefully stop a twistd daemon, use
twistd --pidfile=/path/to/pidfile.pid --stop.
This sends a TERM signal, allowing the application to shut down cleanly.
If the daemon doesn't respond, a kill -9 (SIGKILL) might be necessary,
but it should be avoided as it prevents graceful shutdown. For restarting,
a common pattern is to --stop and then start a new instance. Some system
service managers (like systemd) handle this orchestration automatically.

twistd emerged as a core component of the Twisted network
programming framework, which began development around the year 2000.
Its creation was driven by the need for a robust and standardized way
to deploy long-running server applications written with Twisted.
Before twistd, developers had to implement their own daemonization logic,
which was error-prone and inconsistent. twistd centralized these common
daemonization tasks, making it significantly easier to deploy and manage
Twisted-based services, ensuring they could run reliably in production
environments and integrate smoothly with standard Unix process management
utilities. It has evolved alongside the Twisted framework, adapting to new
operating system features and Python versions.

python(1), kill(1), ps(1), nohup(1), systemd(1), init.d(8)