source: trunk/doc-new/guide/xml/portfile-startupitem.xml @ 33106

Last change on this file since 33106 was 33106, checked in by markd@…, 12 years ago

Minor refinements to startupitem.executable; remove unnecessary keyword
startupitem.type.

File size: 16.9 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4<section id="reference.startupitems">
5  <title>StartupItems</title>
6
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>
23
24  <note>
25    <para>The variable <varname>startupitem_type</varname> in
26    <filename>${prefix}/etc/macports/macports.conf</filename> may be set to
27    <option>none</option> to globally override all StartupItem keywords found
28    in Portfiles; this prevents StartupItems from being created.</para>
29  </note>
30
31  <section id="reference.startupitems.attributes">
32    <title>StartupItem Attributes</title>
33
34    <para>The keywords in this section may be used with either
35    <quote>executable</quote> or <quote>script</quote> StartupItems (see
36    below).</para>
37
38    <variablelist>
39      <varlistentry>
40        <term>startupitem.create</term>
41
42        <listitem>
43          <para>Trigger the creation of a StartupItem.</para>
44
45          <itemizedlist>
46            <listitem>
47              <para>Default: <option>no</option></para>
48            </listitem>
49
50            <listitem>
51              <para>Example:</para>
52
53              <programlisting>startupitem.create      yes</programlisting>
54            </listitem>
55          </itemizedlist>
56        </listitem>
57      </varlistentry>
58
59      <varlistentry>
60        <term>startupitem.name</term>
61
62        <listitem>
63          <para>Sets the name for the StartupItem. Defaults to the name of the
64          port, so this keyword is usually unnecessary.</para>
65
66          <itemizedlist>
67            <listitem>
68              <para>Default: <varname>${name}</varname></para>
69            </listitem>
70
71            <listitem>
72              <para>Example:</para>
73
74              <programlisting>startupitem.name        dhcpd</programlisting>
75            </listitem>
76          </itemizedlist>
77        </listitem>
78      </varlistentry>
79
80      <varlistentry>
81        <term>startupitem.logfile</term>
82
83        <listitem>
84          <para>Path to a logfile for logging events about the lifetime of the
85          StartupItem. Depending on the type of StartupItem, and the manner in
86          which it is started, standard output from the daemon may also be
87          directed to the logfile.</para>
88
89          <itemizedlist>
90            <listitem>
91              <para>Default: <filename>/dev/null</filename></para>
92            </listitem>
93
94            <listitem>
95              <para>Example:</para>
96
97              <programlisting>startupitem.logfile     ${prefix}/var/log/mydaemon.log</programlisting>
98            </listitem>
99          </itemizedlist>
100        </listitem>
101      </varlistentry>
102
103      <varlistentry>
104        <term>startupitem.logevents</term>
105
106        <listitem>
107          <para>Control whether or not to log events to the log file. If
108          logevents is set, events with timestamps are logged to the
109          logfile.</para>
110
111          <itemizedlist>
112            <listitem>
113              <para>Default: <option>no</option></para>
114            </listitem>
115
116            <listitem>
117              <para>Example:</para>
118
119              <programlisting>startupitem.logevents   yes</programlisting>
120            </listitem>
121          </itemizedlist>
122        </listitem>
123      </varlistentry>
124
125      <varlistentry>
126        <term>startupitem.netchange</term>
127
128        <listitem>
129          <para>Cause the daemon to be restarted when a change in network
130          state is detected.</para>
131
132          <itemizedlist>
133            <listitem>
134              <para>Default: <option>no</option></para>
135            </listitem>
136
137            <listitem>
138              <para>Example:</para>
139
140              <programlisting>startupitem.netchange   yes</programlisting>
141            </listitem>
142          </itemizedlist>
143        </listitem>
144      </varlistentry>
145    </variablelist>
146  </section>
147
148  <section id="reference.startupitems.executable">
149    <title>Executable StartupItems</title>
150
151    <para>Daemons run continuously, so monitoring the health of daemon
152    processes and restarting them if they die is an important StartupItems'
153    feature. <quote>Executable</quote> StartupItems are preferred over
154    <quote>script</quote> StartupItems because <command>daemondo</command>
155    launches the daemon <emphasis>directly</emphasis>, rather than
156    <emphasis>indirectly</emphasis> via a script, and therefore it
157    automatically knows how to monitor a daemon process and restart it if it
158    dies. Daemons used with <quote>executable</quote> StartupItems may be
159    programs or scripts (shell, perl, python, etc.), but when a script is used
160    the script <emphasis>itself</emphasis> must be the daemon, rather than
161    merely what launches the daemon (for the latter,<quote>script</quote>
162    StartupItems are to be used).</para>
163
164    <note>
165      <para>For a given port, the <quote>executable</quote> StartupItem
166      keyword may not be used with any keywords in the <quote>script</quote>
167      StartupItem category.</para>
168    </note>
169
170    <variablelist>
171      <varlistentry>
172        <term>startupitem.executable</term>
173
174        <listitem>
175          <para>Specifies the name of the daemon to be run. It may have
176          multiple arguments, but they must be appropriate for a call to exec;
177          arbitrary shell code may not be used.</para>
178
179          <note>
180            <para>Some daemons "daemonize" by detaching themselves from the
181            controlling tty before sending themselves to the background, thus
182            making themselves a child of the original process. A daemon to be
183            started with <code>startupitem.executable</code> must not be
184            allowed to do this (daemondo will think the process has died and
185            start another instance); this can usually be turned off with a
186            switch so the daemon does not detach itself (runs as a foreground
187            process).</para>
188          </note>
189
190          <itemizedlist>
191            <listitem>
192              <para>Default: none</para>
193            </listitem>
194
195            <listitem>
196              <para>Example:</para>
197
198              <programlisting>startupitem.executable  ${prefix}/sbin/vm-pop3d -d 10 -t 600</programlisting>
199            </listitem>
200          </itemizedlist>
201
202          <note>
203            <para>Do not wrap values in quotes if passing arguments to the
204            daemon; <quote>executable</quote> StartupItem elements must be
205            tagged individually so the spaces between arguments serve as
206            delimiters for <quote>string</quote> tags. For example, this
207            startupitem key/value pair:</para>
208
209            <programlisting>startupitem.executable    ${prefix}/sbin/vm-pop3d -d 10 -t 600</programlisting>
210
211            <para> generates a .plist file with these tags:</para>
212
213            <programlisting>&lt;key&gt;ProgramArguments&lt;/key&gt;
214&lt;array&gt;
215    &lt;string&gt;/opt/local/bin/daemondo&lt;/string&gt;
216    &lt;string&gt;--label=vm-pop3d&lt;/string&gt;
217    &lt;string&gt;--start-cmd&lt;/string&gt;
218    &lt;string&gt;/opt/local/sbin/vm-pop3d&lt;/string&gt;
219    &lt;string&gt;-d&lt;/string&gt;
220    &lt;string&gt;10&lt;/string&gt;
221    &lt;string&gt;-t&lt;/string&gt;
222    &lt;string&gt;600&lt;/string&gt;
223    &lt;string&gt;;&lt;/string&gt;
224&lt;/array&gt;</programlisting>
225          </note>
226        </listitem>
227      </varlistentry>
228    </variablelist>
229  </section>
230
231  <section id="reference.startupitems.script">
232    <title>Script StartupItems</title>
233
234    <para>StartupItems of type <quote>script</quote> use
235    <command>daemondo</command> to launch a daemon
236    <emphasis>indirectly</emphasis> via a startup script. A typical snippet of
237    a startup script that may be used with a <quote>script</quote> StartupItem
238    is shown below. Notice that the script is not a daemon; rather the script
239    indirectly launches the vm-pop3d daemon.</para>
240
241    <programlisting>#!/bin/sh
242
243case "$1" in
244    start)
245        echo -n "Starting vm-pop3d: "
246        /opt/local/sbin/vm-pop3d -d 10 -t 600
247
248[... trimmed ...]</programlisting>
249
250    <para>But if a script itself is a daemon, use the
251    <quote>executable</quote> StartupItem type since that way it will be
252    launched directly and its health tracked automatically. When using
253    <quote>script</quote> StartupItems, the <code>startupitem.pidfile</code>
254    keyword must be used if you want <command>daemondo</command> to monitor a
255    daemon process and restart it if it dies.</para>
256
257    <note>
258      <para>For a given port, StartupItem keywords in category
259      <quote>script</quote> may not be used with an <quote>executable</quote>
260      StartupItem keyword.</para>
261    </note>
262
263    <variablelist>
264      <varlistentry>
265        <term>startupitem.start</term>
266
267        <term>startupitem.stop</term>
268
269        <term>startupitem.restart</term>
270
271        <listitem>
272          <para>Specify a shell script to start, stop, and restart the daemon.
273          In the absence of <code>startupitem.restart</code>, the daemon will
274          be restarted by taking the stop action, followed by the start
275          action.</para>
276
277          <itemizedlist>
278            <listitem>
279              <para>Default: none</para>
280            </listitem>
281
282            <listitem>
283              <para>Examples:</para>
284
285              <programlisting>startupitem.start       "${prefix}/share/mysql/mysql.server start"
286startupitem.stop        "${prefix}/share/mysql/mysql.server stop"
287startupitem.restart     "${prefix}/share/mysql/mysql.server restart"</programlisting>
288            </listitem>
289          </itemizedlist>
290
291          <note>
292            <para>Wrap the stop, start, and restart values in quotes so they
293            will be placed in the wrapper tagged as a single element.</para>
294          </note>
295        </listitem>
296      </varlistentry>
297
298      <varlistentry>
299        <term>startupitem.init</term>
300
301        <listitem>
302          <para>Shell code that will be executed prior to any of the options
303          <code>startupitem.start</code>, <code>startupitem.stop</code> and
304          <code>startupitem.restart</code>.</para>
305
306          <itemizedlist>
307            <listitem>
308              <para>Default: none</para>
309            </listitem>
310
311            <listitem>
312              <para>Example:</para>
313
314              <programlisting>startupitem.init        BIN=${prefix}/sbin/bacula-fd</programlisting>
315            </listitem>
316          </itemizedlist>
317        </listitem>
318      </varlistentry>
319
320      <varlistentry>
321        <term>startupitem.pidfile</term>
322
323        <listitem>
324          <para>This keyword must be defined properly for
325          <command>daemondo</command> to be able to monitor daemons launched
326          via <quote>script</quote> StartupItems and restart them if they die.
327          It specifies two things: a process id (PID) file handling method,
328          and a pidfile name and path.</para>
329
330          <itemizedlist>
331            <listitem>
332              <!-- TODO: this is the default value described in the old
333              portfile.7 man page -->
334
335              <para>Default: <literal>none
336              ${prefix}/var/run/${name}.pid</literal></para>
337
338              <!-- TODO: clarify the default value -->
339
340              <para>Default: [none] |
341              [<filename>${prefix}/var/run/${name}.pid</filename>]</para>
342            </listitem>
343
344            <listitem>
345              <!-- TODO: clarify this -->
346
347              <para>Values [none auto manual clean]
348              [<replaceable>/path/to/pidfile</replaceable>]</para>
349            </listitem>
350
351            <listitem>
352              <para>Example:</para>
353
354              <programlisting>startupitem.pidfile     auto ${prefix}/var/run/${name}.pidfile</programlisting>
355
356              <!-- TODO: add more examples here -->
357            </listitem>
358          </itemizedlist>
359
360          <para>PID file handling options:</para>
361
362          <itemizedlist>
363            <listitem>
364              <para><option>none</option> - daemondo will not create or track
365              a PID file, so it won't know when a daemon dies.</para>
366            </listitem>
367
368            <listitem>
369              <para><option>auto</option> - The started process is expected to
370              create a PID file that contains the PID of the running daemon;
371              daemondo then reads the PID from the file and tracks the
372              process. The started process must delete the PID file if this is
373              necessary.</para>
374            </listitem>
375
376            <listitem>
377              <para><option>clean</option> - The started process is expected
378              to create a PID file that contains the PID of the running
379              daemon; daemondo then reads the PID from the file and tracks the
380              process, and deletes the PID file if it detects the daemon has
381              died.</para>
382            </listitem>
383
384            <listitem>
385              <para><option>manual</option> - This option should only be used
386              if an <quote>executable</quote> StartupItem could be used
387              (daemondo launches a daemon directly) <emphasis>and</emphasis> a
388              port author wants a PID file written for some special use. A PID
389              file is not needed to detect process death for daemons launched
390              directly by daemondo. As with executable StartupItems, daemondo
391              remembers the PID of the launched process and tracks it
392              automatically.</para>
393            </listitem>
394          </itemizedlist>
395        </listitem>
396      </varlistentry>
397    </variablelist>
398  </section>
399
400  <section id="reference.startupitems.launchd">
401    <title>Loading / Unloading StartupItems into launchd</title>
402
403    <para>A port with a StartupItem places a link to a .plist file for the
404    port's daemon within <filename>/Library/LaunchDaemons/</filename>. A
405    .plist file is an XML file; MacPorts installs .plist files tagged as
406    <quote>disabled</quote> for the sake of security. You may enable a startup
407    script (tag the.plist file as <quote>enabled</quote>) and load it into
408    <command>launchd</command> with a single command as shown.</para>
409
410    <programlisting><prompt>%%</prompt> <userinput>sudo launchctl load -w /Library/LaunchDaemons/org.macports.mysql5.plist</userinput></programlisting>
411
412    <para>You may stop a running startup script, disable it (tag the.plist
413    file as <quote>disabled</quote>), and unload it from
414    <command>launchd</command> with a single command as shown.</para>
415
416    <programlisting><prompt>%%</prompt> <userinput>sudo launchctl unload -w /Library/LaunchDaemons/org.macports.mysql5.plist</userinput></programlisting>
417  </section>
418
419  <section id="reference.startupitems.internals">
420    <title>StartupItem Internals</title>
421
422    <para>During port installation a MacPorts StartupItem creates a .plist
423    file in <filename>${prefix}/etc/LaunchDaemons/</filename>, and places a
424    symbolic link to the .plist file within
425    <filename>/Library/LaunchDaemons/</filename>.</para>
426
427    <para>For example, the StartupItem for the mysql5 port is
428    <filename>org.macports.mysql5.plist</filename>, and it is linked as
429    shown.</para>
430
431    <programlisting><prompt>%%</prompt> <userinput>ls -l /Library/LaunchDaemons</userinput></programlisting>
432
433    <screen>org.macports.mysql5.plist -&gt;
434     /opt/local/etc/LaunchDaemons/org.macports.mysql5/org.macports.mysql5.plist</screen>
435
436    <para>For <quote>script</quote> StartupItems, in addition to a .plist
437    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
438-rw-r--r--   2 root  wheel  975 Aug  2 14:16 org.macports.mysql5.plist</screen>The
439    wrapper manipulates the script as specified in the startupitem.start and
440    startupitem.stop keywords. An example wrapper script snippet is shown
441    below.</para>
442
443    <programlisting>#!/bin/sh
444
445# MacPorts generated daemondo support script
446
447# Start
448Start()
449{
450    /opt/local/share/mysql5/mysql/mysql.server start
451}
452
453# Stop
454Stop()
455{
456    /opt/local/share/mysql5/mysql/mysql.server stop
457}
458
459[... trimmed ...]</programlisting>
460  </section>
461</section>
Note: See TracBrowser for help on using the repository browser.