Changeset 30408 for trunk/doc-new


Ignore:
Timestamp:
Oct 27, 2007, 6:27:26 AM (12 years ago)
Author:
markd@…
Message:

Enhance pidfile option descriptions per James' explanation on macports-dev; add sections
"Loading / Unloading StartupItems into launchd" and "StartupItem Internals".

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc-new/man/xml/portfile.7.xml

    r30384 r30408  
    913913      <title>StartupItems</title>
    914914
    915       <para><quote>Daemons</quote> is a Unix term for programs that run
    916       continuously in the background, rather than under the direct control of
    917       a user; for example, mail servers, network listeners, etc. MacPorts
    918       StartupItems are used for ported applications that use daemons; these
    919       keywords create Mac OS X startup scripts for <ulink
     915      <para>A StartupItem is a MacPort facility to run "daemons," a Unix term
     916      for programs that run continuously in the background, rather than under
     917      the direct control of a user; for example, mail servers, network
     918      listeners, etc. Ports that use StartupItem keywords create Mac OS X
     919      scripts for <ulink
    920920      url="http://developer.apple.com/macosx/launchd.html">launchd</ulink>,
    921       the facility introduced by Apple beginning with OS X 10.4, that starts,
    922       stops, and manages daemons, programs, and scripts. Port authors use
    923       StartupItem keywords within Portfiles to instruct MacPorts to generate
    924       and install <command>launchd</command> scripts during port installation.
    925       To support launchd, a wrapper program named <command>daemondo</command>
     921      which is the Apple facility introduced with OS X 10.4 to replace xinetd
     922      for starting and managing daemons. To support
     923      <command>launchd</command>, a program named <command>daemondo</command>
    926924      is provided by MacPorts base that serves as an adapter between OS X's
    927       <command>launchd</command> and daemons started via traditional rc.d
    928       style scripts.</para>
     925      <command>launchd</command> and daemons (<quote>executable</quote>
     926      StartupItems) or traditional Unix startup scripts that start daemons
     927      (<quote>script</quote> StartupItems).</para>
    929928
    930929      <para>There are three categories of StartupItem keywords. Those that
     
    12531252              </itemizedlist>
    12541253
    1255               <para>Pidfile handling options:</para>
     1254              <para>PID file handling options:</para>
    12561255
    12571256              <itemizedlist>
    12581257                <listitem>
    1259                   <para><option>none</option> - The daemon is not to use a
    1260                   pidfile.</para>
    1261                 </listitem>
    1262 
    1263                 <listitem>
    1264                   <para><option>auto</option> - The daemon generates its own
    1265                   pidfile.</para>
    1266                 </listitem>
    1267 
    1268                 <listitem>
    1269                   <para><option>manual</option> - The daemon never generates a
    1270                   pidfile; the StartupItem must manage the pidfile on its
    1271                   own.</para>
    1272                 </listitem>
    1273 
    1274                 <listitem>
    1275                   <para><option>clean</option> - The daemon generates its own
    1276                   but will not delete it; the StartupItem must delete
    1277                   it.</para>
     1258                  <para><option>none</option> - daemondo will not create or
     1259                  track a PID file, so it won't know when a daemon
     1260                  dies.</para>
     1261                </listitem>
     1262
     1263                <listitem>
     1264                  <para><option>auto</option> - The started process is
     1265                  expected to create a PID file that contains the PID of the
     1266                  running daemon; daemondo then reads the PID from the file
     1267                  and tracks the process. The started process must delete the
     1268                  PID file if this is necessary.</para>
     1269                </listitem>
     1270
     1271                <listitem>
     1272                  <para><option>clean</option> - The started process is
     1273                  expected to create a PID file that contains the PID of the
     1274                  running daemon; daemondo then reads the PID from the file
     1275                  and tracks the process, and deletes the PID file if it
     1276                  detects the daemon has died.</para>
     1277                </listitem>
     1278
     1279                <listitem>
     1280                  <para><option>manual</option> - This option should only be
     1281                  used if an <quote>executable</quote> StartupItem could be
     1282                  used (daemondo launches a daemon directly)
     1283                  <emphasis>and</emphasis> a port author wants a PID file
     1284                  written for some special use. A PID file is not needed to
     1285                  detect process death for daemons launched directly by
     1286                  daemondo. As with executale StartupItems, daemondo remembers
     1287                  the PID of the launched process and tracks it
     1288                  automatically.</para>
    12781289                </listitem>
    12791290              </itemizedlist>
     
    12811292          </varlistentry>
    12821293        </variablelist>
     1294      </refsection>
     1295
     1296      <refsection>
     1297        <title>Loading / Unloading StartupItems into launchd</title>
     1298
     1299        <para>A port with a StartupItem places a link to a .plist file for the
     1300        port's daemon within <filename>/Library/LaunchDaemons/</filename>. A
     1301        .plist file is an XML file; MacPorts installs .plist files tagged as
     1302        <quote>disabled</quote> for the sake of security. You may enable a
     1303        startup script (tag the.plist file as <quote>enabled</quote>) and load
     1304        it into <command>launchd</command> with a single command as
     1305        shown.</para>
     1306
     1307        <programlisting><prompt>%%</prompt> <userinput>sudo launchctl load -w /Library/LaunchDaemons/org.macports.mysql5.plist</userinput></programlisting>
     1308
     1309        <para>You may stop a running startup script, disable it (tag the.plist
     1310        file as <quote>disabled</quote>), and unload it from
     1311        <command>launchd</command> with a single command as shown.</para>
     1312
     1313        <programlisting><prompt>%%</prompt> <userinput>sudo launchctl unload -w /Library/LaunchDaemons/org.macports.mysql5.plist</userinput></programlisting>
     1314      </refsection>
     1315
     1316      <refsection>
     1317        <title>StartupItem Internals</title>
     1318
     1319        <para>During port installation a MacPorts StartupItem creates a .plist
     1320        file in <filename>${prefix}/etc/LaunchDaemons/</filename>, and places
     1321        a symbolic link to the .plist file within
     1322        <filename>/Library/LaunchDaemons/</filename>.</para>
     1323
     1324        <para>For example, the StartupItem for the mysql5 port is
     1325        <filename>org.macports.mysql5.plist</filename>, and it is linked as
     1326        shown.</para>
     1327
     1328        <programlisting><prompt>%%</prompt> <userinput>ls -l /Library/LaunchDaemons</userinput></programlisting>
     1329
     1330        <screen>org.macports.mysql5.plist -&gt;
     1331     /opt/local/etc/LaunchDaemons/org.macports.mysql5/org.macports.mysql5.plist</screen>
     1332
     1333        <para>For <quote>script</quote> StartupItems, in addition to a .plist
     1334        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
     1335-rw-r--r--   2 root  wheel  975 Aug  2 14:16 org.macports.mysql5.plist</screen>The
     1336        wrapper manipulates the script as specified in the startupitem.start
     1337        and startupitem.stop keywords. An example wrapper script snippet is
     1338        shown below.</para>
     1339
     1340        <programlisting>#!/bin/sh
     1341#
     1342# MacPorts generated daemondo support script
     1343
     1344# Start
     1345Start()
     1346{
     1347        /opt/local/share/mysql5/mysql/mysql.server start
     1348}
     1349
     1350# Stop
     1351Stop()
     1352{
     1353        /opt/local/share/mysql5/mysql/mysql.server stop
     1354}
     1355
     1356[... trimmed ...]</programlisting>
    12831357      </refsection>
    12841358    </refsection>
Note: See TracChangeset for help on using the changeset viewer.