The Emperor protocol

As of 1.3 you can spawn custom applications via the Emperor.

Non-uWSGI Vassals should never daemonize, to maintain a link with the Emperor. If you want/need better integration with the Emperor, implement the Emperor protocol.

The protocol

An environment variable UWSGI_EMPEROR_FD is passed to every vassal, containing a file descriptor number.

import os
has_emperor = os.environ.get('UWSGI_EMPEROR_FD')
if has_emperor:
   print "I'm a vassal snake!"

Or in Perl,

my $has_emperor = $ENV{'UWSGI_EMPEROR_FD'}
if ($has_emperor) {
  print "I am a vassal.\n"

Or in C,

int emperor_fd = -1;
char *has_emperor = getenv("UWSGI_EMPEROR_FD");
if (has_emperor) {
    emperor_fd = atoi(has_emperor);
    fprintf(stderr, "I am a vassal.\n");

From now you can receive (and send) messages from (and to) the Emperor over this file descriptor.

Messages are byte sized (0-255), and each number (byte) has a meaning.


Sent by the Emperor to stop a vassal


Sent by the Emperor to reload a vassal / sent by a vassal when it has been spawned


Sent by a vassal to ask the Emperor for configuration chunk


Sent by a vassal when it is ready to accept requests


Sent by a vassal after the first request to announce loyalty


Sent by a vassal to notify the Emperor of voluntary shutdown


Heartbeat sent by the vassal. After the first received heartbeat, the Emperor will expect more of them from the vassal.


Sent by the vassal to ask for Auto-scaling with Broodlord mode mode.