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

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

Updated patch against source:branches/systemd-howto-5601 addressing code review comments in #comment:8

  • doc/core/howto/listings/systemd/twistedweb.service

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

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

    === modified file 'doc/core/howto/systemd.xhtml'
     
    8080
    8181<h2>Basic Systemd Service Configuration</h2>
    8282<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>
     83  <a href="http://www.freedesktop.org/software/systemd/man/systemd.service.html"><code>systemd.service</code></a>
    8484  file.</p>
    8585<p>Later in this tutorial, you will learn about some other types of
    8686  configuration file, which are used to control when and how your
     
    8989  server immediately on system boot.</p>
    9090<ol>
    9191  <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>
     92    <h3>Create a systemd.service file</h3>
     93    <p>Create
     94      the <a href="http://www.freedesktop.org/software/systemd/man/systemd.service.html"><code>systemd.service</code></a>
     95      file at <code>/etc/systemd/system/www.example.com.service</code>
     96      with the following content:</p>
    9897    <a href="listings/systemd/www.example.com.static.service"
    9998    class="listing">/etc/systemd/system/www.example.com.service</a>
    10099
    101100    <p>This configuration file contains the following note worthy
    102       sections:</p>
     101      directives:</p>
    103102
    104103    <dl>
    105104      <dt>ExecStart</dt>
     
    112111        prevents <code>twistd</code> from writing a pidfile. A pidfile
    113112        is not necessary when Twisted runs as a foreground
    114113        process.</dd>
    115       <dd>The <code>--path</code> flag to specifies the location of
     114      <dd>The <code>--path</code> flag specifies the location of
    116115        the website files. In this example we use <q>.</q> which
    117116        makes <code>twistd</code> serve files from its current working
    118117        directory (see below).</dd>
     
    138137      <dd>In this example the <code>Restart</code> option is set
    139138        to <code>always</code>, which ensures that <code>twistd</code> will be
    140139        restarted under all circumstances.</dd>
     140
     141      <dt>WantedBy</dt>
     142      <dd>Systemd service dependencies are controlled by
     143        <code>WantedBy</code> and <code>RequiredBy</code> directives
     144        in the <code>[Install]</code> section of configuration
     145        file.</dd>
     146      <dd>The <a href="http://www.freedesktop.org/software/systemd/man/systemd.special.html">special
     147        <code>multi-user.target</code></a> is used in this example so
     148        that <code>systemd</code> starts the <code>twistd web</code>
     149        service when it reaches the multi-user stage of the boot
     150        sequence.</dd>
    141151    </dl>
    142152
    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>
     153    <p>There are many more service directives which are documented in the
     154      <a href="http://www.freedesktop.org/software/systemd/man/systemd.directives.html"><code>systemd.directives
     155      man page</code></a>.</p>
    146156  </li>
    147157
    148158  <li>
     
    162172    </pre>
    163173
    164174    <p><code>twistd</code> should now be running and listening on TCP
    165       port 8080. You can verify this using the <code>systemctl</code>
     175      port 8080. You can verify this using the <code>systemctl status</code>
    166176      command. eg</p>
    167177    <pre class="shell">
    168 $ sudo systemctl status www.example.com.service
     178$ systemctl status www.example.com.service
    169179www.example.com.service - Example Web Server
    170180          Loaded: loaded (/etc/systemd/system/www.example.com.service; enabled)
    171181          Active: active (running) since Mon 2013-01-28 16:16:26 GMT; 1s ago
     
    187197    <p>This is especially useful for debugging and diagnosing service
    188198      startup problems.</p>
    189199    <p>The <code>twistd</code> subprocess will log messages
    190       to <code>stderr</code> and <code>systemd</code> will in turn log
     200      to <code>stderr</code> and <code>systemd</code> will log
    191201      these messages to syslog. You can verify this by monitoring the
    192202      syslog messages or by using the new <code>journalctl</code> tool
    193203      in Fedora.</p>
    194204    <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>
     205      the <a href="http://www.freedesktop.org/software/systemd/man/systemctl.html"><code>systemctl</code>
     206      man page</a> for details of other <code>systemctl</code> command
     207      line options.</p>
    197208  </li>
    198209  <li>
    199210    <h3>Enable the service</h3>
     
    205216$ sudo systemctl enable www.example.com.service
    206217ln -s '/etc/systemd/system/www.example.com.service' '/etc/systemd/system/multi-user.target.wants/www.example.com.service'
    207218    </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>
     219    <p>This creates a symlink to the service file in
     220      the <code>multi-user.target.wants</code> directory.</p>
    210221    <p>The Twisted web server will now be started automatically at
    211222      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>
     223    <p class="note">The <code>multi-user.target</code> is an example
     224      of
     225      a <a href="http://www.freedesktop.org/software/systemd/man/systemd.special.html"><q>special</q>
     226      systemd unit</a>. Later in this tutorial you will learn how to
     227      use another special unit - the <code>sockets.target</code>.</p>
    215228  </li>
    216229
    217230  <li>
     
    221234      restart the <code>twistd</code> process if and when it exits
    222235      unexpectedly.</p>
    223236    <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>
     237      the <a href="http://www.freedesktop.org/software/systemd/man/systemd.service.html"><code>systemd.service</code>
    225238      man page.</a></p>
    226239    <p>Try killing the <code>twistd</code> process and then checking its status
    227240      again:</p>
    228241    <pre class="shell">
    229242$ sudo kill 12543
    230243
    231 $ sudo systemctl status www.example.com.service
     244$ systemctl status www.example.com.service
    232245www.example.com.service - Example Web Server
    233246          Loaded: loaded (/etc/systemd/system/www.example.com.service; disabled)
    234247          Active: active (running) since Mon 2013-01-28 17:47:37 GMT; 1s ago
     
    244257    <pre class="shell">
    245258$ sudo systemctl stop www.example.com.service
    246259
    247 $ sudo systemctl status www.example.com.service
     260$ systemctl status www.example.com.service
    248261www.example.com.service - Example Web Server
    249262          Loaded: loaded (/etc/systemd/system/www.example.com.service; enabled)
    250263          Active: inactive (dead) since Mon 2013-01-28 16:51:12 GMT; 1s ago
     
    256269<h2>Socket Activation</h2>
    257270<p>First you need to understand what <q>socket activation</q> is. This
    258271  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>
     272  the <a href="http://www.freedesktop.org/software/systemd/man/daemon.html">systemd
     273  daemon man page</a> explains it quite clearly.</p>
     274
     275<blockquote>In a socket-based activation scheme the creation and
     276  binding of the listening socket as primary communication channel of
     277  daemons to local (and sometimes remote) clients is moved out of the
     278  daemon code and into the init system.</blockquote>
     279
     280<blockquote>Based on per-daemon configuration the init system installs
     281  the sockets and then hands them off to the spawned process as soon
     282  as the respective daemon is to be started.</blockquote>
     283
     284<blockquote>Optionally activation of the service can be delayed until the first
     285  inbound traffic arrives at the socket, to implement on-demand
     286  activation of daemons.</blockquote>
     287
     288<blockquote>However, the primary advantage of this scheme is that all providers
     289  and all consumers of the sockets can be started in parallel as soon
     290  as all sockets are established.</blockquote>
     291
     292<blockquote>In addition to that daemons can be restarted with losing only a
     293  minimal number of client transactions or even any client request at
     294  all (the latter is particularly true for state-less protocols, such
     295  as DNS or syslog), because the socket stays bound and accessible
     296  during the restart, and all requests are queued while the daemon
     297  cannot process them.</blockquote>
     298
     299<p>Another benefit of socket activation is that <code>systemd</code>
     300  can listen on privileged ports and start Twisted with privileges
     301  already dropped. This allows a Twisted service to be configured
     302  and restarted by a non-root user.</p>
     303
    280304<p>Twisted (since version 12.2) includes
    281305  a <a href="endpoints.html"><code>systemd</code> endpoint API and a corresponding
    282306  string ports syntax</a>, which allows a Twisted service to inherit a
    283307  listening socket from <code>systemd</code>.</p>
    284308<p>The following example builds on the previous example, demonstrating
    285309  how to enable socket activation for a simple Twisted web server.</p>
     310
    286311<div class="note">
    287312  <p>Before continuing, stop the previous example service with the
    288313    following command:</p>
     
    294319
    295320<ol>
    296321  <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>
     322    <h3>Create a systemd.socket file</h3>
     323    <p>Create
     324      the <a href="http://www.freedesktop.org/software/systemd/man/systemd.socket.html"><code>systemd.socket</code></a>
     325      file at <code>/etc/systemd/system/www.example.com.socket</code>
     326      with the following content:</p>
    303327    <a href="listings/systemd/www.example.com.socket"
    304328       class="listing">/etc/systemd/system/www.example.com.socket</a>
    305329
    306330    <p>This configuration file contains the following important
    307       sections:</p>
     331      directives:</p>
    308332    <dl>
    309333      <dt>ListenStream=0.0.0.0:80</dt>
    310334      <dd>This option configures <code>systemd</code> to create a
    311335        listening TCP socket bound to all local IPv4 addresses on port
    312336        80.</dd>
    313337      <dt>WantedBy=sockets.target</dt>
    314       <dd>This is a special target used by all socket activated
     338      <dd>This is
     339        a <a href="http://www.freedesktop.org/software/systemd/man/systemd.special.html">special
     340        target</a> used by all socket activated
    315341        services. <code>systemd</code> will automatically bind to all
    316342        such socket activation ports during boot up.</dd>
    317343    </dl>
     
    320346    follows:</p>
    321347    <a href="listings/systemd/www.example.com.socketactivated.service"
    322348       class="listing">/etc/systemd/system/www.example.com.service</a>
    323     <p>Notice the following important changes:</p>
     349    <p>Note the following important directives and changes:</p>
    324350    <dl>
    325351      <dt>ExecStart</dt>
    326352      <dd>The <code>domain=INET</code> endpoint argument makes <code>twistd</code>
     
    337363      <dt>NonBlocking</dt>
    338364      <dd>This must be set to <code>true</code> to ensure that <code>systemd</code>
    339365        passes non-blocking sockets to Twisted.</dd>
     366
     367      <dt><del>[Install]</del></dt>
     368      <dd>In this example, the <code>[Install]</code> section has been
     369        moved to the socket configuration file.</dd>
    340370    </dl>
    341371    <p>Reload <code>systemd</code> so that it reads the updated
    342372      configuration files.</p>
     
    356386    configuration file, <strong>not</strong> the service file.</p>
    357387    <p><code>systemd</code> should now be listening on port 80</p>
    358388    <pre class="shell">
    359 $ sudo systemctl status www.example.com.socket
     389$ systemctl status www.example.com.socket
    360390www.example.com.socket
    361391          Loaded: loaded (/etc/systemd/system/www.example.com.socket; disabled)
    362392          Active: active (listening) since Tue 2013-01-29 14:53:17 GMT; 7s ago
     
    367397    <p>But <code>twistd</code> should not yet have started. You can verify this
    368398      using the <code>systemctl</code> command. eg</p>
    369399    <pre class="shell">
    370 $ sudo systemctl status www.example.com.service
     400$ systemctl status www.example.com.service
    371401www.example.com.service - Example Web Server
    372402          Loaded: loaded (/etc/systemd/system/www.example.com.service; static)
    373403          Active: inactive (dead) since Tue 2013-01-29 14:48:42 GMT; 6min ago
     
    381411    </pre>
    382412  </li>
    383413  <li>
    384     <h3>Activate the port, start the service</h3>
     414    <h3>Activate the port to start the service</h3>
    385415
    386416    <p>Now try connecting
    387417      to <a href="http://localhost:80">http://localhost:80</a> in
     
    390420    <p><code>systemd</code> will accept the connection and
    391421      start <code>twistd</code>, passing it the listening socket. You
    392422      can verify this by using systemctl to report the status of the
    393       service.. eg</p>
     423      service. eg</p>
    394424    <pre class="shell">
    395 $ sudo systemctl status www.example.com.service
     425$ systemctl status www.example.com.service
    396426www.example.com.service - Example Web Server
    397427          Loaded: loaded (/etc/systemd/system/www.example.com.service; static)
    398428          Active: active (running) since Tue 2013-01-29 15:02:20 GMT; 3s ago
     
    413443<h2>Conclusion</h2>
    414444<p>In this tutorial you have learned how to deploy a Twisted service
    415445  using <code>systemd</code>. You have also learned how the service can be started
    416   on demand, using socket activation</p>
     446  on demand, using socket activation.</p>
    417447
    418448<h2 id="limitations">Limitations and Known Issues</h2>
    419449<ol>
     
    424454</ol>
    425455<h2>Further Reading</h2>
    426456<ul>
    427   <li><a href="http://0pointer.de/blog/projects/systemd-docs.html"><code>systemd</code>
     457  <li><a href="http://www.freedesktop.org/software/systemd/man/"><code>systemd</code>
    428458      Documentation</a></li>
    429459</ul>
    430460</body>