Swoole Server Configuration

1. Swoole
2. Swoole Docs
3. Modules
4. Swoole Server
5. Swoole Server Configuration

Swoole Server configurations can be set with $server->set.

Full list example

<?php
$server->set([
    'buffer_output_size' => 32 * 1024*1024, // byte in unit
    'chroot' => '/data/server/',
    'cpu_affinity_ignore' => [0, 1],
    'daemonize' => 1,
    'dispatch_mode' => 1,
    'discard_timeout_request' => true,
    'dispatch_func' => 'my_dispatch_function',
    'enable_delay_receive' => true,
    'user' => 'apache',
    'group' => 'www-data',
    'enable_reuse_port' => true,
    'enable_unsafe_event' => true,
    'heartbeat_idle_time' => 600,
    'heartbeat_check_interval' => 60,
    'log_level' => 1,
    'log_file' => '/data/swoole.log',
    'max_conn' => 1000,
    'max_request' => 0,
    'max_request_grace' => $max_request / 2,
    'worker_num' => 2,
    'message_queue_key' => 'mq1',
    'open_eof_check' => true,
    'open_eof_split' => true,
    'package_eof' => '\r\n', 
    'open_cpu_affinity' => true,
    'open_http2_protocol' => true,
    'open_http_protocol' => true,
    'open_length_check' => true,
    'package_length_type' => 'N',
    'package_body_offset' => 8,
    'package_length_offset' => 8,
    'package_max_length' => 81920,
    'open_mqtt_protocol' => true,
    'open_tcp_nodelay' => false,
    'open_websocket_protocol' => true,
    'package_length_func' => 'my_package_length_func',
    'pid_file' => __DIR__.'/server.pid',
    'pipe_buffer_size' => 32 * 1024*1024,
    'reactor_num' => 8,
    'socket_buffer_size' => 128 * 1024*1024,
    'ssl_cert_file' => __DIR__ . '/config/ssl.cert',
    'ssl_key_file' => __DIR__ . '/config/ssl.key',
    'ssl_ciphers' => 'ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP',
    'ssl_method' => SWOOLE_SSLv3_CLIENT_METHOD,
    'task_ipc_mode' => 1,
    'task_max_request' => 100,
    'task_tmpdir' => '/tmp',
    'task_worker_num' => 8,
    'tcp_defer_accept' => true,
    'enable_static_handler' => true,
    'document_root' => __DIR__ . '/public',
    'reload_async' => true,
    'max_wait_time' => 3,
    'tcp_fastopen' => false,
    'request_slowlog_file' => fasle,
    'max_coroutine' => 3000,
    'send_yield' => false,
    'open_tcp_keepalive' => true
])

backlog

Allow a number of waiting connections.

The configuration is an integer representing the number of pending connections that wait for accept.

buffer_output_size

Set the output buffer size in the memory.

The default value is 2M. The data to send can't be larger than buffer_output_size every time.

Usage

<?php
$server->set([
    'buffer_output_size' => 32 * 1024*1024, // byte in unit
])

chroot

Redirect the root path of the worker process.

This configuration is to separate the operation to the file system in the worker process from the real file system.

Usage

<?php
$server->set([
    'chroot' => '/data/server/'
]);

cpu_affinity_ignore

By default, all the I/O interrupts are processed by CPU 0.

Set the CPU core number which are only used to handle the I/O interrupts.

Usage

<?php
[
    'cpu_affinity_ignore' => [0, 1]
]

How to check I/O interrupts on CPU cores?

cat /proc/interrupts 

daemonize

Daemonize the swoole server process.

If the value of daemonize is more than 1, the swoole server will be daemonized.

The program which wants to run a long time must enable this configuration.

If the daemonize has been enabled, the standard output and error of the program will be redirected to logfile. And if the configuration of log_file hasn't been set, the standard output and error of the program will be redirected to /dev/null.

After daemonizing the processes, the value of CWD will change and the relative path of the file will be different. So it must use the absolute path in the program.

discard_timeout_request

If the configuration of dispatch_mode is 1 or 3, there may be some data that arrive to the worker process after closing the connection.

In this situation, if discard_timeout_request is true, the worker process will discard these data or still process these data.

dispatch_func

Set the dispatch_func to dispatch the connection to the worker process.

