uWSGI Master Process and Vacuum Socket Cleanup Limits

Question

Process Management and Socket Persistence
In production environments, uWSGI is frequently configured with the master and vacuum options to ensure worker lifecycle management and the removal of Unix sockets upon termination. While these settings function predictably during manual restarts in local development, production deployments often rely on signal-based reloading or automated process managers.
There is a specific dependency between the master process and the ability to perform graceful reloads. Without the master process enabled, the application cannot respond to specific signals required for zero-downtime updates, and the vacuum directive may not execute if the process is terminated abruptly by an external supervisor.

The master process handles signal propagation to workers.
The vacuum option targets the cleanup of sockets and pidfiles.

What are the specific limitations of the vacuum option when the master process is absent during a SIGTERM event? Does the lack of a master process prevent the cleanup of the Unix socket even if the vacuum flag is explicitly set?

Tasadduq Burney · Answer

The Impact of the Master Process on Socket Cleanup
Yes, the lack of a master process can prevent the cleanup of a Unix socket even if the vacuum flag is explicitly set. In uWSGI, the vacuum directive is a cleanup instruction executed by the master process during the shutdown sequence. If the master process is absent, there is no central coordinator to handle the unlinking of the socket file from the filesystem upon termination.

How Vacuuming Operates
When the master option is enabled, uWSGI creates a primary process that manages worker lifecycles. When this master process receives a termination signal (such as SIGTERM), it orchestrates a graceful shutdown: it signals workers to stop accepting new connections, allows current requests to finish, and finally executes the vacuum routine to delete the Unix socket and PID files.

Limitations Without a Master Process
If you run uWSGI without the master flag, the application runs as a standalone process (or a set of independent workers). This introduces several critical limitations during a SIGTERM event:

Lack of Coordination: There is no supervisor process to catch the signal and trigger the vacuum logic across the instance.
Abrupt Termination: Without a master process, the OS may terminate the process before the internal cleanup routines are reached, leaving a "stale" socket file on the disk.
Signal Handling: The ability to perform zero-downtime reloads (via SIGHUP) is lost, as these signals specifically target the master process to spawn new workers before killing old ones.

Verification and Safe Testing
To verify the dependency between the master process and the vacuum flag, you can run the following tests in a controlled environment (assuming uWSGI is installed and a socket path is defined):

Test with Master: Start uWSGI with --master --vacuum --socket /tmp/uwsgi.sock. Send a SIGTERM to the process. Verify the socket is gone: ls /tmp/uwsgi.sock should return "No such file or directory".
Test without Master: Start uWSGI with --vacuum --socket /tmp/uwsgi.sock (omitting --master). Send a SIGTERM. Check the socket path; it will likely persist as a stale file.

Diagnostic Requirement
To provide a more tailored recommendation for your production environment, please specify which process manager (e.g., systemd, supervisord, or Kubernetes) is sending the termination signal, as some managers use SIGKILL after a timeout, which bypasses vacuum regardless of the master process status.

uWSGI Master Process and Vacuum Socket Cleanup Limits

Process Management and Socket Persistence

1 answer

The Impact of the Master Process on Socket Cleanup

How Vacuuming Operates

Limitations Without a Master Process

Verification and Safe Testing

Diagnostic Requirement

Your perspective belongs here.

1 question comment

Practical Verification