manpagez: man (manual) pages & more
man launchd.plist(5)
Home | html | info | man

launchd.plist(5)            BSD File Formats Manual           launchd.plist(5)


NAME

     launchd.plist -- System wide and per-user daemon/agent configuration
     files


DESCRIPTION

     This document details the parameters that can be given to an XML property
     list that can be loaded into launchd with launchctl.


EXPECTATIONS

     Daemons or agents managed by launchd are expected to behave certain ways.

     A daemon or agent launched by launchd MUST NOT do the following in the
     process directly launched by launchd:

           o   Call daemon(3).
           o   Do the moral equivalent of daemon(3) by calling fork(2) and
               have the parent process exit(3) or _exit(2).

     A daemon or agent launched by launchd SHOULD NOT do the following as a
     part of their startup initialization:

           o   Setup the user ID or group ID.
           o   Setup the working directory.
           o   chroot(2)
           o   setsid(2)
           o   Close "stray" file descriptors.
           o   Change stdio(3) to /dev/null.
           o   Setup resource limits with setrusage(2).
           o   Setup priority with setpriority(2).
           o   Ignore the SIGTERM signal.

     A daemon or agent launched by launchd SHOULD:

           o   Launch on demand given criteria specified in the XML property
               list.  More information can be found later in this man page.
           o   Catch the SIGTERM signal.


