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

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

Minor grammatical changes.

File size: 17.8 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.</para>
64
65          <itemizedlist>
66            <listitem>
67              <para>Default: none</para>
68            </listitem>
69
70            <listitem>
71              <para>Example:</para>
72
73              <programlisting>startupitem.name        OpenSSH</programlisting>
74            </listitem>
75          </itemizedlist>
76        </listitem>
77      </varlistentry>
78
79      <varlistentry>
80        <term>startupitem.type</term>
81
82        <!-- TODO: check if this is still up to date -->
83
84        <listitem>
85          <para>Select the type of startupitem to generate. By default, a
86          startupitem will be generated that is of the appropriate type for
87          the OS. For instance, launchd is used on system 10.4, while
88          SystemStarter is used on prior Mac OS X systems. A global default
89          may be specified with the startupitem_type preference in
90          <filename>ports.conf</filename>.</para>
91
92          <itemizedlist>
93            <listitem>
94              <para>Default: none</para>
95            </listitem>
96
97            <listitem>
98              <para>Values: <option>SystemStarter</option>
99              <option>launchd</option> <option>default</option>
100              <option>rcNG</option></para>
101            </listitem>
102
103            <listitem>
104              <para>Example:</para>
105
106              <programlisting>startupitem.type        launchd</programlisting>
107            </listitem>
108          </itemizedlist>
109        </listitem>
110      </varlistentry>
111
112      <varlistentry>
113        <term>startupitem.logfile</term>
114
115        <listitem>
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>
120
121          <itemizedlist>
122            <listitem>
123              <para>Default: <filename>/dev/null</filename></para>
124            </listitem>
125
126            <listitem>
127              <para>Example:</para>
128
129              <programlisting>startupitem.logfile     ${prefix}/var/log/mydaemon.log</programlisting>
130            </listitem>
131          </itemizedlist>
132        </listitem>
133      </varlistentry>
134
135      <varlistentry>
136        <term>startupitem.logevents</term>
137
138        <listitem>
139          <para>Control whether or not to log events to the log file. If
140          logevents is set, events with timestamps are logged to the
141          logfile.</para>
142
143          <itemizedlist>
144            <listitem>
145              <para>Default: <option>no</option></para>
146            </listitem>
147
148            <listitem>
149              <para>Example:</para>
150
151              <programlisting>startupitem.logevents   yes</programlisting>
152            </listitem>
153          </itemizedlist>
154        </listitem>
155      </varlistentry>
156
157      <varlistentry>
158        <term>startupitem.netchange</term>
159
160        <listitem>
161          <para>Cause the daemon to be restarted when a change in network
162          state is detected.</para>
163
164          <itemizedlist>
165            <listitem>
166              <para>Default: <option>no</option></para>
167            </listitem>
168
169            <listitem>
170              <para>Example:</para>
171
172              <programlisting>startupitem.netchange   yes</programlisting>
173            </listitem>
174          </itemizedlist>
175        </listitem>
176      </varlistentry>
177    </variablelist>
178  </section>
179
180  <section id="reference.startupitems.executable">
181    <title>Executable StartupItems</title>
182
183    <para>Daemons run continuously, so monitoring the health of daemon
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
188    <emphasis>indirectly</emphasis> via a script, and therefore it
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>
195
196    <note>
197      <para>For a given port, the <quote>executable</quote> StartupItem
198      keyword may not be used with any keywords in the <quote>script</quote>
199      StartupItem category.</para>
200    </note>
201
202    <variablelist>
203      <varlistentry>
204        <term>startupitem.executable</term>
205
206        <listitem>
207          <para>Specifies the name of the daemon to be run. It may have
208          multiple arguments, but they must be appropriate for a call to exec;
209          arbitrary shell code may not be used.</para>
210
211          <note>
212            <para>Some daemons "daemonize" by detaching themselves from the
213            controlling tty before sending themselves to the background, 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            allowed to do this (daemondo will think the process has died and
217            start another instance); this can usually be turned off with a
218            switch so the daemon does not detach itself (runs as a foreground
219            process).</para>
220          </note>
221
222          <itemizedlist>
223            <listitem>
224              <para>Default: <option>none</option></para>
225            </listitem>
226
227            <listitem>
228              <para>Example:</para>
229
230              <programlisting>startupitem.executable  ${prefix}/sbin/vm-pop3d -d 10 -t 600</programlisting>
231            </listitem>
232          </itemizedlist>
233
234          <note>
235            <para>Do not wrap values in quotes if passing arguments to the
236            daemon. <quote>Executable</quote> StartupItem values must be
237            tagged as individual strings and the spaces between arguments
238            serve as delimiters for each string, as shown in example .plist
239            snippet below.</para>
240
241            <programlisting>&lt;key&gt;ProgramArguments&lt;/key&gt;
242&lt;array&gt;
243        &lt;string&gt;/opt/local/bin/daemondo&lt;/string&gt;
244        &lt;string&gt;--label=vm-pop3d&lt;/string&gt;
245        &lt;string&gt;--start-cmd&lt;/string&gt;
246        &lt;string&gt;/opt/local/sbin/vm-pop3d&lt;/string&gt;
247        &lt;string&gt;-d&lt;/string&gt;
248        &lt;string&gt;10&lt;/string&gt;
249        &lt;string&gt;-t&lt;/string&gt;
250        &lt;string&gt;600&lt;/string&gt;
251        &lt;string&gt;;&lt;/string&gt;
252&lt;/array&gt;</programlisting>
253          </note>
254        </listitem>
255      </varlistentry>
256    </variablelist>
257  </section>
258
259  <section id="reference.startupitems.script">
260    <title>Script StartupItems</title>
261
262    <para>StartupItems of type <quote>script</quote> use
263    <command>daemondo</command> to launch a daemon
264    <emphasis>indirectly</emphasis> via a startup script. A typical snippet of
265    a startup script that may be used with a <quote>script</quote> StartupItem
266    is shown below. Notice that the script is not a daemon; rather the script
267    indirectly launches the vm-pop3d daemon.</para>
268
269    <programlisting>#!/bin/sh
270
271case "$1" in
272    start)
273        echo -n "Starting vm-pop3d: "
274        /opt/local/sbin/vm-pop3d -d 10 -t 600
275
276[... trimmed ...]</programlisting>
277
278    <para>But if a script itself is a daemon, use the
279    <quote>executable</quote> StartupItem type since that way it will be
280    launched directly and its health tracked automatically. When using
281    <quote>script</quote> StartupItems, the <code>startupitem.pidfile</code>
282    keyword must be used if you want <command>daemondo</command> to monitor a
283    daemon process and restart it if it dies.</para>
284
285    <note>
286      <para>For a given port, StartupItem keywords in category
287      <quote>script</quote> may not be used with an <quote>executable</quote>
288      StartupItem keyword.</para>
289    </note>
290
291    <variablelist>
292      <varlistentry>
293        <term>startupitem.start</term>
294
295        <term>startupitem.stop</term>
296
297        <term>startupitem.restart</term>
298
299        <listitem>
300          <para>Specify a shell script to start, stop, and restart the daemon.
301          In the absence of <code>startupitem.restart</code>, the daemon will
302          be restarted by taking the stop action, followed by the start
303          action.</para>
304
305          <itemizedlist>
306            <listitem>
307              <para>Default: none</para>
308            </listitem>
309
310            <listitem>
311              <para>Examples:</para>
312
313              <programlisting>startupitem.start       "${prefix}/share/mysql/mysql.server start"
314startupitem.stop        "${prefix}/share/mysql/mysql.server stop"
315startupitem.restart     "${prefix}/share/mysql/mysql.server restart"</programlisting>
316            </listitem>
317          </itemizedlist>
318
319          <note>
320            <para>Wrap the stop, start, and restart values in quotes so they
321            will be placed in the wrapper as a single command.</para>
322          </note>
323        </listitem>
324      </varlistentry>
325
326      <varlistentry>
327        <term>startupitem.init</term>
328
329        <listitem>
330          <para>Shell code that will be executed prior to any of the options
331          <code>startupitem.start</code>, <code>startupitem.stop</code> and
332          <code>startupitem.restart</code>.</para>
333
334          <itemizedlist>
335            <listitem>
336              <para>Default: none</para>
337            </listitem>
338
339            <listitem>
340              <para>Example:</para>
341
342              <programlisting>startupitem.init        BIN=${prefix}/sbin/bacula-fd</programlisting>
343            </listitem>
344          </itemizedlist>
345        </listitem>
346      </varlistentry>
347
348      <varlistentry>
349        <term>startupitem.pidfile</term>
350
351        <listitem>
352          <para>This keyword must be defined properly for
353          <command>daemondo</command> to be able to monitor daemons launched
354          via <quote>script</quote> StartupItems and restart them if they die.
355          It specifies two things: a process id (PID) file handling method,
356          and a pidfile name and path.</para>
357
358          <itemizedlist>
359            <listitem>
360              <!-- TODO: this is the default value described in the old
361              portfile.7 man page -->
362
363              <para>Default: <literal>none
364              ${prefix}/var/run/${name}.pid</literal></para>
365
366              <!-- TODO: clarify the default value -->
367
368              <para>Default: [none] |
369              [<filename>${prefix}/var/run/${name}.pid</filename>]</para>
370            </listitem>
371
372            <listitem>
373              <!-- TODO: clarify this -->
374
375              <para>Values [none auto manual clean]
376              [<replaceable>/path/to/pidfile</replaceable>]</para>
377            </listitem>
378
379            <listitem>
380              <para>Example:</para>
381
382              <programlisting>startupitem.pidfile     auto ${prefix}/var/run/${name}.pidfile</programlisting>
383
384              <!-- TODO: add more examples here -->
385            </listitem>
386          </itemizedlist>
387
388          <para>PID file handling options:</para>
389
390          <itemizedlist>
391            <listitem>
392              <para><option>none</option> - daemondo will not create or track
393              a PID file, so it won't know when a daemon dies.</para>
394            </listitem>
395
396            <listitem>
397              <para><option>auto</option> - The started process is expected to
398              create a PID file that contains the PID of the running daemon;
399              daemondo then reads the PID from the file and tracks the
400              process. The started process must delete the PID file if this is
401              necessary.</para>
402            </listitem>
403
404            <listitem>
405              <para><option>clean</option> - The started process is expected
406              to create a PID file that contains the PID of the running
407              daemon; daemondo then reads the PID from the file and tracks the
408              process, and deletes the PID file if it detects the daemon has
409              died.</para>
410            </listitem>
411
412            <listitem>
413              <para><option>manual</option> - This option should only be used
414              if an <quote>executable</quote> StartupItem could be used
415              (daemondo launches a daemon directly) <emphasis>and</emphasis> a
416              port author wants a PID file written for some special use. A PID
417              file is not needed to detect process death for daemons launched
418              directly by daemondo. As with executable StartupItems, daemondo
419              remembers the PID of the launched process and tracks it
420              automatically.</para>
421            </listitem>
422          </itemizedlist>
423        </listitem>
424      </varlistentry>
425    </variablelist>
426  </section>
427
428  <section id="reference.startupitems.launchd">
429    <title>Loading / Unloading StartupItems into launchd</title>
430
431    <para>A port with a StartupItem places a link to a .plist file for the
432    port's daemon within <filename>/Library/LaunchDaemons/</filename>. A
433    .plist file is an XML file; MacPorts installs .plist files tagged as
434    <quote>disabled</quote> for the sake of security. You may enable a startup
435    script (tag the.plist file as <quote>enabled</quote>) and load it into
436    <command>launchd</command> with a single command as shown.</para>
437
438    <programlisting><prompt>%%</prompt> <userinput>sudo launchctl load -w /Library/LaunchDaemons/org.macports.mysql5.plist</userinput></programlisting>
439
440    <para>You may stop a running startup script, disable it (tag the.plist
441    file as <quote>disabled</quote>), and unload it from
442    <command>launchd</command> with a single command as shown.</para>
443
444    <programlisting><prompt>%%</prompt> <userinput>sudo launchctl unload -w /Library/LaunchDaemons/org.macports.mysql5.plist</userinput></programlisting>
445  </section>
446
447  <section id="reference.startupitems.internals">
448    <title>StartupItem Internals</title>
449
450    <para>During port installation a MacPorts StartupItem creates a .plist
451    file in <filename>${prefix}/etc/LaunchDaemons/</filename>, and places a
452    symbolic link to the .plist file within
453    <filename>/Library/LaunchDaemons/</filename>.</para>
454
455    <para>For example, the StartupItem for the mysql5 port is
456    <filename>org.macports.mysql5.plist</filename>, and it is linked as
457    shown.</para>
458
459    <programlisting><prompt>%%</prompt> <userinput>ls -l /Library/LaunchDaemons</userinput></programlisting>
460
461    <screen>org.macports.mysql5.plist -&gt;
462     /opt/local/etc/LaunchDaemons/org.macports.mysql5/org.macports.mysql5.plist</screen>
463
464    <para>For <quote>script</quote> StartupItems, in addition to a .plist
465    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
466-rw-r--r--   2 root  wheel  975 Aug  2 14:16 org.macports.mysql5.plist</screen>The
467    wrapper manipulates the script as specified in the startupitem.start and
468    startupitem.stop keywords. An example wrapper script snippet is shown
469    below.</para>
470
471    <programlisting>#!/bin/sh
472
473# MacPorts generated daemondo support script
474
475# Start
476Start()
477{
478    /opt/local/share/mysql5/mysql/mysql.server start
479}
480
481# Stop
482Stop()
483{
484    /opt/local/share/mysql5/mysql/mysql.server stop
485}
486
487[... trimmed ...]</programlisting>
488  </section>
489</section>
Note: See TracBrowser for help on using the repository browser.