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

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

Updated systemd socket endpoint documentation addressing code review comments from thijs

  • doc/core/howto/endpoints.xhtml

    === modified file 'doc/core/howto/endpoints.xhtml'
     
    241241  </li>
    242242</ul>
    243243
     244<h2>Using <code>systemd</code> Server Endpoints</h2>
     245<p>The following example demonstrates how to launch a Twisted web
     246  server using <code>systemd</code> socket activation.</p>
     247<ol>
     248  <li>
     249    <p>Create
     250    a <a href="http://0pointer.de/public/systemd-man/systemd.socket.html"><code>systemd.socket</code></a>
     251    file.</p>
     252
     253    <a href="listings/systemd/twistedweb.socket"
     254    class="listing">/etc/systemd/system/twistedweb.socket</a>
     255
     256    <p>This file configures <code>systemd</code> to listen on an IPv4 address on
     257    port 8080.</p>
     258  </li>
     259
     260  <li>
     261    <p>Create
     262    a <a href="http://0pointer.de/public/systemd-man/systemd.service.html"><code>systemd.service</code></a>
     263    file.</p>
     264
     265    <a href="listings/systemd/twistedweb.service"
     266    class="listing">/etc/systemd/system/twistedweb.service</a>
     267
     268    <p>This configuration file contains the following important
     269    sections:</p>
     270
     271    <dl>
     272      <dt>ExecStart</dt>
     273      <dd>Include the full path to <code>twistd</code> (in this case the path to a
     274        symlink maintained
     275        by <a href="http://twistedmatrix.com/trac/wiki/Combinator">Combinator</a>)</dd>
     276      <dd>The <code>--nodaemon</code> flag makes <code>twistd</code> run in the
     277        foreground. <code>systemd</code> expects child processes to remain in the
     278        foreground.</dd>
     279      <dd>The <code>domain=INET</code> endpoint argument makes <code>twistd</code>
     280        treat the inherited file descriptor as an IPv4 socket.</dd>
     281      <dd>The <code>index=0</code> endpoint argument
     282        makes <code>twistd</code> adopt the first file descriptor
     283        inherited from <code>systemd</code>.</dd>
     284
     285      <dt>Environment</dt>
     286      <dd>In this example, Twisted has been installed
     287        with <a href="http://twistedmatrix.com/trac/wiki/Combinator">Combinator</a>
     288        so the Combinator path is added
     289        to <code>PYTHONPATH</code>.</dd>
     290
     291      <dt>NonBlocking</dt>
     292      <dd>This must be set to <code>true</code> to ensure that the
     293      sockets have the O_NONBLOCK flag set and hence are in
     294      non-blocking mode before they are passed to Twisted.</dd>
     295    </dl>
     296
     297    <p>There are many more service options which are documented in the
     298    <a href="http://0pointer.de/public/systemd-man/systemd.service.html"><code>systemd.service</code>
     299    man page</a>.</p>
     300  </li>
     301  <li>
     302    <p>Reload <code>systemd</code>.</p>
     303    <pre class="shell">
     304      $ sudo systemctl --system daemon-reload
     305    </pre>
     306    <p>This forces <code>systemd</code> to read the new configuration files.</p>
     307  </li>
     308  <li>
     309    <p>Start <code>systemd</code> listening on the new port.</p>
     310    <pre class="shell">
     311      $ sudo systemctl start twistedweb.socket
     312    </pre>
     313
     314    <p><code>systemd</code> should now be listening on port 8080. You can verify
     315     this using the <code>netstat</code> command. eg</p>
     316    <pre class="shell">
     317      $ sudo netstat -lntp | grep 8080
     318      ...
     319      tcp 0 0 127.0.0.1:8080 0.0.0.0:* LISTEN 1/init
     320    </pre>
     321
     322    <p><strong>Note</strong>: <code>twistd</code> will not be started
     323    until the first client connects. You can verify this by searching
     324    the current process list. eg</p>
     325    <pre class="shell">
     326      $ ps -ef | grep twistd
     327      ...
     328      richard   5815  4237  0 01:20 pts/5    00:00:00 grep --color=auto twistd
     329    </pre>
     330  </li>
     331  <li>
     332    <p>Connect to port 8080 using <a href="http://curl.haxx.se/">curl</a>.</p>
     333    <pre class="shell">
     334      $ curl http://localhost:8080
     335    </pre>
     336
     337    <p><code>systemd</code> will accept the connection and
     338    launch <code>twistd</code>, passing it the listening socket. You
     339    can verify this by searching the process list again. eg</p>
     340    <pre class="shell">
     341      $ ps -ef | grep twistd
     342      ...
     343      richard   5831     1  1 01:29 ?        00:00:00 python /home/richard/projects/Twisted/trunk/bin/twistd --nodaemon web --port systemd:domain=INET:index=0 --path .
     344      richard   5836  4237  0 01:29 pts/5    00:00:00 grep --color=auto twistd
     345    </pre>
     346
     347    <p>The <code>twistd</code> subprocess will log messages
     348    to <code>stderr</code> and <code>systemd</code> will in turn log these messages
     349    to syslog. You can verify this by monitoring the syslog messages
     350    using the <code>tail</code> command. eg</p>
     351    <pre class="shell">
     352      $ sudo tail -f /var/log/messages
     353      ...
     354      Log opened.
     355      twistd 12.0.0+r34099 (/usr/bin/python 2.7.2) starting up.
     356      reactor class: twisted.internet.pollreactor.PollReactor.
     357      Site starting on 8080
     358      "GET / HTTP/1.1" 200 - "-" "curl/7.21.7 (x86_64-redhat-linux-gnu) libcurl/7.21.7 NSS/3.13.3.0 zlib/1.2.5 libidn/1.22 libssh2/1.2.7"
     359    </pre>
     360  </li>
     361</ol>
     362
     363<h3>Process Monitoring and Supervision With <code>systemd</code></h3>
     364<p>In addition to launching Twisted on-demand, <code>systemd</code> also provides
     365  process monitoring and supervision.</p>
     366<p>Here is a short demonstration.</p>
     367<ol>
     368  <li>
     369    <p>Kill the <code>twistd</code> process.</p>
     370
     371    <pre class="shell">
     372      $ kill -9 5831
     373    </pre>
     374
     375    <p><code>systemd</code> will log a warning when
     376    the <code>twistd</code> process ends unexpectedly, but it will
     377    continue listening on port 8080.</p>
     378    <pre class="shell">
     379      $ sudo tail -f /var/log/messages
     380      ...
     381      twistedweb.service: main process exited, code=killed, status=9
     382      Unit twistedweb.service entered failed state.
     383    </pre>
     384
     385    <p>It will immediately re-launch <code>twistd</code> when another client
     386    connects to that port.</p>
     387  </li>
     388</ol>
     389
     390
     391<h3>Further Reading</h3>
     392<ul>
     393  <li><a href="http://0pointer.de/blog/projects/systemd-docs.html"><code>systemd</code>
     394  Documentation</a></li>
     395</ul>
    244396</body>
    245397</html>
  • doc/core/howto/listings/systemd/twistedweb.service

    === added directory 'doc/core/howto/listings/systemd'
    === added file 'doc/core/howto/listings/systemd/twistedweb.service'
     
     1[Service]
     2ExecStart=/home/richard/projects/combinator_paths/bincache/twistd --nodaemon \
     3    web --port systemd:domain=INET:index=0 --path /home/richard/www
     4
     5Environment=\
     6    PYTHONPATH=/home/richard/projects/Divmod/trunk/Combinator
     7
     8WorkingDirectory=/home/richard/www
     9
     10User=richard
     11
     12NonBlocking=true
  • doc/core/howto/listings/systemd/twistedweb.socket

    === added file 'doc/core/howto/listings/systemd/twistedweb.socket'
     
     1[Socket]
     2ListenStream=0.0.0.0:8080
     3
     4[Install]
     5WantedBy=sockets.target