XML PROPERTY LIST KEYS

     The following keys can be used to describe the configuration details of
     your daemon or agent.  Property lists are Apple's standard configuration
     file format. Please see plist(5) for more information. Please note: prop-
     erty list files are expected to have their name end in ".plist".  Also
     please note that it is the expected convention for launchd property list
     files to be named <Label>.plist.  Thus, if your job label is
     "com.apple.sshd", your plist file should be named "com.apple.sshd.plist".

     Label <string>
     This required key uniquely identifies the job to launchd.

     Disabled <boolean>
     This optional key is used as a hint to launchctl(1) that it should not
     submit this job to launchd when loading a job or jobs. The value of this
     key does NOT reflect the current state of the job on the running system.
     If you wish to know whether a job is loaded in launchd, reading this key
     from a configuration file yourself is not a sufficient test. You should
     query launchd for the presence of the job using the launchctl(1) list
     subcommand or use the ServiceManagement framework's SMJobCopyDictionary()
     method.

     Note that as of Mac OS X v10.6, this key's value in a configuration file
     conveys a default value, which is changed with the [-w] option of the
     launchctl(1) load and unload subcommands. These subcommands no longer
     modify the configuration file, so the value displayed in the configura-
     tion file is not necessarily the value that launchctl(1) will apply. See
     launchctl(1) for more information.

     Please also be mindful that you should only use this key if the provided
     on-demand and KeepAlive criteria are insufficient to describe the condi-
     tions under which your job needs to run. The cost to have a job loaded in
     launchd is negligible, so there is no harm in loading a job which only
     runs once or very rarely.

     UserName <string>
     This optional key specifies the user to run the job as. This key is only
     applicable when launchd is running as root.

     GroupName <string>
     This optional key specifies the group to run the job as. This key is only
     applicable when launchd is running as root. If UserName is set and Group-
     Name is not, the the group will be set to the default group of the user.

     inetdCompatibility <dictionary>
     The presence of this key specifies that the daemon expects to be run as
     if it were launched from inetd.

           Wait <boolean>
           This flag corresponds to the "wait" or "nowait" option of inetd. If
           true, then the listening socket is passed via the standard
           in/out/error file descriptors. If false, then accept(2) is called
           on behalf of the job, and the result is passed via the standard
           in/out/error descriptors.

     LimitLoadToHosts <array of strings>
     This configuration file only applies to the hosts listed with this key.
     Note: One should set kern.hostname in sysctl.conf(5) for this feature to
     work reliably.

     LimitLoadFromHosts <array of strings>
     This configuration file only applies to hosts NOT listed with this key.
     Note: One should set kern.hostname in sysctl.conf(5) for this feature to
     work reliably.

     LimitLoadToSessionType <string>
     This configuration file only applies to sessions of the type specified.
     This key is used in concert with the -S flag to launchctl.

     Program <string>
     This key maps to the first argument of execvp(3).  If this key is miss-
     ing, then the first element of the array of strings provided to the Pro-
     gramArguments will be used instead.  This key is required in the absence
     of the ProgramArguments key.

     ProgramArguments <array of strings>
     This key maps to the second argument of execvp(3).  This key is required
     in the absence of the Program key. Please note: many people are confused
     by this key. Please read execvp(3) very carefully!

     EnableGlobbing <boolean>
     This flag causes launchd to use the glob(3) mechanism to update the pro-
     gram arguments before invocation.

     EnableTransactions <boolean>
     This flag instructs launchd that the job promises to use
     vproc_transaction_begin(3) and vproc_transaction_end(3) to track out-
     standing transactions that need to be reconciled before the process can
     safely terminate. If no outstanding transactions are in progress, then
     launchd is free to send the SIGKILL signal.

     OnDemand <boolean>
     This key was used in Mac OS X 10.4 to control whether a job was kept
     alive or not. The default was true.  This key has been deprecated and
     replaced in Mac OS X 10.5 and later with the more powerful KeepAlive
     option.

     KeepAlive <boolean or dictionary of stuff>
     This optional key is used to control whether your job is to be kept con-
     tinuously running or to let demand and conditions control the invocation.
     The default is false and therefore only demand will start the job. The
     value may be set to true to unconditionally keep the job alive. Alterna-
     tively, a dictionary of conditions may be specified to selectively con-
     trol whether launchd keeps a job alive or not. If multiple keys are pro-
     vided, launchd ORs them, thus providing maximum flexibility to the job to
     refine the logic and stall if necessary. If launchd finds no reason to
     restart the job, it falls back on demand based invocation.  Jobs that
     exit quickly and frequently when configured to be kept alive will be
     throttled to converve system resources.

           SuccessfulExit <boolean>
           If true, the job will be restarted as long as the program exits and
           with an exit status of zero.  If false, the job will be restarted
           in the inverse condition.  This key implies that "RunAtLoad" is set
           to true, since the job needs to run at least once before we can get
           an exit status.

           NetworkState <boolean>
           If true, the job will be kept alive as long as the network is up,
           where up is defined as at least one non-loopback interface being up
           and having IPv4 or IPv6 addresses assigned to them.  If false, the
           job will be kept alive in the inverse condition.

           PathState <dictionary of booleans>
           Each key in this dictionary is a file-system path. If the value of
           the key is true, then the job will be kept alive as long as the
           path exists.  If false, the job will be kept alive in the inverse
           condition. The intent of this feature is that two or more jobs may
           create semaphores in the file-system namespace.

           OtherJobEnabled <dictionary of booleans>
           Each key in this dictionary is the label of another job. If the
           value of the key is true, then this job is kept alive as long as
           that other job is enabled. Otherwise, if the value is false, then
           this job is kept alive as long as the other job is disabled.  This
           feature should not be considered a substitute for the use of IPC.

     RunAtLoad <boolean>
     This optional key is used to control whether your job is launched once at
     the time the job is loaded. The default is false.

     RootDirectory <string>
     This optional key is used to specify a directory to chroot(2) to before
     running the job.

     WorkingDirectory <string>
     This optional key is used to specify a directory to chdir(2) to before
     running the job.

     EnvironmentVariables <dictionary of strings>
     This optional key is used to specify additional environmental variables
     to be set before running the job.

     Umask <integer>
     This optional key specifies what value should be passed to umask(2)
     before running the job. Known bug: Property lists don't support octal, so
     please convert the value to decimal.

     TimeOut <integer>
     The recommended idle time out (in seconds) to pass to the job. If no
     value is specified, a default time out will be supplied by launchd for
     use by the job at check in time.

     ExitTimeOut <integer>
     The amount of time launchd waits before sending a SIGKILL signal. The
     default value is 20 seconds. The value zero is interpreted as infinity.

     ThrottleInterval <integer>
     This key lets one override the default throttling policy imposed on jobs
     by launchd.  The value is in seconds, and by default, jobs will not be
     spawned more than once every 10 seconds.  The principle behind this is
     that jobs should linger around just in case they are needed again in the
     near future. This not only reduces the latency of responses, but it
     encourages developers to amortize the cost of program invocation.

     InitGroups <boolean>
     This optional key specifies whether initgroups(3) should be called before
     running the job.  The default is true in 10.5 and false in 10.4. This key
     will be ignored if the UserName key is not set.

     WatchPaths <array of strings>
     This optional key causes the job to be started if any one of the listed
     paths are modified.

     QueueDirectories <array of strings>
     Much like the WatchPaths option, this key will watch the paths for modi-
     fications. The difference being that the job will only be started if the
     path is a directory and the directory is not empty.

     StartOnMount <boolean>
     This optional key causes the job to be started every time a filesystem is
     mounted.

     StartInterval <integer>
     This optional key causes the job to be started every N seconds.  If the
     system is asleep, the job will be started the next time the computer
     wakes up.  If multiple intervals transpire before the computer is woken,
     those events will be coalesced into one event upon wake from sleep.

     StartCalendarInterval <dictionary of integers or array of dictionary of
     integers>
     This optional key causes the job to be started every calendar interval as
     specified. Missing arguments are considered to be wildcard. The semantics
     are much like crontab(5).  Unlike cron which skips job invocations when
     the computer is asleep, launchd will start the job the next time the com-
     puter wakes up.  If multiple intervals transpire before the computer is
     woken, those events will be coalesced into one event upon wake from
     sleep.

           Minute <integer>
           The minute on which this job will be run.

           Hour <integer>
           The hour on which this job will be run.

           Day <integer>
           The day on which this job will be run.

           Weekday <integer>
           The weekday on which this job will be run (0 and 7 are Sunday).

           Month <integer>
           The month on which this job will be run.

     StandardInPath <string>
     This optional key specifies what file should be used for data being sup-
     plied to stdin when using stdio(3).

     StandardOutPath <string>
     This optional key specifies what file should be used for data being sent
     to stdout when using stdio(3).

     StandardErrorPath <string>
     This optional key specifies what file should be used for data being sent
     to stderr when using stdio(3).

     Debug <boolean>
     This optional key specifies that launchd should adjust its log mask tem-
     porarily to LOG_DEBUG while dealing with this job.

     WaitForDebugger <boolean>
     This optional key specifies that launchd should instruct the kernel to
     have the job wait for a debugger to attach before any code in the job is
     executed.

     SoftResourceLimits <dictionary of integers>

     HardResourceLimits <dictionary of integers>
     Resource limits to be imposed on the job. These adjust variables set with
     setrlimit(2).  The following keys apply:

           Core <integer>
           The largest size (in bytes) core file that may be created.

           CPU <integer>
           The maximum amount of cpu time (in seconds) to be used by each
           process.

           Data <integer>
           The maximum size (in bytes) of the data segment for a process; this
           defines how far a program may extend its break with the sbrk(2)
           system call.

           FileSize <integer>
           The largest size (in bytes) file that may be created.

           MemoryLock <integer>
           The maximum size (in bytes) which a process may lock into memory
           using the mlock(2) function.

           NumberOfFiles <integer>
           The maximum number of open files for this process.  Setting this
           value in a system wide daemon will set the sysctl(3) kern.maxfiles
           (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits)
           value in addition to the setrlimit(2) values.

           NumberOfProcesses <integer>
           The maximum number of simultaneous processes for this user id.
           Setting this value in a system wide daemon will set the sysctl(3)
           kern.maxproc (SoftResourceLimits) or kern.maxprocperuid
           (HardResourceLimits) value in addition to the setrlimit(2) values.

           ResidentSetSize <integer>
           The maximum size (in bytes) to which a process's resident set size
           may grow.  This imposes a limit on the amount of physical memory to
           be given to a process; if memory is tight, the system will prefer
           to take memory from processes that are exceeding their declared
           resident set size.

           Stack <integer>
           The maximum size (in bytes) of the stack segment for a process;
           this defines how far a program's stack segment may be extended.
           Stack extension is performed automatically by the system.

     Nice <integer>
     This optional key specifies what nice(3) value should be applied to the
     daemon.

     ProcessType <string>
     This optional key describes, at a high level, the intended purpose of the
     job.  The system will apply resource limits based on what kind of job it
     is. If left unspecified, the system will apply light resource limits to
     the job, throttling its CPU usage and I/O bandwidth. The following are
     valid values:

           Background
           Background jobs are generally processes that do work that was not
           directly requested by the user. The resource limits applied to
           Background jobs are intended to prevent them from disrupting the
           user experience.

           Standard
           Standard jobs are equivalent to no ProcessType being set.

           Adaptive
           Adaptive jobs move between the Background and Interactive classifi-
           cations based on activity over XPC connections. See
           xpc_transaction_begin(3) for details.

           Interactive
           Interactive jobs run with the same resource limitations as apps,
           that is to say, none. Interactive jobs are critical to maintaining
           a responsive user experience, and this key should only be used if
           an app's ability to be responsive depends on it, and cannot be made
           Adaptive.

     LegacyTimers <boolean>
     This optional key controls the behavior of timers created by the job. By
     default on OS X Mavericks version 10.9 and later, timers created by
     launchd jobs are coalesced. Batching the firing of timers with similar
     deadlines improves the overall energy efficiency of the system. If this
     key is set to true, timers created by the job will opt into less effi-
     cient but more precise behavior and not be coalesced with other timers.

     AbandonProcessGroup <boolean>
     When a job dies, launchd kills any remaining processes with the same
     process group ID as the job.  Setting this key to true disables that
     behavior.

     LowPriorityIO <boolean>
     This optional key specifies whether the kernel should consider this dae-
     mon to be low priority when doing file system I/O.

     LaunchOnlyOnce <boolean>
     This optional key specifies whether the job can only be run once and only
     once.  In other words, if the job cannot be safely respawned without a
     full machine reboot, then set this key to be true.

     MachServices <dictionary of booleans or a dictionary of dictionaries>
     This optional key is used to specify Mach services to be registered with
     the Mach bootstrap sub-system.  Each key in this dictionary should be the
     name of service to be advertised. The value of the key must be a boolean
     and set to true.  Alternatively, a dictionary can be used instead of a
     simple true value.

           ResetAtClose <boolean>
           If this boolean is false, the port is recycled, thus leaving
           clients to remain oblivious to the demand nature of job. If the
           value is set to true, clients receive port death notifications when
           the job lets go of the receive right. The port will be recreated
           atomically with respect to bootstrap_look_up() calls, so that
           clients can trust that after receiving a port death notification,
           the new port will have already been recreated. Setting the value to
           true should be done with care. Not all clients may be able to han-
           dle this behavior. The default value is false.

           HideUntilCheckIn <boolean>
           Reserve the name in the namespace, but cause bootstrap_look_up() to
           fail until the job has checked in with launchd.

     Finally, for the job itself, the values will be replaced with Mach ports
     at the time of check-in with launchd.

     Sockets <dictionary of dictionaries... OR dictionary of array of
     dictionaries...>
     This optional key is used to specify launch on demand sockets that can be
     used to let launchd know when to run the job. The job must check-in to
     get a copy of the file descriptors using APIs outlined in launch(3).  The
     keys of the top level Sockets dictionary can be anything. They are meant
     for the application developer to use to differentiate which descriptors
     correspond to which application level protocols (e.g. http vs. ftp vs.
     DNS...).  At check-in time, the value of each Sockets dictionary key will
     be an array of descriptors. Daemon/Agent writers should consider all
     descriptors of a given key to be to be effectively equivalent, even
     though each file descriptor likely represents a different networking pro-
     tocol which conforms to the criteria specified in the job configuration
     file.

     The parameters below are used as inputs to call getaddrinfo(3).

           SockType <string>
           This optional key tells launchctl what type of socket to create.
           The default is "stream" and other valid values for this key are
           "dgram" and "seqpacket" respectively.

           SockPassive <boolean>
           This optional key specifies whether listen(2) or connect(2) should
           be called on the created file descriptor. The default is true ("to
           listen").

           SockNodeName <string>
           This optional key specifies the node to connect(2) or bind(2) to.

           SockServiceName <string>
           This optional key specifies the service on the node to connect(2)
           or bind(2) to.

           SockFamily <string>
           This optional key can be used to specifically request that "IPv4"
           or "IPv6" socket(s) be created.

           SockProtocol <string>
           This optional key specifies the protocol to be passed to socket(2).
           The only value understood by this key at the moment is "TCP".

           SockPathName <string>
           This optional key implies SockFamily is set to "Unix". It specifies
           the path to connect(2) or bind(2) to.

           SecureSocketWithKey <string>
           This optional key is a variant of SockPathName. Instead of binding
           to a known path, a securely generated socket is created and the
           path is assigned to the environment variable that is inherited by
           all jobs spawned by launchd.

           SockPathMode <integer>
           This optional key specifies the mode of the socket. Known bug:
           Property lists don't support octal, so please convert the value to
           decimal.

           Bonjour <boolean or string or array of strings>
           This optional key can be used to request that the service be regis-
           tered with the mDNSResponder(8).  If the value is boolean, the ser-
           vice name is inferred from the SockServiceName.

           MulticastGroup <string>
           This optional key can be used to request that the datagram socket
           join a multicast group.  If the value is a hostname, then
           getaddrinfo(3) will be used to join the correct multicast address
           for a given socket family.  If an explicit IPv4 or IPv6 address is
           given, it is required that the SockFamily family also be set, oth-
           erwise the results are undefined.


DEPENDENCIES

     Unlike many bootstrapping daemons, launchd has no explicit dependency
     model.  Interdependencies are expected to be solved through the use of
     IPC.  It is therefore in the best interest of a job developer who expects
     dependents to define all of the sockets in the configuration file. This
     has the added benefit of making it possible to start the job based on
     demand instead of immediately.


EXAMPLE XML PROPERTY LISTS

     The following XML Property List simply keeps "exampled" running continu-
     ously:

           <?xml version="1.0" encoding="UTF-8"?>
           <!DOCTYPE plist PUBLIC -//Apple Computer//DTD PLIST 1.0//EN
           http://www.apple.com/DTDs/PropertyList-1.0.dtd >
           <plist version="1.0">
           <dict>
                <key>Label</key>
                <string>com.example.exampled</string>
                <key>ProgramArguments</key>
                <array>
                     <string>exampled</string>
                </array>
                <key>KeepAlive</key>
                <true/>
           </dict>
           </plist>


FILES

     ~/Library/LaunchAgents         Per-user agents provided by the user.
     /Library/LaunchAgents          Per-user agents provided by the adminis-
                                    trator.
     /Library/LaunchDaemons         System-wide daemons provided by the admin-
                                    istrator.
     /System/Library/LaunchAgents   Per-user agents provided by Mac OS X.
     /System/Library/LaunchDaemons  System-wide daemons provided by Mac OS X.


SEE ALSO

     launchctl(1), sysctl(3), launchd(8), plist(5)

Darwin                            1 May, 2009                           Darwin

Mac OS X 10.9.2 - Generated Fri Feb 28 08:39:19 CST 2014