Ticket #5601: systemd-howto-5601-3.patch

File systemd-howto-5601-3.patch, 22.3 KB (added by Richard Wall, 9 years ago)

Updated patch

  • doc/core/howto/endpoints.xhtml

    === modified file 'doc/core/howto/endpoints.xhtml'
     
    233233  socket.  lockfile enables use of a separate lock file to prove the server is
    234234  still running.  For example, <code>unix:address=/var/run/web.sock:lockfile=1</code>.
    235235  </li>
    236   <li>systemd.  Supported arguments: domain, index.  domain indicates which
    237   socket domain the inherited file descriptor belongs to (eg INET, INET6).
    238   index indicates an offset into the array of file descriptors which have been
    239   inherited from systemd.  For
    240   example, <code>systemd:domain=INET6:index=3</code>.
     236  <li>systemd.  Supported arguments: domain, index.  domain indicates
     237  which socket domain the inherited file descriptor belongs to (eg
     238  INET, INET6).  index indicates an offset into the array of file
     239  descriptors which have been inherited from systemd.  For
     240  example, <code>systemd:domain=INET6:index=3</code>. See
     241  also <a href="systemd.xhtml">Deploying Twisted with systemd</a>.
    241242  </li>
    242243</ul>
    243 
    244244</body>
    245245</html>
  • doc/core/howto/index.xhtml

    === modified file 'doc/core/howto/index.xhtml'
     
    159159        <li><a href="tap.xhtml">Writing Twisted Application Plugins
    160160        for twistd</a><br />
    161161            More powerful <code>twistd</code> deployment method.</li>
     162
     163        <li><a href="systemd.xhtml">Deploying Twisted with
     164            systemd</a><br /> Use <code>systemd</code> to launch and
     165            monitor Twisted applications</li>
    162166      </ul>
    163167    </li>
    164168
  • doc/core/howto/listings/systemd/www.example.com.socket

    === added directory 'doc/core/howto/listings/systemd'
    === added file 'doc/core/howto/listings/systemd/www.example.com.socket'
     
     1[Socket]
     2ListenStream=0.0.0.0:80
     3
     4[Install]
     5WantedBy=sockets.target
  • doc/core/howto/listings/systemd/www.example.com.socketactivated.service

    === added file 'doc/core/howto/listings/systemd/www.example.com.socketactivated.service'
     
     1[Unit]
     2Description=Example Web Server
     3
     4[Service]
     5ExecStart=/usr/bin/twistd \
     6    --nodaemon \
     7    --pidfile= \
     8    web --port systemd:domain=INET:index=0 --path .
     9
     10NonBlocking=true
     11
     12WorkingDirectory=/srv/www/www.example.com/static
     13
     14User=nobody
     15Group=nobody
     16
     17Restart=always
  • doc/core/howto/listings/systemd/www.example.com.static.service

    === added file 'doc/core/howto/listings/systemd/www.example.com.static.service'
     
     1[Unit]
     2Description=Example Web Server
     3
     4[Service]
     5ExecStart=/usr/bin/twistd \
     6    --nodaemon \
     7    --pidfile= \
     8    web --port 8080 --path .
     9
     10WorkingDirectory=/srv/www/www.example.com/static
     11
     12User=nobody
     13Group=nobody
     14
     15Restart=always
     16
     17[Install]
     18WantedBy=multi-user.target
  • doc/core/howto/systemd.xhtml

    === added file 'doc/core/howto/systemd.xhtml'
     
     1<?xml version="1.0" encoding="utf-8"?>
     2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     3    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
     4
     5<html xmlns="http://www.w3.org/1999/xhtml">
     6  <head>
     7    <meta charset="utf-8" />
     8    <title>Deploying Twisted with systemd</title>
     9  </head>
     10
     11<body>
     12<h1>Deploying Twisted with <code>systemd</code></h1>
     13
     14<h2>Introduction</h2>
     15
     16<p>In this tutorial you will learn how to start a Twisted service
     17  using <code>systemd</code>.</p>
     18
     19<p>You will also learn how to start the service using <code>socket
     20  activation</code>.</p>
     21
     22<div class="note">
     23  <p>The examples in this tutorial demonstrate how to
     24    launch a Twisted web server, but the same techniques apply to any
     25    Twisted service.</p>
     26</div>
     27
     28<h2>Prerequisites</h2>
     29<dl>
     30  <dt>Twisted</dt>
     31  <dd>You will need a version of Twisted >= 12.2 for the socket
     32    activation section of this tutorial.</dd>
     33  <dd>This tutorial was written on a Fedora 18 Linux operating system
     34    with a system wide installation of Twisted and Twisted Web.</dd>
     35  <dd>If you have installed Twisted locally eg in your home directory
     36    or in a virtualenv, you will need to modify the paths in some of
     37    the following examples.</dd>
     38  <dd>
     39    <p>Test your Twisted installation by starting a <code>twistd
     40      web</code> server on TCP port 8080 with the following
     41      command:</p>
     42    <pre class="shell">
     43$ twistd --nodaemon web --port 8080 --path /srv/www/www.example.com/static
     442013-01-28 13:21:35+0000 [-] Log opened.
     452013-01-28 13:21:35+0000 [-] twistd 12.3.0 (/usr/bin/python 2.7.3) starting up.
     462013-01-28 13:21:35+0000 [-] reactor class: twisted.internet.epollreactor.EPollReactor.
     472013-01-28 13:21:35+0000 [-] Site starting on 8080
     482013-01-28 13:21:35+0000 [-] Starting factory &lt;twisted.web.server.Site instance at 0x7f57eb66efc8&gt;
     49    </pre>
     50    <p>This assumes that you have the following static web page in the
     51      following directory structure:</p>
     52    <pre class="shell">
     53# tree /srv/
     54/srv/
     55└── www
     56    └── www.example.com
     57        └── static
     58            └── index.html
     59    </pre>
     60    <pre class="html">
     61&lt;!doctype html&gt;
     62&lt;html lang=en&gt;
     63  &lt;head&gt;
     64    &lt;meta charset=utf-8&gt;
     65    &lt;title&gt;Example Site&lt;/title&gt;
     66  &lt;/head&gt;
     67  &lt;body&gt;
     68    &lt;h1&gt;Example Site&lt;/h1&gt;
     69  &lt;/body&gt;
     70&lt;/html&gt;
     71    </pre>
     72
     73    <p>Now try connecting
     74      to <a href="http://localhost:8080">http://localhost:8080</a> in
     75      your web browser.</p>
     76    <p>If you do not see your web page or if <code>twistd</code> didn't start, you
     77      should investigate and fix the problem before continuing.</p>
     78  </dd>
     79</dl>
     80
     81<h2>Basic Systemd Service Configuration</h2>
     82<p>The essential configuration file for a <code>systemd</code> service is the
     83  <a href="http://0pointer.de/public/systemd-man/systemd.service.html"><code>systemd.service</code></a>
     84  file.</p>
     85<p>Later in this tutorial, you will learn about some other types of
     86  configuration file, which are used to control when and how your
     87  service is started.</p>
     88<p>But we will begin by configuring <code>systemd</code> to start a Twisted web
     89  server immediately on system boot.</p>
     90<ol>
     91  <li>
     92    <h3>Create
     93      a <a href="http://0pointer.de/public/systemd-man/systemd.service.html"><code>systemd.service</code></a>
     94      file</h3>
     95    <p>Create the service file
     96      at <code>/etc/systemd/system/www.example.com.service</code> with
     97      the following content:</p>
     98    <a href="listings/systemd/www.example.com.static.service"
     99    class="listing">/etc/systemd/system/www.example.com.service</a>
     100
     101    <p>This configuration file contains the following note worthy
     102      sections:</p>
     103
     104    <dl>
     105      <dt>ExecStart</dt>
     106      <dd>Always include the full path to <code>twistd</code> in case
     107        you have multiple versions installed.</dd>
     108      <dd>The <code>--nodaemon</code> flag makes <code>twistd</code>
     109        run in the foreground. Systemd works best with child processes
     110        that remain in the foreground.</dd>
     111      <dd>The <code>--pidfile=</code> flag
     112        prevents <code>twistd</code> from writing a pidfile. A pidfile
     113        is not necessary when Twisted runs as a foreground
     114        process.</dd>
     115      <dd>The <code>--path</code> flag to specifies the location of
     116        the website files. In this example we use <q>.</q> which
     117        makes <code>twistd</code> serve files from its current working
     118        directory (see below).</dd>
     119
     120      <dt>WorkingDirectory</dt>
     121      <dd>Systemd can configure the working environment of its child
     122        processes.</dd>
     123      <dd>In this example the working directory of <code>twistd</code>
     124        is set to that of the static website.</dd>
     125
     126      <dt>User / Group</dt>
     127      <dd>Systemd can also control the effective user and group of its
     128        child processes.</dd>
     129      <dd>This example uses an un-privileged user <q>nobody</q> and
     130        un-privileged group <q>nobody</q>.</dd>
     131      <dd>This is an important security measure which ensures that the
     132        Twisted sub-process can not access restricted areas of the
     133        file system.</dd>
     134
     135      <dt>Restart</dt>
     136      <dd>Systemd can automatically restart a child process if it
     137        exits or crashes unexpectedly.</dd>
     138      <dd>In this example the <code>Restart</code> option is set
     139        to <code>always</code>, which ensures that <code>twistd</code> will be
     140        restarted under all circumstances.</dd>
     141    </dl>
     142
     143    <p>There are many more service options which are documented in the
     144    <a href="http://0pointer.de/public/systemd-man/systemd.service.html"><code>systemd.service</code>
     145      man page</a>.</p>
     146  </li>
     147
     148  <li>
     149    <h3>Reload <code>systemd</code></h3>
     150    <pre class="shell">
     151$ sudo systemctl daemon-reload
     152    </pre>
     153    <p>This forces <code>systemd</code> to read the new configuration
     154      file.</p>
     155    <p class="note">Always run <code>systemctl daemon-reload</code>
     156      after changing any of the <code>systemd</code> configuration files.</p>
     157  </li>
     158  <li>
     159    <h3>Start the service</h3>
     160    <pre class="shell">
     161$ sudo systemctl start www.example.com
     162    </pre>
     163
     164    <p><code>twistd</code> should now be running and listening on TCP
     165      port 8080. You can verify this using the <code>systemctl</code>
     166      command. eg</p>
     167    <pre class="shell">
     168$ sudo systemctl status www.example.com.service
     169www.example.com.service - Example Web Server
     170          Loaded: loaded (/etc/systemd/system/www.example.com.service; enabled)
     171          Active: active (running) since Mon 2013-01-28 16:16:26 GMT; 1s ago
     172        Main PID: 10695 (twistd)
     173          CGroup: name=systemd:/system/www.example.com.service
     174                  └─10695 /usr/bin/python /usr/bin/twistd --nodaemon --pidfile= web --port 8080 --path .
     175
     176Jan 28 16:16:26 zorin.lan systemd[1]: Starting Example Web Server...
     177Jan 28 16:16:26 zorin.lan systemd[1]: Started Example Web Server.
     178Jan 28 16:16:26 zorin.lan twistd[10695]: 2013-01-28 16:16:26+0000 [-] Log opened.
     179Jan 28 16:16:26 zorin.lan twistd[10695]: 2013-01-28 16:16:26+0000 [-] twistd 12.1.0 (/usr/bin/python 2.7.3) starting up.
     180Jan 28 16:16:26 zorin.lan twistd[10695]: 2013-01-28 16:16:26+0000 [-] reactor class: twisted.internet.epollreactor.EPollReactor.
     181Jan 28 16:16:26 zorin.lan twistd[10695]: 2013-01-28 16:16:26+0000 [-] Site starting on 8080
     182Jan 28 16:16:26 zorin.lan twistd[10695]: 2013-01-28 16:16:26+0000 [-] Starting factory &lt;twisted.web.server.Site instance at 0x159b758&gt;
     183    </pre>
     184    <p>The <code>systemctl status</code> command is convenient because
     185      it shows you both the current status of the service and a short
     186      log of the service output.</p>
     187    <p>This is especially useful for debugging and diagnosing service
     188      startup problems.</p>
     189    <p>The <code>twistd</code> subprocess will log messages
     190      to <code>stderr</code> and <code>systemd</code> will in turn log
     191      these messages to syslog. You can verify this by monitoring the
     192      syslog messages or by using the new <code>journalctl</code> tool
     193      in Fedora.</p>
     194    <p>See
     195      the <a href="http://0pointer.de/public/systemd-man/systemctl.html"><code>systemctl</code>
     196      man page</a> for details of the service available options.</p>
     197  </li>
     198  <li>
     199    <h3>Enable the service</h3>
     200    <p>We've seen how to start the service manually, but now we need
     201      to <q>enable</q> it so that it starts automatically at boot
     202      time.</p>
     203    <p>Enable the service with the following command:</p>
     204    <pre class="shell">
     205$ sudo systemctl enable www.example.com.service
     206ln -s '/etc/systemd/system/www.example.com.service' '/etc/systemd/system/multi-user.target.wants/www.example.com.service'
     207    </pre>
     208    <p>As you can see, this creates a symlink to the service file in
     209      the <code>systemd</code> multi-user target directory.</p>
     210    <p>The Twisted web server will now be started automatically at
     211      boot time.</p>
     212    <p class="note">The default <code>systemd</code> boot <code>target</code>
     213      is <q>multi-user</q>. Later in this tutorial you will learn how
     214      to use the <q>sockets</q> target.</p>
     215  </li>
     216
     217  <li>
     218    <h3>Test that the service is automatically restarted</h3>
     219    <p>The <code>Restart=always</code> option in
     220      the <code>systemd.service</code> file ensures that <code>systemd</code> will
     221      restart the <code>twistd</code> process if and when it exits
     222      unexpectedly.</p>
     223    <p>You can read about other <code>Restart</code> options in
     224      the <a href="http://0pointer.de/public/systemd-man/systemd.service.html"><code>systemd.service</code>
     225      man page.</a></p>
     226    <p>Try killing the <code>twistd</code> process and then checking its status
     227      again:</p>
     228    <pre class="shell">
     229$ sudo kill 12543
     230
     231$ sudo systemctl status www.example.com.service
     232www.example.com.service - Example Web Server
     233          Loaded: loaded (/etc/systemd/system/www.example.com.service; disabled)
     234          Active: active (running) since Mon 2013-01-28 17:47:37 GMT; 1s ago
     235        Main PID: 12611 (twistd)
     236    </pre>
     237    <p>The <q>Active</q> time stamp shows that the <code>twistd</code> process was
     238      restarted within 1 second.</p>
     239  </li>
     240
     241  <li>
     242    <p>Now stop the service before you proceed to the next
     243      section.</p>
     244    <pre class="shell">
     245$ sudo systemctl stop www.example.com.service
     246
     247$ sudo systemctl status www.example.com.service
     248www.example.com.service - Example Web Server
     249          Loaded: loaded (/etc/systemd/system/www.example.com.service; enabled)
     250          Active: inactive (dead) since Mon 2013-01-28 16:51:12 GMT; 1s ago
     251         Process: 10695 ExecStart=/usr/bin/twistd --nodaemon --pidfile= web --port 8080 --path . (code=exited, status=0/SUCCESS)
     252    </pre>
     253  </li>
     254</ol>
     255
     256<h2>Socket Activation</h2>
     257<p>First you need to understand what <q>socket activation</q> is. This
     258  extract from
     259  the <a href="http://www.0pointer.de/public/systemd-man/daemon.html">systemd
     260  daemon man page</a> explains it clearly.</p>
     261<blockquote>
     262  In a socket-based activation scheme the creation and binding of the
     263  listening socket as primary communication channel of daemons to
     264  local (and sometimes remote) clients is moved out of the daemon code
     265  and into the init system. Based on per-daemon configuration the init
     266  system installs the sockets and then hands them off to the spawned
     267  process as soon as the respective daemon is to be
     268  started. Optionally activation of the service can be delayed until
     269  the first inbound traffic arrives at the socket, to implement
     270  on-demand activation of daemons. However, the primary advantage of
     271  this scheme is that all providers and all consumers of the sockets
     272  can be started in parallel as soon as all sockets are
     273  established. In addition to that daemons can be restarted with
     274  losing only a minimal number of client transactions or even any
     275  client request at all (the latter is particularly true for
     276  state-less protocols, such as DNS or syslog), because the socket
     277  stays bound and accessible during the restart, and all requests are
     278  queued while the daemon cannot process them.
     279</blockquote>
     280<p>Twisted (since version 12.2) includes
     281  a <a href="endpoints.html"><code>systemd</code> endpoint API and a corresponding
     282  string ports syntax</a>, which allows a Twisted service to inherit a
     283  listening socket from <code>systemd</code>.</p>
     284<p>The following example builds on the previous example, demonstrating
     285  how to enable socket activation for a simple Twisted web server.</p>
     286<div class="note">
     287  <p>Before continuing, stop the previous example service with the
     288    following command:</p>
     289
     290  <pre class="shell">
     291$ sudo systemctl stop www.example.com.service
     292  </pre>
     293</div>
     294
     295<ol>
     296  <li>
     297    <h3>Create
     298      a <a href="http://0pointer.de/public/systemd-man/systemd.socket.html"><code>systemd.socket</code></a>
     299      file</h3>
     300    <p>Create the socket file
     301      at <code>/etc/systemd/system/www.example.com.socket</code> with
     302      the following content:</p>
     303    <a href="listings/systemd/www.example.com.socket"
     304       class="listing">/etc/systemd/system/www.example.com.socket</a>
     305
     306    <p>This configuration file contains the following important
     307      sections:</p>
     308    <dl>
     309      <dt>ListenStream=0.0.0.0:80</dt>
     310      <dd>This option configures <code>systemd</code> to create a
     311        listening TCP socket bound to all local IPv4 addresses on port
     312        80.</dd>
     313      <dt>WantedBy=sockets.target</dt>
     314      <dd>This is a special target used by all socket activated
     315        services. <code>systemd</code> will automatically bind to all
     316        such socket activation ports during boot up.</dd>
     317    </dl>
     318
     319    <p>You also need to modify the <code>systemd.service</code> file as
     320    follows:</p>
     321    <a href="listings/systemd/www.example.com.socketactivated.service"
     322       class="listing">/etc/systemd/system/www.example.com.service</a>
     323    <p>Notice the following important changes:</p>
     324    <dl>
     325      <dt>ExecStart</dt>
     326      <dd>The <code>domain=INET</code> endpoint argument makes <code>twistd</code>
     327        treat the inherited file descriptor as an IPv4 socket.</dd>
     328      <dd>The <code>index=0</code> endpoint argument
     329        makes <code>twistd</code> adopt the first file descriptor
     330        inherited from <code>systemd</code>.</dd>
     331      <dd class="note">Socket activation is also technically possible
     332        with other socket families and types, but Twisted currently
     333        only accepts IPv4 and IPv6 TCP
     334        sockets. See <a href="#limitations">limitations</a>
     335        below.</dd>
     336
     337      <dt>NonBlocking</dt>
     338      <dd>This must be set to <code>true</code> to ensure that <code>systemd</code>
     339        passes non-blocking sockets to Twisted.</dd>
     340    </dl>
     341    <p>Reload <code>systemd</code> so that it reads the updated
     342      configuration files.</p>
     343    <pre class="shell">
     344$ sudo systemctl daemon-reload
     345    </pre>
     346  </li>
     347
     348  <li>
     349    <h3>Start and enable the socket</h3>
     350    <p>You can now start <code>systemd</code> listening on the socket with the
     351      following command:</p>
     352    <pre class="shell">
     353$ sudo systemctl start www.example.com.socket
     354    </pre>
     355    <p class="note">This command refers specifically to the socket
     356    configuration file, <strong>not</strong> the service file.</p>
     357    <p><code>systemd</code> should now be listening on port 80</p>
     358    <pre class="shell">
     359$ sudo systemctl status www.example.com.socket
     360www.example.com.socket
     361          Loaded: loaded (/etc/systemd/system/www.example.com.socket; disabled)
     362          Active: active (listening) since Tue 2013-01-29 14:53:17 GMT; 7s ago
     363
     364Jan 29 14:53:17 zorin.lan systemd[1]: Listening on www.example.com.socket.
     365    </pre>
     366
     367    <p>But <code>twistd</code> should not yet have started. You can verify this
     368      using the <code>systemctl</code> command. eg</p>
     369    <pre class="shell">
     370$ sudo systemctl status www.example.com.service
     371www.example.com.service - Example Web Server
     372          Loaded: loaded (/etc/systemd/system/www.example.com.service; static)
     373          Active: inactive (dead) since Tue 2013-01-29 14:48:42 GMT; 6min ago
     374    </pre>
     375
     376    <p>Enable the socket, so that it will be started automatically
     377      with the other socket activated services during boot up.</p>
     378    <pre class="shell">
     379$ sudo systemctl enable www.example.com.socket
     380ln -s '/etc/systemd/system/www.example.com.socket' '/etc/systemd/system/sockets.target.wants/www.example.com.socket'
     381    </pre>
     382  </li>
     383  <li>
     384    <h3>Activate the port, start the service</h3>
     385
     386    <p>Now try connecting
     387      to <a href="http://localhost:80">http://localhost:80</a> in
     388      your web browser.</p>
     389
     390    <p><code>systemd</code> will accept the connection and
     391      start <code>twistd</code>, passing it the listening socket. You
     392      can verify this by using systemctl to report the status of the
     393      service.. eg</p>
     394    <pre class="shell">
     395$ sudo systemctl status www.example.com.service
     396www.example.com.service - Example Web Server
     397          Loaded: loaded (/etc/systemd/system/www.example.com.service; static)
     398          Active: active (running) since Tue 2013-01-29 15:02:20 GMT; 3s ago
     399        Main PID: 25605 (twistd)
     400          CGroup: name=systemd:/system/www.example.com.service
     401                  └─25605 /usr/bin/python /usr/bin/twistd --nodaemon --pidfile= web --port systemd:domain=INET:index=0 --path .
     402
     403Jan 29 15:02:20 zorin.lan systemd[1]: Started Example Web Server.
     404Jan 29 15:02:20 zorin.lan twistd[25605]: 2013-01-29 15:02:20+0000 [-] Log opened.
     405Jan 29 15:02:20 zorin.lan twistd[25605]: 2013-01-29 15:02:20+0000 [-] twistd 12.1.0 (/usr/bin/python 2.7.3) starting up.
     406Jan 29 15:02:20 zorin.lan twistd[25605]: 2013-01-29 15:02:20+0000 [-] reactor class: twisted.internet.epollreactor.EPollReactor.
     407Jan 29 15:02:20 zorin.lan twistd[25605]: 2013-01-29 15:02:20+0000 [-] Site starting on 80
     408Jan 29 15:02:20 zorin.lan twistd[25605]: 2013-01-29 15:02:20+0000 [-] Starting factory &lt;twisted.web.server.Site instance at 0x24be758&gt;
     409    </pre>
     410  </li>
     411</ol>
     412
     413<h2>Conclusion</h2>
     414<p>In this tutorial you have learned how to deploy a Twisted service
     415  using <code>systemd</code>. You have also learned how the service can be started
     416  on demand, using socket activation</p>
     417
     418<h2 id="limitations">Limitations and Known Issues</h2>
     419<ol>
     420  <li>Twisted can not accept UNIX or datagram sockets
     421    from <code>systemd</code>.</li>
     422  <li>Twisted does not support listening for SSL connections on
     423    sockets inherited from <code>systemd</code>.</li>
     424</ol>
     425<h2>Further Reading</h2>
     426<ul>
     427  <li><a href="http://0pointer.de/blog/projects/systemd-docs.html"><code>systemd</code>
     428      Documentation</a></li>
     429</ul>
     430</body>
     431</html>
  • twisted/topfiles/5601.feature

    === added file 'twisted/topfiles/5601.feature'
     
     1A new "Deploying Twisted with systemd" howto document which
     2demonstrates how to start a Twisted service using systemd socket
     3activation.