Changeset 33034 for trunk/doc-new


Ignore:
Timestamp:
Jan 17, 2008, 3:05:10 AM (12 years ago)
Author:
markd@…
Message:

Clarify startupitem.executable: daemons that detach and run as children / why quotes aren't used

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc-new/guide/xml/portfile-startupitem.xml

    r32049 r33034  
    22<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
    33"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
    4 
    54<section id="reference.startupitems">
    65  <title>StartupItems</title>
    76
    8   <para>A StartupItem is a MacPorts facility to run "daemons," a Unix term
    9   for programs that run continuously in the background, rather than under
    10   the direct control of a user; for example, mail servers, network
    11   listeners, etc. Ports that use StartupItem keywords create Mac OS X
    12   scripts for <ulink
    13   url="http://developer.apple.com/macosx/launchd.html">launchd</ulink>,
    14   which is the Apple facility introduced with Mac OS X 10.4 to replace xinetd
    15   for starting and managing daemons. To support
    16   <command>launchd</command>, a program named <command>daemondo</command>
    17   is provided by MacPorts base that serves as an adapter between Mac OS X's
    18   <command>launchd</command> and daemons (<quote>executable</quote>
    19   StartupItems) or traditional Unix startup scripts that start daemons
    20   (<quote>script</quote> StartupItems).</para>
    21 
    22   <para>There are three categories of StartupItem keywords. Those that
    23   trigger StartupItem creation and logging, those that specify attributes
    24   of <quote>executable</quote> StartupItems, and those that specify
    25   attributes of <quote>script</quote> StartupItems.</para>
     7  <para>A StartupItem is a MacPorts facility to run "daemons," a Unix term for
     8  programs that run continuously in the background, rather than under the
     9  direct control of a user; for example, mail servers, network listeners, etc.
     10  Ports that use StartupItem keywords create Mac OS X scripts for <ulink
     11  url="http://developer.apple.com/macosx/launchd.html">launchd</ulink>, which
     12  is the Apple facility introduced with Mac OS X 10.4 to replace xinetd for
     13  starting and managing daemons. To support <command>launchd</command>, a
     14  program named <command>daemondo</command> is provided by MacPorts base that
     15  serves as an adapter between Mac OS X's <command>launchd</command> and
     16  daemons (<quote>executable</quote> StartupItems) or traditional Unix startup
     17  scripts that start daemons (<quote>script</quote> StartupItems).</para>
     18
     19  <para>There are three categories of StartupItem keywords. Those that trigger
     20  StartupItem creation and logging, those that specify attributes of
     21  <quote>executable</quote> StartupItems, and those that specify attributes of
     22  <quote>script</quote> StartupItems.</para>
    2623
    2724  <note>
    2825    <para>The variable <varname>startupitem_type</varname> in
    2926    <filename>${prefix}/etc/macports/macports.conf</filename> may be set to
    30     <option>none</option> to globally override all StartupItem keywords
    31     found in Portfiles; this prevents StartupItems from being
    32     created.</para>
     27    <option>none</option> to globally override all StartupItem keywords found
     28    in Portfiles; this prevents StartupItems from being created.</para>
    3329  </note>
    3430
     
    9288          SystemStarter is used on prior Mac OS X systems. A global default
    9389          may be specified with the startupitem_type preference in
    94           <filename>ports.conf</filename>.
    95           </para>
     90          <filename>ports.conf</filename>.</para>
    9691
    9792          <itemizedlist>
     
    119114
    120115        <listitem>
    121           <para>Path to a logfile for logging events about the lifetime of
    122           the StartupItem. Depending on the type of StartupItem, and the
    123           manner in which it is started, standard output from the daemon
    124           may also be directed to the logfile.</para>
     116          <para>Path to a logfile for logging events about the lifetime of the
     117          StartupItem. Depending on the type of StartupItem, and the manner in
     118          which it is started, standard output from the daemon may also be
     119          directed to the logfile.</para>
    125120
    126121          <itemizedlist>
     
    187182
    188183    <para>Daemons run continuously, so monitoring the health of daemon
    189     processes and restarting them if they die is an important
    190     StartupItems' feature. <quote>Executable</quote> StartupItems are
    191     preferred over <quote>script</quote> StartupItems because
    192     <command>daemondo</command> launches the daemon
    193     <emphasis>directly</emphasis>, rather than
     184    processes and restarting them if they die is an important StartupItems'
     185    feature. <quote>Executable</quote> StartupItems are preferred over
     186    <quote>script</quote> StartupItems because <command>daemondo</command>
     187    launches the daemon <emphasis>directly</emphasis>, rather than
    194188    <emphasis>indirectly</emphasis> via a script, and therefore it
    195     automatically knows how to monitor a daemon process and restart it if
    196     it dies. Daemons used with <quote>executable</quote> StartupItems may
    197     be programs or scripts (shell, perl, python, etc.), but when a script is
    198     used the script <emphasis>itself</emphasis> must be the daemon, rather
    199     than a script that launches a daemon. <quote>Script</quote> StartupItems
    200     are to be used for the latter.</para>
     189    automatically knows how to monitor a daemon process and restart it if it
     190    dies. Daemons used with <quote>executable</quote> StartupItems may be
     191    programs or scripts (shell, perl, python, etc.), but when a script is used
     192    the script <emphasis>itself</emphasis> must be the daemon, rather than
     193    merely what launches the daemon (for the latter,<quote>script</quote>
     194    StartupItems are to be used).</para>
    201195
    202196    <note>
    203197      <para>For a given port, the <quote>executable</quote> StartupItem
    204       keyword may not be used with any keywords in the
    205       <quote>script</quote> StartupItem category.</para>
     198      keyword may not be used with any keywords in the <quote>script</quote>
     199      StartupItem category.</para>
    206200    </note>
    207201
     
    211205
    212206        <listitem>
    213           <para>Specifies the name of the daemon to be run in the
    214           background. It may have multiple arguments, but they must be
    215           appropriate for a call to exec; arbitrary shell code may not be
    216           used.</para>
    217 
    218           <itemizedlist>
    219             <listitem>
    220               <!-- TODO: is the default really no, not none? -->
    221               <para>Default: <option>no</option></para>
     207          <para>Specifies the name of the daemon to be run in the background.
     208          It may have multiple arguments, but they must be appropriate for a
     209          call to exec; arbitrary shell code may not be used. </para>
     210
     211          <note>
     212            <para>Some daemons "daemonize" themselves by sending themselves to
     213            the background and detaching it from the controlling tty, thus
     214            making themselves a child of the original process. A daemon to be
     215            started with <code>startupitem.executable</code> must not be
     216            alowed to do this (daemondo will think the process died died and
     217            start another instance); this can usually be turned off with a
     218            switch so the daemon runs as a foreground process.</para>
     219          </note>
     220
     221          <itemizedlist>
     222            <listitem>
     223              <para>Default: <option>none</option></para>
    222224            </listitem>
    223225
     
    230232
    231233          <note>
    232             <para>Do not to wrap the value in quotes if passing arguments
    233             to the daemon; unlike with<quote>script</quote> StartupItem
    234             values, executable StartupItem value elements must be tagged
    235             separately as shown in this example .plist file
    236             snippet.</para>
    237 
    238             <programlisting><![CDATA[<key>ProgramArguments</key>
    239 <array>
    240         <string>/opt/local/bin/daemondo</string>
    241         <string>--label=vm-pop3d</string>
    242         <string>--start-cmd</string>
    243         <string>/opt/local/sbin/vm-pop3d</string>
    244         <string>-d</string>
    245         <string>10</string>
    246         <string>-t</string>
    247         <string>600</string>
    248         <string>;</string>
    249 </array>]]></programlisting>
    250             <!-- TODO: what is the meaning of this snippet here? -->
     234            <para>Do not wrap values in quotes if passing arguments to the
     235            daemon. <quote>Executable</quote> StartupItem values must be
     236            tagged as individual strings and the spaces between arguments
     237            serve as delimiters for each string, as shown in example .plist
     238            snippet below.</para>
     239
     240            <programlisting>&lt;key&gt;ProgramArguments&lt;/key&gt;
     241&lt;array&gt;
     242        &lt;string&gt;/opt/local/bin/daemondo&lt;/string&gt;
     243        &lt;string&gt;--label=vm-pop3d&lt;/string&gt;
     244        &lt;string&gt;--start-cmd&lt;/string&gt;
     245        &lt;string&gt;/opt/local/sbin/vm-pop3d&lt;/string&gt;
     246        &lt;string&gt;-d&lt;/string&gt;
     247        &lt;string&gt;10&lt;/string&gt;
     248        &lt;string&gt;-t&lt;/string&gt;
     249        &lt;string&gt;600&lt;/string&gt;
     250        &lt;string&gt;;&lt;/string&gt;
     251&lt;/array&gt;</programlisting>
    251252          </note>
    252253        </listitem>
     
    260261    <para>StartupItems of type <quote>script</quote> use
    261262    <command>daemondo</command> to launch a daemon
    262     <emphasis>indirectly</emphasis> via a startup script. A typical
    263     snippet of a startup script that may be used with a
    264     <quote>script</quote> StartupItem is shown below. Notice that the
    265     script is not a daemon; rather the script indirectly launches the
    266     vm-pop3d daemon.</para>
     263    <emphasis>indirectly</emphasis> via a startup script. A typical snippet of
     264    a startup script that may be used with a <quote>script</quote> StartupItem
     265    is shown below. Notice that the script is not a daemon; rather the script
     266    indirectly launches the vm-pop3d daemon.</para>
    267267
    268268    <programlisting>#!/bin/sh
     
    278278    <quote>executable</quote> StartupItem type since that way it will be
    279279    launched directly and its health tracked automatically. When using
    280     <quote>script</quote> StartupItems, the
    281     <code>startupitem.pidfile</code> keyword must be used if you want
    282     <command>daemondo</command> to monitor a daemon process and restart it
    283     if it dies.</para>
     280    <quote>script</quote> StartupItems, the <code>startupitem.pidfile</code>
     281    keyword must be used if you want <command>daemondo</command> to monitor a
     282    daemon process and restart it if it dies.</para>
    284283
    285284    <note>
    286285      <para>For a given port, StartupItem keywords in category
    287       <quote>script</quote> may not be used with an
    288       <quote>executable</quote> StartupItem keyword.</para>
     286      <quote>script</quote> may not be used with an <quote>executable</quote>
     287      StartupItem keyword.</para>
    289288    </note>
    290289
     
    318317
    319318          <note>
    320             <para>Wrap the stop, start, and restart values in quotes so
    321             they will be placed in the wrapper as a single command.</para>
     319            <para>Wrap the stop, start, and restart values in quotes so they
     320            will be placed in the wrapper as a single command.</para>
    322321          </note>
    323322        </listitem>
     
    328327
    329328        <listitem>
    330           <para>Shell code that will be executed prior to any of the
    331           options <code>startupitem.start</code>,
    332           <code>startupitem.stop</code> and
     329          <para>Shell code that will be executed prior to any of the options
     330          <code>startupitem.start</code>, <code>startupitem.stop</code> and
    333331          <code>startupitem.restart</code>.</para>
    334332
    335333          <itemizedlist>
    336 
    337             <listitem>
    338               <!-- TODO: is the default really no, not none? -->
    339               <para>Default: <option>no</option></para>
     334            <listitem>
     335              <para>Default: none</para>
    340336            </listitem>
    341337
     
    354350        <listitem>
    355351          <para>This keyword must be defined properly for
    356           <command>daemondo</command> to be able to monitor daemons
    357           launched via <quote>script</quote> StartupItems and restart them
    358           if they die. It specifies two things: a process id (PID) file
    359           handling method, and a pidfile name and path.</para>
     352          <command>daemondo</command> to be able to monitor daemons launched
     353          via <quote>script</quote> StartupItems and restart them if they die.
     354          It specifies two things: a process id (PID) file handling method,
     355          and a pidfile name and path.</para>
    360356
    361357          <itemizedlist>
     
    363359              <!-- TODO: this is the default value described in the old
    364360              portfile.7 man page -->
     361
    365362              <para>Default: <literal>none
    366363              ${prefix}/var/run/${name}.pid</literal></para>
     364
    367365              <!-- TODO: clarify the default value -->
     366
    368367              <para>Default: [none] |
    369368              [<filename>${prefix}/var/run/${name}.pid</filename>]</para>
     
    372371            <listitem>
    373372              <!-- TODO: clarify this -->
     373
    374374              <para>Values [none auto manual clean]
    375375              [<replaceable>/path/to/pidfile</replaceable>]</para>
     
    382382
    383383              <!-- TODO: add more examples here -->
    384 
    385384            </listitem>
    386385          </itemizedlist>
     
    390389          <itemizedlist>
    391390            <listitem>
    392               <para><option>none</option> - daemondo will not create or
    393               track a PID file, so it won't know when a daemon
    394               dies.</para>
    395             </listitem>
    396 
    397             <listitem>
    398               <para><option>auto</option> - The started process is
    399               expected to create a PID file that contains the PID of the
    400               running daemon; daemondo then reads the PID from the file
    401               and tracks the process. The started process must delete the
    402               PID file if this is necessary.</para>
    403             </listitem>
    404 
    405             <listitem>
    406               <para><option>clean</option> - The started process is
    407               expected to create a PID file that contains the PID of the
    408               running daemon; daemondo then reads the PID from the file
    409               and tracks the process, and deletes the PID file if it
    410               detects the daemon has died.</para>
    411             </listitem>
    412 
    413             <listitem>
    414               <para><option>manual</option> - This option should only be
    415               used if an <quote>executable</quote> StartupItem could be
    416               used (daemondo launches a daemon directly)
    417               <emphasis>and</emphasis> a port author wants a PID file
    418               written for some special use. A PID file is not needed to
    419               detect process death for daemons launched directly by
    420               daemondo. As with executable StartupItems, daemondo remembers
    421               the PID of the launched process and tracks it
     391              <para><option>none</option> - daemondo will not create or track
     392              a PID file, so it won't know when a daemon dies.</para>
     393            </listitem>
     394
     395            <listitem>
     396              <para><option>auto</option> - The started process is expected to
     397              create a PID file that contains the PID of the running daemon;
     398              daemondo then reads the PID from the file and tracks the
     399              process. The started process must delete the PID file if this is
     400              necessary.</para>
     401            </listitem>
     402
     403            <listitem>
     404              <para><option>clean</option> - The started process is expected
     405              to create a PID file that contains the PID of the running
     406              daemon; daemondo then reads the PID from the file and tracks the
     407              process, and deletes the PID file if it detects the daemon has
     408              died.</para>
     409            </listitem>
     410
     411            <listitem>
     412              <para><option>manual</option> - This option should only be used
     413              if an <quote>executable</quote> StartupItem could be used
     414              (daemondo launches a daemon directly) <emphasis>and</emphasis> a
     415              port author wants a PID file written for some special use. A PID
     416              file is not needed to detect process death for daemons launched
     417              directly by daemondo. As with executable StartupItems, daemondo
     418              remembers the PID of the launched process and tracks it
    422419              automatically.</para>
    423420            </listitem>
     
    434431    port's daemon within <filename>/Library/LaunchDaemons/</filename>. A
    435432    .plist file is an XML file; MacPorts installs .plist files tagged as
    436     <quote>disabled</quote> for the sake of security. You may enable a
    437     startup script (tag the.plist file as <quote>enabled</quote>) and load
    438     it into <command>launchd</command> with a single command as
    439     shown.</para>
     433    <quote>disabled</quote> for the sake of security. You may enable a startup
     434    script (tag the.plist file as <quote>enabled</quote>) and load it into
     435    <command>launchd</command> with a single command as shown.</para>
    440436
    441437    <programlisting><prompt>%%</prompt> <userinput>sudo launchctl load -w /Library/LaunchDaemons/org.macports.mysql5.plist</userinput></programlisting>
     
    452448
    453449    <para>During port installation a MacPorts StartupItem creates a .plist
    454     file in <filename>${prefix}/etc/LaunchDaemons/</filename>, and places
    455     a symbolic link to the .plist file within
     450    file in <filename>${prefix}/etc/LaunchDaemons/</filename>, and places a
     451    symbolic link to the .plist file within
    456452    <filename>/Library/LaunchDaemons/</filename>.</para>
    457453
     
    468464    file, a wrapper is also created.<programlisting><prompt>%%</prompt> <userinput>ls -l /opt/local/etc/LaunchDaemons/org.macports.mysql5/</userinput></programlisting><screen>-rwxr-xr-x   2 root  wheel  475 Aug  2 14:16 mysql5.wrapper
    469465-rw-r--r--   2 root  wheel  975 Aug  2 14:16 org.macports.mysql5.plist</screen>The
    470     wrapper manipulates the script as specified in the startupitem.start
    471     and startupitem.stop keywords. An example wrapper script snippet is
    472     shown below.</para>
     466    wrapper manipulates the script as specified in the startupitem.start and
     467    startupitem.stop keywords. An example wrapper script snippet is shown
     468    below.</para>
    473469
    474470    <programlisting>#!/bin/sh
Note: See TracChangeset for help on using the changeset viewer.