The swoole server provides [five types of dispatch_mode. If the dispatch_mode can't meet your need, you can write C++ function or PHP function to realize customized dispatch strategy.

Usage

<?php
$server->set([
    'dispatch_func' => 'my_dispatch_function',
]);

Once the dispatch_func has been setted, the configuration dispatch_mode would not work.

If the function set by dispatch_func, Swoole will result in a fatal error.

If the data dispatched is more than 8K, dispatch_func can get 0-8180 bytes data.

PHP function

It is forbidden to add any blocking operation in the dispatch_func otherwise the Reactor group would stop.

<?php
$server->set([
    'dispatch_func' => function ($server, $fd, $type, $data) {
        var_dump($fd, $type, $data);
        return intval($data[0]);
    }
]);

Parameters:

• $fd, the id number of client

• $type, the type of data, 0: receive data from the client, 4: the connection with the client closes, 5: the connection with the client starts

• $data, the data to dispatch

Return:

the return must be an integer between 0 and worker_num

C++ function

In other extension, use swoole_add_function to register function to swoole

int dispatch_function(swServer *serv, swConnection *conn, swEventData *data);

int dispatch_function(swServer *serv, swConnection *conn, swEventData *data)
{
    printf("cpp, type=%d, size=%d\n", data->info.type, data->info.len);
    return data->info.len % server->worker_num;
}

int register_dispatch_function(swModule *module)
{
    swoole_add_function("my_dispatch_function", (void *) dispatch_function);
}

dispatch_mode

The mode of dispatching connections to the worker process.

This parameter only works for the SWOOLE_PROCESS mode swoole_server.

• 1, polling mode. Dispatch the connection to the workers in sequence.

• 2, fixed mode(default value of dispatch_mode). Dispatch the connection to the worker according to the id number of connection. In this mode, the data from the same connection will be handled by the same worker process.

• 3, preemptive mode. The swoole will dispatch the connection to the unoccupied worker process.

• 4, IP mode. Dispatch the connection to the worker according to the IP of the client. The dispatch algorithm is ip2long(ClientIP) % worker_num

• 5, uid mode. If the connection has been bound with a uid by Swoole\Server->bind, the swoole will dispatch the connection to the worker according to the uid. The dispatch algorithm is UID % worker_num. If you want to use a string as a uid, it should convert this string by crc32($uid)

Usage advice

• stateless server: 3 is advised for synchronous and blocking server, 1 is advised for asynchronous and non-blocking server

• stateful server: 2, 4, 5

If the dispatch_mode is 1 or 3, the event of connect and close will be shielded.

enable_delay_receive

Enable the delay of receiving a new connection.

Once enabled, the client which has been accepted would not be added to the EventLoop automatically and only trigger the callback function of the received event.

The worker process needs to call $server->confirm($fd) to confirm the connection manually and add the connection to the EventLoop.

Usage

<?php
// enable `enable_delay_receive`
$server->set([
    'enable_delay_receive' => true,
]);

$server->on("Connect", function ($server, $fd, $reactorId) {
    $server->after(2000, function() use ($server, $fd) {
        // confirm connection and start process data
        $server->confirm($fd);
    });
});

enable_reuse_port

Enable the reuse of port.

enable_unsafe_event

Enable the event of close and close when the dispatch_mode is 1 or 3.

group

Set the group of worker and task worker process.

Usage

<?php
$server->set([
    'group' => 'www-data'
]);

heartbeat_check_interval

This configuration heartbeat_check_interval is the interval of polling every TCP connection.

If the connection hasn't sent any data to the server in the last interval of heartbeat_check_interval, the connection will be closed.

The swoole server would not send the heartbeat packet to the client but only wait for the heartbeat packet from the client. The heartbeat check of swoole server only checks the last time of sending data from the client. If the time exceeds heartbeat_check_interval, the connection between the server and the client will be closed.

heartbeat_idle_time

This configuration which works with the heartbeat_check_interval stands for the max idle time of connection.

Usage

<?php
[
    'heartbeat_idle_time' => 600,
    'heartbeat_check_interval' => 60,
];

log_file

Set the log path of swoole.

Tips

In the log file, there are some labels to distinguish the thread or process that output the log item.

• # Master process

• $ Manager process

• * Worker process

• ^ Task worker process

Reopen the log file

If the log file has been mv or unlink, the log can't be recorded normally. In this situation, you can send SIGRTMIN

log_level

Set the level of the log.

The log that is inferior to the log_level set will not be recorded to log file.

Usage

<?php
$server->set([
    'log_level' => 1,
]);

Log level list

0 =>DEBUG // all the levels of log will be recorded
1 =>TRACE
2 =>INFO
3 =>NOTICE
4 =>WARNING
5 =>ERROR

max_conn

The max number of connection the server could handle at the same time.

After exceeding this limit, the swoole server will refuse the new coming connection.

max_conn should be less than ulimit -n max_conn should be more than (server->worker_num + SwooleG.task_worker_num) * 2 + 32 the default value of max_conn is ulimit -n the value of max_conn should not be too large and be setted according to the memory usage of server.

max_request

A worker process is restarted to avoid memory leak when receving max_request + rand(0, max_request_grace) requests.

The default value of max_request_grace is (max_request / 2);

The default value of max_request is 0 which means there is no limit of the max request. If the max_request is set to some number, the worker process will exit and release all the memory and resource occupied by this process after receiving the max_request request. And then, the manager will respawn a new worker process.

This parameter is to resolve the problem of nonlocalizable and slow memory leak.

max_request only works for synchronous, blocking and stateless response program The asynchronous server should not set max_request max_request only works for SWOOLE_PROCESS mode.

<?php
$server = new swoole_server("127.0.0.1", 9501);
$server->set([
    'worker_num' => 2,    
    'max_request' => 3,  
    'dispatch_mode'=>3,
]);

$server->on('receive', function ($server, $fd, $from_id, $data) {
    $server->send($fd, "Server: ".$data);
});

$server->start();

Check the PID of the worker process before request and after many times request.

max_request_grace

The default value of max_request_grace is (max_request / 2);

A worker process is restarted to avoid memory leak when receving max_request + rand(0, max_request_grace)requests.

You can disable the rand function by setting max_request_grace = 0;

message_queue_key

Set the key of the message queue.

This configuration only works if the configuration of task_ipc_mode has been set to 2 or 3.

The default value of message_queue_key is calculated by ftok($php_script_file, 1).

open_cpu_affinity

Open the affinity setting of CPU.

By enabling open_cpu_affinity, the worker process is bonding with a CPU core to increase the CPU cache hit rate.

How to check if the process is bonding with a CPU core?

taskset -p PID

pid 24666\'s current affinity mask: f
pid 24901\'s current affinity mask: 8

Check more about CPU affinity and taskset

open_eof_check

This configuration is to check the package EOF. The package EOF is set by the configuration package_eof

Usage

If this configuration has been enabled, the swoole will check the end of data from the client. If the end of data from the client is the string set by package_eof, the swoole will send the data to the worker process otherwise the swoole will continue to receive and joint the data from the client.

<?php
[
    'open_eof_check' => true,
    'package_eof' => "\r\n", 
]

The above configuration example can be used for Memcache or POP protocal which ends by \r\n. Once setted, the worker process will receive one or serveral whole packages. In the worker process, you should use explode("\r\n", $data) split the data or set the configuration package_eof to split the data automatically.

open_eof_split

Enable the split of data to package.

Once the configuration open_eof_check has been set, the worker process will receive the data ending with the specified string. This data may contain one or serval whole package. In this situation, you can enable the open_eof_split to split the data to package automatically. And then the callback function onReceive will receive a whole package.

open_http2_protocol

Enable the process of http2 protocol.

This configuration needs to compile swoole with --enable-http2

Usage

<?php
$server->set([
    'open_http2_protocol' => true
]);

open_http_protocol

Enable the HTTP protocol.

Once this configuration has enabled, the callback function onReceive will receive a whole HTTP package.

The swoole_http_server will enable this configuration automatically.

Usage

<?php
$server->set([
    'open_http_protocol' => true
]);

open_length_check

Open the check of package length.

If this configuration has enabled, the swoole will open the analysis of package which has fixed header and body. And the worker process will receive a whole package in the callback function onReceive.

This configuration should work with three other configurations.

package_length_type

Use some field in the header of the package to stand for the length the package. The swoole supports 10 types of length. Check the full list in the configuration of package_length_type.

package_body_offset

The offset of the package to calculate the length of the package.

• 0, the length stands for the length of header and body

• N, this value stands for that the length of the header is N and the length of a package only contains the length of the body.

package_length_offset

The offset of the value of length in the header

Example

struct
{
    uint32_t type;
    uint32_t uid;
    uint32_t length;
    uint32_t serid;
    char body[0];
}

The configuration designed from the above protocal design

<?php
$server->set(array(
    'open_length_check' => true,
    'package_max_length' => 81920,
    'package_length_type' => 'N',
    'package_length_offset' => 8,
    'package_body_offset' => 16,
));

open_mqtt_protocol

Enable the process of MQTT protocol.

Once this configuration has enabled, the swoole will analyze the MQTT package head and the callback function onReceive will receive a whole MQTT package.

Usage

<?php
$server->set([
    'open_mqtt_protocol' => true
]);

open_tcp_nodelay

Open this configuration to close the Nagle algorithm.

open_websocket_protocol

Enable the process of WebSocket protocol.

Swoole enables this configuration open_http_protocol automatically if the configuration open_websocket_protocol has been enabled.

The swoole_websocket_server will enable this configuration automatically.

Usage

<?php
$server->set([
    'open_websocket_protocol' => true
]);

package_eof

Set the end string of package.

This configuration should work with open_eof_check.

The max length of this string is 8 bytes.

package_length_func

Set the function to check the length of the package. The swoole supports the PHP function and C++ function.

The function returns an integer.

• 0, lack of data to joint a whole package

• 1, error data, the swoole will close the connection.

• The length of the package.

PHP function

<?php
$server = new Swoole\Server("127.0.0.1", 9501);

$server->set([
    'open_length_check' => true,
    'dispatch_mode' => 1,
    'package_length_func' => function ($data) {
        if (strlen($data) < 8) {
            return 0;
        }
        $length = intval(trim(substr($data, 0, 8)));
        if ($length <= 0) {
            return -1;
        }

        return $length + 8;
    },
    'package_max_length' => 32 * 1024*1024,
]);

$server->on('receive', function (Swoole\Server $serv, $fd, $from_id, $data){
    var_dump($data);
    echo "#{$server->worker_id}>> received length=" . strlen($data) . "\n";
});

$server->start();

package_length_type

The type of length. For now, the swoole supports 10 types.

• c : signed, 1 byte
• C : unsigned, 1 byte
• s : signed, host byte order, 2 bytes
• S : unsigned, host byte order, 2 bytes
• n : unsigned, network byte order, 2 bytes
• N : unsigned, network byte order, 4 bytes
• l : signed, host byte order, 4 bytes
• L : unsigned, host byte order, 4 bytes
• v : unsigned, little endian, 2 bytes
• V : unsigned, little endian, 4 bytes

package_max_length

The max length of a package whose unit is byte.

Once the configuration open_length_check/open_eof_check/open_http_protocol has enabled, the internal of swoole will joint the data received from the client and the data stores in the memory before receiving the whole package. So to limit the usage of memory, it should set the package_max_length.

pid_file

The file path which the master process id saves in.

Usage

<?php
$server->set([
    'pid_file' => __DIR__.'/server.pid',
]);

The PID of master process saves in the pid_file after the swoole server starts. And this file is deleted after the swoole server stops normally.

pipe_buffer_size

Set the buffer size of the pipe.

Usage

<?php
$server->set([
    'pipe_buffer_size' => 32 * 1024 *1024,
]);

reactor_num

the number of the reactor thread(for SWOOLE_BASE_MODE)

You can change the number of event processing thread in the master process.

To make full use of CPU, the default number of reactor_num is the number of core in CPU.

In general, the number of the reactor thread is between one and four times of CPU cores.

socket_buffer_size

Set the buffer size of the socket.

This configuration is to set the max memory size of the connection.

Usage

<?php
$server->set([
    'socket_buffer_size' => 128 * 1024 *1024,
])

ssl_cert_file

It must add --enable-openssl to the support for SSL when you compile the swoole

To enable SSL, it should set the file path of the cert file and the key file.

<?php
$server = new Swoole\Server("0.0.0.0", 9501, SWOOLE_PROCESS, SWOOLE_SOCK_TCP | SWOOLE_SSL);
$server->set([
    'ssl_cert_file' => __DIR__ . '/config/ssl.cert',
    'ssl_key_file' => __DIR__ . '/config/ssl.key',
]);

• The web browser must trust the credential before browsing the webpage
• In the WebSocket application, the part starting the connection of WebSocket must use https
• The certificate extensions must be PEM and not DER

Convert PEM to DER:

openssl x509 -in cert.crt -outform der -out cert.der

Convert DER to PEM:

openssl x509 -in cert.crt -inform der -outform pem -out cert.pem

ssl_ciphers

Set the ssl_ciphers to change the default encryption algorithm of OpenSSL. The default encryption algorithm of OpenSSL is EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH

<?php
$server->on([
    'ssl_ciphers' => 'ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP', // the swoole use the default algorithm when the `ssl_ciphers` is empty
]);

ssl_key_file

It must add --enable-openssl to the support for SSL when you compile the swoole

To enable SSL, it should set the file path of the cert file and the key file.

<?php
$server = new Swoole\Server("0.0.0.0", 9501, SWOOLE_PROCESS, SWOOLE_SOCK_TCP | SWOOLE_SSL);
$server->set([
    'ssl_cert_file' => __DIR__ . '/config/ssl.cert',
    'ssl_key_file' => __DIR__ . '/config/ssl.key',
]);

• The web browser must trust the credential before browsing the webpage
• In the WebSocket application, the part starting the connection of WebSocket must use https
• The certificate extensions must be PEM and not DER

Convert PEM to DER openssl x509 -in cert.crt -outform der -out cert.der Convert DER to PEM openssl x509 -in cert.crt -inform der -outform pem -out cert.pem

ssl_method

Set the algorithm of SSL. The algorithm of client and server must be same otherwise the handshake of WebSocket will fail. The default algorithm is SWOOLE_SSLv23_METHOD

<?php
$server->set([
    'ssl_method' => SWOOLE_SSLv3_CLIENT_METHOD, // this configuration is available for the swoole whose version is higher than 1.7.20
]);

task_ipc_mode

Set the communication mode between the task worker process and worker process.

• 1, default mode, use UNIX socket to communicate

• 2, use the message queue to communicate

• 3, use the message queue to communicate and set the mode to competition

the difference between mode 2 and 3 : mode 2 supports the feature of sending task to a specified task worker process by $server->task($data, $task_worker_id) while the mode 3 don't support to specify task worker process.

The message queue uses the memory queue provided by os to store the data.

If the configuration message_queue_key hasn't been set, the message queue would use the private queue and this private queue will be deleted after the close of swoole server.

If the configuration message_queue_key has been set, the data of message queue would not be deleted and the swoole server could get the data after a restart.

Use ipcrm -q message_queue_id to delete the data of message queue

task_max_request

the max number of task worker process could handle.

After handling the number of task_max_request tasks, the task worker process will exit and release all the memory and resource used by this process. And then, the manager will respawn a new task worker process.

The default value of task_max_request is 0 which means there is no limit of the max task request.

task_tmpdir

Set the path of temporary task data.

If the data sent by task exceeds 8192 bytes, the swoole will use the temporary file to store the data.

The default of task_tmpdir is /tmp.

task_worker_num

the number of task worker process.

To enable this parameter, it needs to register the callback function of the task event and finish event.

The task worker process is synchronous and blocking.

According to the speed of sending task and handling task, set a reasonable value of task_worker_num.

tcp_defer_accept

This configuration is to defer the TCP connection to trigger onReceive events before receving data.

<?php
$server->set(array(
  'tcp_defer_accept' => 5
));

user

Set the user of worker and task worker process.

Usage

<?php
$server->set(['user' => 'apache']);

worker_num

The number of worker process

If the code of logic is asynchronous and non-blocking, set the worker_num to the value from one time to four times of CPU cores. If the code of logic is synchronous and blocking, set the worker_num according to the consuming time of request and load of os.

reload_async

By enabling reload_async, the worker processes shutdown after processing all the pending events.

max_wait_time

The max waiting time to restart a worker process.

tcp_fastopen

By enabling tcp_fastopen, send data with SYNC. Check more about tcp_fastopen

request_slowlog_file

Enable slowlog and set the location of log file.

<?php
$server->set([
  'request_slowlog_file' => '/tmp/swoole_slowlog.log',
  'request_slowlog_timeout' => 2,
  'trace_event_worker' => true,
]);

max_coroutine

Set the max coroutine number per worker process.

send_yield

Yield the current task and waiting for I/O if the send buffer is full.

open_tcp_keepalive

TCP level Keep-Alive checking.

<?php
$serv->set(array(
    'worker_num' => 1,
    'open_tcp_keepalive' => 1, // enable TCP Keep-Alive check
    'tcp_keepidle' => 4, // check if there is no data for 4s. 
    'tcp_keepinterval' => 1, // check if there is data every 1s 
    'tcp_keepcount' => 5, //close the connection if there is no data for 5 cycles.
));