PORTFILE-STARTUPITEM7portfile-startupitemMacPorts Portfile referenceDescriptionA complete reference of all available Portfile StartupItem keywords.
Portfiles consist of valid TCL and are encoded in UTF-8. They usually
contain only simple keyword/value combinations and Tcl extensions as
described below, though they may also contain arbitrary TCL code. Every
port has a corresponding Portfile, but Portfiles do not completely define
a port's installation behavior since the MacPorts base has default port
installation characteristics coded within it. Therefore Portfiles need
only specify required options and, if necessary, non-default
characteristics for a port.StartupItemsA StartupItem is a MacPort facility to run "daemons," a Unix term
for programs that run continuously in the background, rather than under
the direct control of a user; for example, mail servers, network
listeners, etc. Ports that use StartupItem keywords create Mac OS X
scripts for launchd,
which is the Apple facility introduced with OS X 10.4 to replace xinetd
for starting and managing daemons. To support
launchd, a program named daemondo
is provided by MacPorts base that serves as an adapter between OS X's
launchd and daemons (executable
StartupItems) or traditional Unix startup scripts that start daemons
(script StartupItems).There are three categories of StartupItem keywords. Those that
trigger StartupItem creation and logging, those that specify attributes
of executable StartupItems, and those that specify
attributes of script StartupItems.StartupItem AttributesThe keywords in this section may be used with either
executable or script StartupItems (see
below).startupitem.createTrigger the creation of a StartupItem.Type: optionalDefault: noValues: yes noExample:startupitem.create yesstartupitem.nameSets the name for the StartupItem.Type: requiredDefault: noneValues: any_nameExample:startupitem.name OpenSSHstartupitem.logfilePath to a logfile for logging events about the lifetime of
the StartupItem. Depending on the type of StartupItem, and the
manner in which it is started, standard output from the daemon
may also be directed to the logfile.Type: optionalDefault: /dev/nullValues: /file/pathExample:startupitem.logfile ${prefix}/var/log/mydaemon.logstartupitem.logeventsControl whether or not to log events to the log file. If
logevents is set, events with timestamps are logged to the
logfile.Type: optionalDefault: noValues: yes noExample:startupitem.logevents yesstartupitem.netchangeCause the daemon to be restarted when a change in network
state is detected.Type: optionalDefault: noValues: yes noExample:startupitem.netchange yesExecutable StartupItemsDaemons run continuously, so monitoring the health of daemon
processes and restarting them if they die is an important
StartupItems' feature. Executable StartupItems are
preferred over script StartupItems because
daemondo launches the daemon
directly, rather than
indirectly via a script, and therefore it
automatically knows how to monitor a daemon process and restart it if
it dies. Daemons used with executable StartupItems may
be programs or scripts (shell, perl, python, etc.), but when a script
the script itself must be the daemon, rather than
a script that launches a daemon. Script StartupItems
are to be used for the latter.For a given port, the executable StartupItem
keyword may not be used with any keywords in the
script StartupItem category.startupitem.executableSpecifies the name of the daemon to be run in the
background. It may have multiple arguments, but they must be
appropriate for a call to exec; arbitrary shell code may not be
used.Type: optionalDefault: noValues: /path/to/daemon
[args]Example:startupitem.executable ${prefix}/sbin/vm-pop3d -d 10 -t 600Do not to wrap the value in quotes if passing arguments
to the daemon; unlike withscript StartupItem
values, executable StartupItem value elements must be tagged
separately as shown in this example .plist file
snippet.<key>ProgramArguments</key>
<array>
<string>/opt/local/bin/daemondo</string>
<string>--label=vm-pop3d</string>
<string>--start-cmd</string>
<string>/opt/local/sbin/vm-pop3d</string>
<string>-d</string>
<string>10</string>
<string>-t</string>
<string>600</string>
<string>;</string>
</array>Script StartupItemsStartupItems of type script use
daemondo to launch a daemon
indirectly via a startup script. A typical
snippet of a startup script that may be used with a
script StartupItem is shown below. Notice that the
script is not a daemon; rather the script indirectly launches the
vm-pop3d daemon.#!/bin/sh
#
case "$1" in
start)
echo -n "Starting vm-pop3d: "
/opt/local/sbin/vm-pop3d -d 10 -t 600
[... trimmed ...]But if a script itself is a daemon, use the
executable StartupItem type since that way it will be
launched directly and its health tracked automatically. When using
script StartupItems, the
startupitem.pidfile keyword must be used if you want
daemondo to monitor a daemon process and restart it
if it dies.For a given port, StartupItem keywords in category
script may not be used with an
executable StartupItem keyword.startupitem.startstartupitem.stopstartupitem.restartSpecify a shell script to start, stop, and restart the
daemon. In the absence of a restart key, the daemon will be
restarted by taking the stop action, followed by the start
action.Type: optionalDefault: noneValues: shell_scriptExamples:startupitem.start "${prefix}/share/mysql/mysql.server start"
startupitem.stop "${prefix}/share/mysql/mysql.server stop"
startupitem.restart "${prefix}/share/mysql/mysql.server restart"Wrap the stop, start, and restart values in quotes so
they will be placed in the wrapper as a single command.startupitem.initShell code that will be executed prior to any of the
options startupitem.start,
startupitem.stop and
startupitem.restart.Type: optionalDefault: noValues: shell_scriptExample:startupitem.init "BIN=${prefix}/sbin/bacula-fd"startupitem.pidfileThis keyword must be defined properly for
daemondo to be able to monitor daemons
launched via script StartupItems and restart them
if they die. It specifies two things: a process id (PID) file
handling method, and a pidfile name and path.Type: optionalDefault: [none] |
[${prefix}/var/run/${name}.pid]Values [none auto manual clean]
[/path/to/pidfile]Example:startupitem.pidfile auto ${prefix}/var/run/${name}.pidfilePID file handling options: - daemondo will not create or
track a PID file, so it won't know when a daemon
dies. - The started process is
expected to create a PID file that contains the PID of the
running daemon; daemondo then reads the PID from the file
and tracks the process. The started process must delete the
PID file if this is necessary. - The started process is
expected to create a PID file that contains the PID of the
running daemon; daemondo then reads the PID from the file
and tracks the process, and deletes the PID file if it
detects the daemon has died. - This option should only be
used if an executable StartupItem could be
used (daemondo launches a daemon directly)
and a port author wants a PID file
written for some special use. A PID file is not needed to
detect process death for daemons launched directly by
daemondo. As with executale StartupItems, daemondo remembers
the PID of the launched process and tracks it
automatically.Loading / Unloading StartupItems into launchdA port with a StartupItem places a link to a .plist file for the
port's daemon within /Library/LaunchDaemons/. A
.plist file is an XML file; MacPorts installs .plist files tagged as
disabled for the sake of security. You may enable a
startup script (tag the.plist file as enabled) and load
it into launchd with a single command as
shown.%%sudo launchctl load -w /Library/LaunchDaemons/org.macports.mysql5.plistYou may stop a running startup script, disable it (tag the.plist
file as disabled), and unload it from
launchd with a single command as shown.%%sudo launchctl unload -w /Library/LaunchDaemons/org.macports.mysql5.plistStartupItem InternalsDuring port installation a MacPorts StartupItem creates a .plist
file in ${prefix}/etc/LaunchDaemons/, and places
a symbolic link to the .plist file within
/Library/LaunchDaemons/.For example, the StartupItem for the mysql5 port is
org.macports.mysql5.plist, and it is linked as
shown.%%ls -l /Library/LaunchDaemonsorg.macports.mysql5.plist ->
/opt/local/etc/LaunchDaemons/org.macports.mysql5/org.macports.mysql5.plistFor script StartupItems, in addition to a .plist
file, a wrapper is also created.%%ls -l /opt/local/etc/LaunchDaemons/org.macports.mysql5/-rwxr-xr-x 2 root wheel 475 Aug 2 14:16 mysql5.wrapper
-rw-r--r-- 2 root wheel 975 Aug 2 14:16 org.macports.mysql5.plistThe
wrapper manipulates the script as specified in the startupitem.start
and startupitem.stop keywords. An example wrapper script snippet is
shown below.#!/bin/sh
#
# MacPorts generated daemondo support script
# Start
Start()
{
/opt/local/share/mysql5/mysql/mysql.server start
}
# Stop
Stop()
{
/opt/local/share/mysql5/mysql/mysql.server stop
}
[... trimmed ...]SEE ALSOportfile-global7, portfile-phase7, portfile-tcl7AUTHORSLandon Fuller landonf@macports.orgJuan Manuel Palacios jmpp@macports.orgMark Duling markd@macports.orgKevin Van Vechten kevin@opendarwin.orgJordan K. Hubbard jkh@macports.orgChris Ridd cjr@opendarwin.orgKevin Ballard eridius@macports.orgMarkus W. Weissmann mww@macports.org