docs/DAEMON_SOCKET_ACTIVATION.md

   1 ---
   2 title: Socket Activation with Popular Daemons
   3 category: Manuals and Documentation for Users and Administrators
   4 layout: default
   5 SPDX-License-Identifier: LGPL-2.1-or-later
   6 ---
   7
   8 ## nginx
   9
  10 nginx includes an undocumented, internal socket-passing mechanism based on the `NGINX` environmental variable. It uses this to perform reloads without having to close and reopen its sockets, but it's also useful for socket activation.
  11
  12 **/etc/nginx/my-nginx.conf**
  13
  14 ```
  15 http {
  16   server {
  17     listen [::]:80 ipv6only=on;
  18     listen 80;
  19   }
  20 }
  21 ```
  22
  23 **/etc/systemd/system/my-nginx.service**
  24
  25 ```
  26 [Service]
  27 User=nginx
  28 Group=nginx
  29 Environment=NGINX=3:4;
  30 ExecStart=/usr/sbin/nginx -c/etc/nginx/my-nginx.conf
  31 PrivateNetwork=true
  32 ```
  33
  34
  35 **/etc/systemd/system/my-nginx.socket**
  36
  37 ```
  38 [Unit]
  39 After=network.target
  40 Requires=network.target
  41
  42 [Socket]
  43 ListenStream=80
  44 ListenStream=0.0.0.0:80
  45 BindIPv6Only=ipv6-only
  46
  47 [Install]
  48 WantedBy=sockets.target
  49 ```
  50
  51
  52 ## PHP-FPM
  53
  54 Like nginx, PHP-FPM includes a socket-passing mechanism an environmental variable. In PHP-FPM's case, it's `FPM_SOCKETS`.
  55
  56 This configuration is possible with any web server that supports FastCGI (like Apache, Lighttpd, or nginx). The web server does not need to know anything special about the socket; use a normal PHP-FPM configuration.
  57
  58 Paths are based on a Fedora 19 system.
  59
  60 ### First, the configuration files
  61
  62 **/etc/php-fpm.d/my-php-fpm-pool.conf**
  63
  64 ```
  65 [global]
  66 pid = /run/my-php-fpm-pool.pid ; Not really used by anything with daemonize = no, but needs to be writable.
  67 error_log = syslog             ; Will aggregate to the service's systemd journal.
  68 daemonize = no                 ; systemd handles the forking.
  69
  70 [www]
  71 listen = /var/run/my-php-fpm-pool.socket  ; Must match systemd socket unit.
  72 user = nginx ; Ignored but required.
  73 group = nginx ; Ignored but required.
  74 pm = static
  75 pm.max_children = 10
  76 slowlog = syslog
  77 ```
  78
  79
  80 **/etc/systemd/system/my-php-fpm-pool.service**
  81
  82 ```
  83 [Service]
  84 User=nginx
  85 Group=nginx
  86 Environment="FPM_SOCKETS=/var/run/my-php-fpm-pool.socket=3"
  87 ExecStart=/usr/sbin/php-fpm --fpm-config=/etc/php-fpm.d/my-php-fpm-pool.conf
  88 KillMode=process
  89 ```
  90
  91
  92 **/etc/systemd/system/my-php-fpm-pool.socket**
  93
  94 ```
  95 [Socket]
  96 ListenStream=/var/run/my-php-fpm-pool.socket
  97
  98 [Install]
  99 WantedBy=sockets.target
 100 ```
 101
 102
 103 ### Second, the setup commands
 104
 105 ```sh
 106 sudo systemctl --system daemon-reload
 107 sudo systemctl start my-php-fpm-pool.socket
 108 sudo systemctl enable my-php-fpm-pool.socket
 109 ```
 110
 111
 112 After accessing the web server, the service should be running.
 113
 114 ```sh
 115 sudo systemctl status my-php-fpm-pool.service
 116 ```
 117
 118
 119 It's possible to shut down the service and re-activate it using the web browser, too. It's necessary to stop and start the socket to reset some shutdown PHP-FPM does that otherwise breaks reactivation.
 120
 121 ```sh
 122 sudo systemctl stop my-php-fpm-pool.socket my-php-fpm-pool.service
 123 sudo systemctl start my-php-fpm-pool.socket
 124 ```