source: trunk/doc-new/man/xml/portfile-startupitem.7.xml @ 31135

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

Document the startupitem_type "none" option.

File size: 20.7 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4<refentry>
5  <refmeta>
6    <refentrytitle>PORTFILE-STARTUPITEM</refentrytitle>
7
8    <manvolnum>7</manvolnum>
9  </refmeta>
10
11  <refnamediv>
12    <refname>portfile-startupitem</refname>
13
14    <refpurpose>MacPorts Portfile reference</refpurpose>
15  </refnamediv>
16
17  <refsection>
18    <title>Description</title>
19
20    <para>A complete reference of all available Portfile StartupItem keywords.
21    Portfiles consist of valid TCL and are encoded in UTF-8. They usually
22    contain only simple keyword/value combinations and Tcl extensions as
23    described below, though they may also contain arbitrary TCL code. Every
24    port has a corresponding Portfile, but Portfiles do not completely define
25    a port's installation behavior since the MacPorts base has default port
26    installation characteristics coded within it. Therefore Portfiles need
27    only specify required options and, if necessary, non-default
28    characteristics for a port.</para>
29  </refsection>
30
31  <refsection>
32    <refsection>
33      <title>StartupItems</title>
34
35      <para>A StartupItem is a MacPort facility to run "daemons," a Unix term
36      for programs that run continuously in the background, rather than under
37      the direct control of a user; for example, mail servers, network
38      listeners, etc. Ports that use StartupItem keywords create Mac OS X
39      scripts for <ulink
40      url="http://developer.apple.com/macosx/launchd.html">launchd</ulink>,
41      which is the Apple facility introduced with OS X 10.4 to replace xinetd
42      for starting and managing daemons. To support
43      <command>launchd</command>, a program named <command>daemondo</command>
44      is provided by MacPorts base that serves as an adapter between OS X's
45      <command>launchd</command> and daemons (<quote>executable</quote>
46      StartupItems) or traditional Unix startup scripts that start daemons
47      (<quote>script</quote> StartupItems).</para>
48
49      <para>There are three categories of StartupItem keywords. Those that
50      trigger StartupItem creation and logging, those that specify attributes
51      of <quote>executable</quote> StartupItems, and those that specify
52      attributes of <quote>script</quote> StartupItems.</para>
53
54      <note>
55        <para>The variable <varname>startupitem_type</varname> in
56        ${prefix}/etc/macports/macports.conf may be set to
57        <option>none</option> to globally override all StartupItem keywords
58        found in Portfiles; this prevents StartupItems from being
59        created.</para>
60      </note>
61
62      <refsection>
63        <title>StartupItem Attributes</title>
64
65        <para>The keywords in this section may be used with either
66        <quote>executable</quote> or <quote>script</quote> StartupItems (see
67        below).</para>
68
69        <variablelist>
70          <varlistentry>
71            <term>startupitem.create</term>
72
73            <listitem>
74              <para>Trigger the creation of a StartupItem.</para>
75
76              <itemizedlist>
77                <listitem>
78                  <para>Type: optional</para>
79                </listitem>
80
81                <listitem>
82                  <para>Default: no</para>
83                </listitem>
84
85                <listitem>
86                  <para>Values: yes no</para>
87                </listitem>
88
89                <listitem>
90                  <para>Example:</para>
91
92                  <programlisting>startupitem.create  yes</programlisting>
93                </listitem>
94              </itemizedlist>
95            </listitem>
96          </varlistentry>
97
98          <varlistentry>
99            <term>startupitem.name</term>
100
101            <listitem>
102              <para>Sets the name for the StartupItem.</para>
103
104              <itemizedlist>
105                <listitem>
106                  <para>Type: required</para>
107                </listitem>
108
109                <listitem>
110                  <para>Default: none</para>
111                </listitem>
112
113                <listitem>
114                  <para>Values: <replaceable>any_name</replaceable></para>
115                </listitem>
116
117                <listitem>
118                  <para>Example:</para>
119
120                  <programlisting>startupitem.name  OpenSSH</programlisting>
121                </listitem>
122              </itemizedlist>
123            </listitem>
124          </varlistentry>
125
126          <varlistentry>
127            <term>startupitem.logfile</term>
128
129            <listitem>
130              <para>Path to a logfile for logging events about the lifetime of
131              the StartupItem. Depending on the type of StartupItem, and the
132              manner in which it is started, standard output from the daemon
133              may also be directed to the logfile.</para>
134
135              <itemizedlist>
136                <listitem>
137                  <para>Type: optional</para>
138                </listitem>
139
140                <listitem>
141                  <para>Default: <filename>/dev/null</filename></para>
142                </listitem>
143
144                <listitem>
145                  <para>Values: <replaceable>/file/path</replaceable></para>
146                </listitem>
147
148                <listitem>
149                  <para>Example:</para>
150
151                  <programlisting>startupitem.logfile  ${prefix}/var/log/mydaemon.log</programlisting>
152                </listitem>
153              </itemizedlist>
154            </listitem>
155          </varlistentry>
156
157          <varlistentry>
158            <term>startupitem.logevents</term>
159
160            <listitem>
161              <para>Control whether or not to log events to the log file. If
162              logevents is set, events with timestamps are logged to the
163              logfile.</para>
164
165              <itemizedlist>
166                <listitem>
167                  <para>Type: optional</para>
168                </listitem>
169
170                <listitem>
171                  <para>Default: no</para>
172                </listitem>
173
174                <listitem>
175                  <para>Values: yes no</para>
176                </listitem>
177
178                <listitem>
179                  <para>Example:</para>
180
181                  <programlisting>startupitem.logevents   yes</programlisting>
182                </listitem>
183              </itemizedlist>
184            </listitem>
185          </varlistentry>
186
187          <varlistentry>
188            <term>startupitem.netchange</term>
189
190            <listitem>
191              <para>Cause the daemon to be restarted when a change in network
192              state is detected.</para>
193
194              <itemizedlist>
195                <listitem>
196                  <para>Type: optional</para>
197                </listitem>
198
199                <listitem>
200                  <para>Default: no</para>
201                </listitem>
202
203                <listitem>
204                  <para>Values: yes no</para>
205                </listitem>
206
207                <listitem>
208                  <para>Example:</para>
209
210                  <programlisting>startupitem.netchange  yes</programlisting>
211                </listitem>
212              </itemizedlist>
213            </listitem>
214          </varlistentry>
215        </variablelist>
216      </refsection>
217
218      <refsection>
219        <title>Executable StartupItems</title>
220
221        <para>Daemons run continuously, so monitoring the health of daemon
222        processes and restarting them if they die is an important
223        StartupItems' feature. <quote>Executable</quote> StartupItems are
224        preferred over <quote>script</quote> StartupItems because
225        <command>daemondo</command> launches the daemon
226        <emphasis>directly</emphasis>, rather than
227        <emphasis>indirectly</emphasis> via a script, and therefore it
228        automatically knows how to monitor a daemon process and restart it if
229        it dies. Daemons used with <quote>executable</quote> StartupItems may
230        be programs or scripts (shell, perl, python, etc.), but when a script
231        the script <emphasis>itself</emphasis> must be the daemon, rather than
232        a script that launches a daemon. <quote>Script</quote> StartupItems
233        are to be used for the latter.</para>
234
235        <note>
236          <para>For a given port, the <quote>executable</quote> StartupItem
237          keyword may not be used with any keywords in the
238          <quote>script</quote> StartupItem category.</para>
239        </note>
240
241        <variablelist>
242          <varlistentry>
243            <term>startupitem.executable</term>
244
245            <listitem>
246              <para>Specifies the name of the daemon to be run in the
247              background. It may have multiple arguments, but they must be
248              appropriate for a call to exec; arbitrary shell code may not be
249              used.</para>
250
251              <itemizedlist>
252                <listitem>
253                  <para>Type: optional</para>
254                </listitem>
255
256                <listitem>
257                  <para>Default: no</para>
258                </listitem>
259
260                <listitem>
261                  <para>Values: <replaceable>/path/to/daemon</replaceable>
262                  [<replaceable>args</replaceable>]</para>
263                </listitem>
264
265                <listitem>
266                  <para>Example:</para>
267
268                  <programlisting>startupitem.executable  ${prefix}/sbin/vm-pop3d -d 10 -t 600</programlisting>
269                </listitem>
270              </itemizedlist>
271
272              <note>
273                <para>Do not to wrap the value in quotes if passing arguments
274                to the daemon; unlike with<quote>script</quote> StartupItem
275                values, executable StartupItem value elements must be tagged
276                separately as shown in this example .plist file
277                snippet.</para>
278
279                <programlisting>&lt;key&gt;ProgramArguments&lt;/key&gt;
280        &lt;array&gt;
281                &lt;string&gt;/opt/local/bin/daemondo&lt;/string&gt;
282                &lt;string&gt;--label=vm-pop3d&lt;/string&gt;
283                &lt;string&gt;--start-cmd&lt;/string&gt;
284                &lt;string&gt;/opt/local/sbin/vm-pop3d&lt;/string&gt;
285                &lt;string&gt;-d&lt;/string&gt;
286                &lt;string&gt;10&lt;/string&gt;
287                &lt;string&gt;-t&lt;/string&gt;
288                &lt;string&gt;600&lt;/string&gt;
289                &lt;string&gt;;&lt;/string&gt;
290        &lt;/array&gt;</programlisting>
291              </note>
292            </listitem>
293          </varlistentry>
294        </variablelist>
295      </refsection>
296
297      <refsection>
298        <title>Script StartupItems</title>
299
300        <para>StartupItems of type <quote>script</quote> use
301        <command>daemondo</command> to launch a daemon
302        <emphasis>indirectly</emphasis> via a startup script. A typical
303        snippet of a startup script that may be used with a
304        <quote>script</quote> StartupItem is shown below. Notice that the
305        script is not a daemon; rather the script indirectly launches the
306        vm-pop3d daemon.</para>
307
308        <programlisting>#!/bin/sh
309#
310case "$1" in
311  start)
312       echo -n "Starting vm-pop3d: "
313       /opt/local/sbin/vm-pop3d -d 10 -t 600
314
315
316[... trimmed ...]</programlisting>
317
318        <para>But if a script itself is a daemon, use the
319        <quote>executable</quote> StartupItem type since that way it will be
320        launched directly and its health tracked automatically. When using
321        <quote>script</quote> StartupItems, the
322        <code>startupitem.pidfile</code> keyword must be used if you want
323        <command>daemondo</command> to monitor a daemon process and restart it
324        if it dies.</para>
325
326        <note>
327          <para>For a given port, StartupItem keywords in category
328          <quote>script</quote> may not be used with an
329          <quote>executable</quote> StartupItem keyword.</para>
330        </note>
331
332        <variablelist>
333          <varlistentry>
334            <term>startupitem.start</term>
335
336            <term>startupitem.stop</term>
337
338            <term>startupitem.restart</term>
339
340            <listitem>
341              <para>Specify a shell script to start, stop, and restart the
342              daemon. In the absence of a restart key, the daemon will be
343              restarted by taking the stop action, followed by the start
344              action.</para>
345
346              <itemizedlist>
347                <listitem>
348                  <para>Type: optional</para>
349                </listitem>
350
351                <listitem>
352                  <para>Default: none</para>
353                </listitem>
354
355                <listitem>
356                  <para>Values: <replaceable>shell_script</replaceable></para>
357                </listitem>
358
359                <listitem>
360                  <para>Examples:</para>
361
362                  <programlisting>startupitem.start "${prefix}/share/mysql/mysql.server start"
363startupitem.stop "${prefix}/share/mysql/mysql.server stop"
364startupitem.restart "${prefix}/share/mysql/mysql.server restart"</programlisting>
365                </listitem>
366              </itemizedlist>
367
368              <note>
369                <para>Wrap the stop, start, and restart values in quotes so
370                they will be placed in the wrapper as a single command.</para>
371              </note>
372            </listitem>
373          </varlistentry>
374
375          <varlistentry>
376            <term>startupitem.init</term>
377
378            <listitem>
379              <para>Shell code that will be executed prior to any of the
380              options <code>startupitem.start</code>,
381              <code>startupitem.stop</code> and
382              <code>startupitem.restart</code>.</para>
383
384              <itemizedlist>
385                <listitem>
386                  <para>Type: optional</para>
387                </listitem>
388
389                <listitem>
390                  <para>Default: no</para>
391                </listitem>
392
393                <listitem>
394                  <para>Values: <replaceable>shell_script</replaceable></para>
395                </listitem>
396
397                <listitem>
398                  <para>Example:</para>
399
400                  <programlisting>startupitem.init "BIN=${prefix}/sbin/bacula-fd"</programlisting>
401                </listitem>
402              </itemizedlist>
403            </listitem>
404          </varlistentry>
405
406          <varlistentry>
407            <term>startupitem.pidfile</term>
408
409            <listitem>
410              <para>This keyword must be defined properly for
411              <command>daemondo</command> to be able to monitor daemons
412              launched via <quote>script</quote> StartupItems and restart them
413              if they die. It specifies two things: a process id (PID) file
414              handling method, and a pidfile name and path.</para>
415
416              <itemizedlist>
417                <listitem>
418                  <para>Type: optional</para>
419                </listitem>
420
421                <listitem>
422                  <para>Default: [none] |
423                  [<filename>${prefix}/var/run/${name}.pid</filename>]</para>
424                </listitem>
425
426                <listitem>
427                  <para>Values [none auto manual clean]
428                  [<replaceable>/path/to/pidfile</replaceable>]</para>
429                </listitem>
430
431                <listitem>
432                  <para>Example:</para>
433
434                  <programlisting>startupitem.pidfile auto ${prefix}/var/run/${name}.pidfile</programlisting>
435                </listitem>
436              </itemizedlist>
437
438              <para>PID file handling options:</para>
439
440              <itemizedlist>
441                <listitem>
442                  <para><option>none</option> - daemondo will not create or
443                  track a PID file, so it won't know when a daemon
444                  dies.</para>
445                </listitem>
446
447                <listitem>
448                  <para><option>auto</option> - The started process is
449                  expected to create a PID file that contains the PID of the
450                  running daemon; daemondo then reads the PID from the file
451                  and tracks the process. The started process must delete the
452                  PID file if this is necessary.</para>
453                </listitem>
454
455                <listitem>
456                  <para><option>clean</option> - The started process is
457                  expected to create a PID file that contains the PID of the
458                  running daemon; daemondo then reads the PID from the file
459                  and tracks the process, and deletes the PID file if it
460                  detects the daemon has died.</para>
461                </listitem>
462
463                <listitem>
464                  <para><option>manual</option> - This option should only be
465                  used if an <quote>executable</quote> StartupItem could be
466                  used (daemondo launches a daemon directly)
467                  <emphasis>and</emphasis> a port author wants a PID file
468                  written for some special use. A PID file is not needed to
469                  detect process death for daemons launched directly by
470                  daemondo. As with executale StartupItems, daemondo remembers
471                  the PID of the launched process and tracks it
472                  automatically.</para>
473                </listitem>
474              </itemizedlist>
475            </listitem>
476          </varlistentry>
477        </variablelist>
478      </refsection>
479
480      <refsection>
481        <title>Loading / Unloading StartupItems into launchd</title>
482
483        <para>A port with a StartupItem places a link to a .plist file for the
484        port's daemon within <filename>/Library/LaunchDaemons/</filename>. A
485        .plist file is an XML file; MacPorts installs .plist files tagged as
486        <quote>disabled</quote> for the sake of security. You may enable a
487        startup script (tag the.plist file as <quote>enabled</quote>) and load
488        it into <command>launchd</command> with a single command as
489        shown.</para>
490
491        <programlisting><prompt>%%</prompt> <userinput>sudo launchctl load -w /Library/LaunchDaemons/org.macports.mysql5.plist</userinput></programlisting>
492
493        <para>You may stop a running startup script, disable it (tag the.plist
494        file as <quote>disabled</quote>), and unload it from
495        <command>launchd</command> with a single command as shown.</para>
496
497        <programlisting><prompt>%%</prompt> <userinput>sudo launchctl unload -w /Library/LaunchDaemons/org.macports.mysql5.plist</userinput></programlisting>
498      </refsection>
499
500      <refsection>
501        <title>StartupItem Internals</title>
502
503        <para>During port installation a MacPorts StartupItem creates a .plist
504        file in <filename>${prefix}/etc/LaunchDaemons/</filename>, and places
505        a symbolic link to the .plist file within
506        <filename>/Library/LaunchDaemons/</filename>.</para>
507
508        <para>For example, the StartupItem for the mysql5 port is
509        <filename>org.macports.mysql5.plist</filename>, and it is linked as
510        shown.</para>
511
512        <programlisting><prompt>%%</prompt> <userinput>ls -l /Library/LaunchDaemons</userinput></programlisting>
513
514        <screen>org.macports.mysql5.plist -&gt;
515     /opt/local/etc/LaunchDaemons/org.macports.mysql5/org.macports.mysql5.plist</screen>
516
517        <para>For <quote>script</quote> StartupItems, in addition to a .plist
518        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
519-rw-r--r--   2 root  wheel  975 Aug  2 14:16 org.macports.mysql5.plist</screen>The
520        wrapper manipulates the script as specified in the startupitem.start
521        and startupitem.stop keywords. An example wrapper script snippet is
522        shown below.</para>
523
524        <programlisting>#!/bin/sh
525#
526# MacPorts generated daemondo support script
527
528# Start
529Start()
530{
531        /opt/local/share/mysql5/mysql/mysql.server start
532}
533
534# Stop
535Stop()
536{
537        /opt/local/share/mysql5/mysql/mysql.server stop
538}
539
540[... trimmed ...]</programlisting>
541      </refsection>
542    </refsection>
543  </refsection>
544
545  <refsection>
546    <title>SEE ALSO</title>
547
548    <para><citerefentry>
549        <refentrytitle>portfile-global</refentrytitle>
550
551        <manvolnum>7</manvolnum>
552      </citerefentry>, <citerefentry>
553        <refentrytitle>portfile-phase</refentrytitle>
554
555        <manvolnum>7</manvolnum>
556      </citerefentry>, <citerefentry>
557        <refentrytitle>portfile-tcl</refentrytitle>
558
559        <manvolnum>7</manvolnum>
560      </citerefentry></para>
561  </refsection>
562
563  <refsection>
564    <title>AUTHORS</title>
565
566    <para>Landon Fuller <email>landonf@macports.org</email></para>
567
568    <para>Juan Manuel Palacios <email>jmpp@macports.org</email></para>
569
570    <para>Mark Duling <email>markd@macports.org</email></para>
571
572    <para>Kevin Van Vechten <email>kevin@opendarwin.org</email></para>
573
574    <para>Jordan K. Hubbard <email>jkh@macports.org</email></para>
575
576    <para>Chris Ridd <email>cjr@opendarwin.org</email></para>
577
578    <para>Kevin Ballard <email>eridius@macports.org</email></para>
579
580    <para>Markus W. Weissmann <email>mww@macports.org</email></para>
581  </refsection>
582</refentry>
Note: See TracBrowser for help on using the repository browser.