launchd/src/launchd.plist.5

   1 .Dd September 30, 2004
   2 .Dt launchd.plist 5
   3 .Os Darwin
   4 .Sh NAME
   5 .Nm launchd.plist
   6 .Nd System wide and per-user daemon/agent configuration files
   7 .Sh DESCRIPTION
   8 This document details the parameters that can be given to an XML property list that can be loaded into
   9 .Nm launchd
  10 with
  11 .Nm launchctl .
  12 .Sh EXPECTATIONS
  13 Daemons or agents managed by
  14 .Nm launchd
  15 are expected to behave certain ways.
  16 .Pp
  17 A daemon or agent launched by
  18 .Nm launchd
  19 MUST NOT do the following in the process directly launched by
  20 .Nm launchd :
  21 .Pp
  22 .Bl -bullet -offset indent -compact
  23 .It
  24 Call
  25 .Xr daemon 3 .
  26 .It
  27 Do the moral equivalent of
  28 .Xr daemon 3
  29 by calling
  30 .Xr fork 2
  31 and have the parent process
  32 .Xr exit 3
  33 or
  34 .Xr _exit 2 .
  35 .El
  36 .Pp
  37 A daemon or agent launched by
  38 .Nm launchd
  39 SHOULD NOT do the following as a part of their startup initialization:
  40 .Pp
  41 .Bl -bullet -offset indent -compact
  42 .It
  43 Setup the user ID or group ID.
  44 .It
  45 Setup the working directory.
  46 .It
  47 .Xr chroot 2
  48 .It
  49 .Xr setsid 2
  50 .It
  51 Close "stray" file descriptors.
  52 .It
  53 Change
  54 .Xr stdio 3
  55 to /dev/null.
  56 .It
  57 Setup resource limits with
  58 .Xr setrusage 2 .
  59 .It
  60 Setup priority with
  61 .Xr setpriority 2 .
  62 .It
  63 Ignore the SIGTERM signal.
  64 .El
  65 .Pp
  66 A daemon or agent launched by
  67 .Nm launchd
  68 SHOULD:
  69 .Pp
  70 .Bl -bullet -offset indent -compact
  71 .It
  72 Launch on demand given criteria specified in the XML property list.
  73 More information can be found later in this man page.
  74 .It
  75 Catch the SIGTERM signal.
  76 .El
  77 .Sh XML PROPERTY LIST KEYS
  78 The follow keys can be used to describe the configuration details of your daemon or agent.
  79 Property lists are Apple's standard configuration file format. Please see
  80 .Xr plist 5
  81 for more information. Please note. Property list files are expected to have their name end in ".plist".
  82 .Pp
  83 .Bl -ohang
  84 .It Sy Label <string>
  85 This required key uniquely identifies the job to
  86 .Nm launchd .
  87 .It Sy Disabled <boolean>
  88 This optional key is used to disable your job. The default is false.
  89 .It Sy UserName <string>
  90 This optional key specifies the user to run the job as. This key is only applicable when launchd is running as root.
  91 .It Sy GroupName <string>
  92 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 GroupName is not, the the group will be set to the default group of the user.
  93 .It Sy inetdCompatibility <dictionary>
  94 The presence of this key specifies that the daemon expects to be run as if it were launched from inetd.
  95 .Bl -ohang -offset indent
  96 .It Sy Wait <boolean>
  97 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
  98 .Xr accept 2
  99 is called on behalf of the job, and the result is passed via the standard in/out/error descriptors.
 100 .El
 101 .It Sy LimitLoadToHosts <array of strings>
 102 This configuration file only applies to the hosts listed with this key.
 103 .It Sy LimitLoadFromHosts <array of strings>
 104 This configuration file only applies to hosts NOT listed with this key.
 105 .It Sy LimitLoadToSessionType <string>
 106 This configuration file only applies to sessions of the type specified. This key is used
 107 in concert with the -S flag to
 108 .Nm launchctl .
 109 .It Sy ProgramArguments <array of strings>
 110 This required key maps to the second argument of
 111 .Xr execvp 3 .
 112 .It Sy Program <string>
 113 This optional key maps to the first argument of
 114 .Xr execvp 3 .
 115 If this key is missing, then the first element of the array of strings provided to the ProgramArguments will be used instead.
 116 .It Sy EnableGlobbing <boolean>
 117 This flag causes
 118 .Nm launchd
 119 to use the
 120 .Xr glob 3
 121 mechanism to update the program arguments before invocation.
 122 .It Sy OnDemand <boolean>
 123 This key was used in Mac OS X 10.4 to control whether a job was kept alive or not. The default was true.
 124 This key has been deprecated and replaced in Mac OS X 10.5 with the more powerful KeepAlive option.
 125 .It Sy KeepAlive <boolean or dictionary of stuff>
 126 This optional key is used to control whether your job is to be kept
 127 continuously running or to let demand and conditions control the invocation. The
 128 default is false and therefore only demand will start the job. The value may be
 129 set to true to unconditionally keep the job alive. Alternatively, a dictionary
 130 of conditions may be specified to selectively control whether
 131 .Nm launchd
 132 keeps a job alive or not. If multiple keys are provided, launchd ORs them, thus
 133 providing maximum flexibility to the job to refine the logic and stall if necessary. If
 134 .Nm launchd
 135 finds no reason to restart the job, it falls back on demand based invocation.
 136 Jobs that exit quickly and frequently when configured to be kept alive will be
 137 throttled to converve system resources.
 138 .Bl -ohang -offset indent
 139 .It Sy SuccessfulExit <boolean>
 140 If true, the job will be restarted as long as the program exits and with an exit
 141 status of zero.  If false, the job will be restarted in the inverse condition.
 142 This key implies that "RunAtLoad" is set to true, since the job needs to run at
 143 least once before we can get an exit status.
 144 .It Sy NetworkState <boolean>
 145 If true, the job will be kept alive as long as the network is up, where up is
 146 defined as at least one non-loopback interface being up and having IPv4 or IPv6
 147 addresses assigned to them.
 148 If false, the job will be kept alive in the inverse condition.
 149 .It Sy PathState <dictionary of booleans>
 150 Each key in this dictionary is a file-system path. If the value of the key is
 151 true, then the job will be kept alive as long as the path exists.
 152 If false, the job will be kept alive in the inverse condition. The intent of this
 153 feature is that two or more jobs may create semaphores in the file-system namespace.
 154 .El
 155 .It Sy RunAtLoad <boolean>
 156 This optional key is used to control whether your job is launched once at the time the job is loaded. The default is false.
 157 .It Sy RootDirectory <string>
 158 This optional key is used to specify a directory to
 159 .Xr chroot 2
 160 to before running the job.
 161 .It Sy WorkingDirectory <string>
 162 This optional key is used to specify a directory to
 163 .Xr chdir 2
 164 to before running the job.
 165 .It Sy EnvironmentVariables <dictionary of strings>
 166 This optional key is used to specify additional environmental variables to be setup before running the job.
 167 .It Sy Umask <integer>
 168 This optional key specifies what value should be passed to
 169 .Xr umask 2
 170 before running the job. Known bug: Property lists don't support octal, so please convert the value to decimal.
 171 .It Sy TimeOut <integer>
 172 The recommended time out (in seconds) to pass to the job. If no value is specified, a default time out will be supplied by
 173 .Nm launchd
 174 for use by the job at check in time.
 175 .It Sy InitGroups <boolean>
 176 This optional key specifies whether the job should have
 177 .Xr initgroups 3
 178 be called before running the job.
 179 The default is false.
 180 .It Sy WatchPaths <array of strings>
 181 This optional key causes the job to be started if any one of the listed paths are modified.
 182 .It Sy QueueDirectories <array of strings>
 183 Much like the WatchPaths option, this key will watch the paths for modifications. The difference being that the job will only be started if the path is a directory and the directory is not empty.
 184 .It Sy StartInterval <integer>
 185 This optional key causes the job to be started every N seconds.
 186 If the system is asleep, the job will be started the next time the computer
 187 wakes up.  If multiple intervals transpire before the computer is woken, those
 188 events will be coalesced into one event upon wake from sleep.
 189 .It Sy StartCalendarInterval <dictionary of integers or array of dictionary of integers>
 190 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
 191 .Xr crontab 5 .
 192 Unlike cron which skips job invocations when the computer is asleep, launchd
 193 will start the job the next time the computer wakes up.  If multiple intervals
 194 transpire before the computer is woken, those events will be coalesced into one
 195 event upon wake from sleep.
 196 .Bl -ohang -offset indent
 197 .It Sy Minute <integer>
 198 The minute on which this job will be run.
 199 .It Sy Hour <integer>
 200 The hour on which this job will be run.
 201 .It Sy Day <integer>
 202 The day on which this job will be run.
 203 .It Sy Weekday <integer>
 204 The weekday on which this job will be run (0 and 7 are Sunday).
 205 .It Sy Month <integer>
 206 The month on which this job will be run.
 207 .El
 208 .It Sy StandardOutPath <string>
 209 This optional key specifies what file should be used for data being sent to stdout when using
 210 .Xr stdio 3 .
 211 .It Sy StandardErrorPath <string>
 212 This optional key specifies what file should be used for data being sent to stderr when using
 213 .Xr stdio 3 .
 214 .It Sy Debug <boolean>
 215 This optional key specifies that
 216 .Nm launchd
 217 should adjust its log mask temporarily to LOG_DEBUG while dealing with this job.
 218 .It Sy WaitForDebugger <boolean>
 219 This optional key specifies that
 220 .Nm launchd
 221 should instruct the kernel to have the job wait for a debugger to attach before any code in the job is executed.
 222 .It Sy SoftResourceLimits <dictionary of integers>
 223 .It Sy HardResourceLimits <dictionary of integers>
 224 Resource limits to be imposed on the job. These adjust variables set with
 225 .Xr setrlimit 2 .
 226 The following keys apply:
 227 .Bl -ohang -offset indent
 228 .It Sy Core <integer>
 229 The largest size (in bytes) core file that may be created.
 230 .It Sy CPU <integer>
 231 The maximum amount of cpu time (in seconds) to be used by each process.
 232 .It Sy Data <integer>
 233 The maximum size (in bytes) of the data segment for a process; this defines how far a program may extend its break with the
 234 .Xr sbrk 2
 235 system call.
 236 .It Sy FileSize <integer>
 237 The largest size (in bytes) file that may be created.
 238 .It Sy MemoryLock <integer>
 239 The maximum size (in bytes) which a process may lock into memory using the
 240 .Xr mlock 2
 241 function.
 242 .It Sy NumberOfFiles <integer>
 243 The maximum number of open files for this process.
 244 .It Sy NumberOfProcesses <integer>
 245 The maximum number of simultaneous processes for this user id.
 246 .It Sy ResidentSetSize <integer>
 247 The maximum size (in bytes) to which a process's resident set size may grow.
 248 This imposes a limit on the amount of physical memory to be given to a process;
 249 if memory is tight, the system will prefer to take memory from processes that
 250 are exceeding their declared resident set size.
 251 .It Sy Stack <integer>
 252 The maximum size (in bytes) of the stack segment for a process; this defines
 253 how far a program's stack segment may be extended.  Stack extension is
 254 performed automatically by the system.
 255 .El
 256 .It Sy Nice <integer>
 257 This optional key specifies what
 258 .Xr nice 3
 259 value should be applied to the daemon.
 260 .It Sy LowPriorityIO <boolean>
 261 This optional key specifies whether the kernel should consider this daemon to be low priority when doing file system I/O.
 262 .It Sy MachServices <dictionary of booleans>
 263 This optional key is used to specify Mach services to be registered with the
 264 Mach bootstrap sub-system.  Each key in this dictionary should be the name of
 265 service to be advertised.  The value of the key must be a boolean. If the
 266 boolean is true, the port is recycled, thus leaving clients to remain oblivious
 267 to the demand nature of job. If the value is set to false, clients receive port
 268 death notifications when the job lets go of the receive right. The port will be
 269 recreated atomically with respect to bootstrap_look_up() calls, so that clients
 270 can trust that after receiving a port death notification, the new port will
 271 have already been recreated. Setting the value to false should be done with
 272 care. Not all clients may be able to handle this behavior. Finally, for the job
 273 itself, the values will be replaced with Mach ports at the time of check-in
 274 with
 275 .Nm launchd .
 276 .It Sy Sockets <dictionary of dictionaries... OR dictionary of array of dictionaries...>
 277 This optional key is used to specify launch on demand sockets that can be used to let
 278 .Nm launchd
 279 know when to run the job. The job must check-in to get a copy of the file descriptors using APIs outlined in
 280 .Xr launch 3 .
 281 The keys of the top level Sockets dictionary can be anything. They are meant for the application developer to use to
 282 differentiate different which descriptors correspond to which application level protocols (e.g. http vs. ftp vs. DNS...).
 283 At check in time, the value of each Sockets dictionary key will be an array of descriptors. Daemon/Agent writers should
 284 consider all descriptors of a given key to be to be effectively equivalent, even though each file descriptor likely represents
 285 a different networking protocol which conforms to the criteria specified in the job configuration file.
 286 .Pp
 287 The paramters below are used as inputs to call
 288 .Xr getaddrinfo 3 .
 289 .Bl -ohang -offset indent
 290 .It Sy SockType <string>
 291 This optional key tells
 292 .Nm launchctl
 293 what type of socket to create. The default is "stream" and other valid values for this key
 294 are "dgram" and "seqpacket" respectively.
 295 .It Sy SockPassive <boolean>
 296 This optional key specifies whether
 297 .Xr listen 2
 298 or
 299 .Xr connect 2
 300 should be called on the created file descriptor. The default is true ("to listen").
 301 .It Sy SockNodeName <string>
 302 This optional key specifies the node to
 303 .Xr connect 2
 304 or
 305 .Xr bind 2
 306 to.
 307 .It Sy SockServiceName <string>
 308 This optional key specifies the service on the node to
 309 .Xr connect 2
 310 or
 311 .Xr bind 2
 312 to.
 313 .It Sy SockFamily <string>
 314 This optional key can be used to specifically request that "IPv4" or "IPv6" socket(s) be created.
 315 .It Sy SockProtocol <string>
 316 This optional key specifies the protocol to be passed to
 317 .Xr socket 2 .
 318 The only value understood by this key at the moment is "TCP".
 319 .It Sy SockPathName <string>
 320 This optional key implies SockFamily is set to "Unix". It specifies the path to
 321 .Xr connect 2
 322 or
 323 .Xr bind 2
 324 to.
 325 .It Sy SecureSocketWithKey <string>
 326 This optional key is a variant of SockPathName. Instead of binding to a known
 327 path, a securely generated socket is created and the path is assigned to the
 328 environment variable that is inherited by all jobs spawned by launchd.
 329 .It Sy SockPathMode <integer>
 330 This optional key specifies the mode of the socket. Known bug: Property lists
 331 don't support octal, so please convert the value to decimal.
 332 .It Sy Bonjour <boolean or string or array of strings>
 333 This optional key can be used to request that the service be registered with the
 334 .Xr mDNSResponder 8 .
 335 If the value is boolean, the service name is inferred from the SockServiceName.
 336 .It Sy MulticastGroup <string>
 337 This optional key can be used to request that the datagram socket join a multicast group.
 338 If the value is a hostname, then
 339 .Xr getaddrinfo 3
 340 will be used to join the correct multicast address for a given socket family.
 341 If an explicit IPv4 or IPv6 address is given, it is required that the
 342 SockFamily family also be set, otherwise the results are undefined.
 343 .El
 344 .El
 345 .Pp
 346 .Sh DEPENDENCIES
 347 Unlike many bootstrapping daemons, launchd has no explicit dependency model.
 348 Interdependencies are expected to be solved through the use of IPC.
 349 It is therefore in the best interest of a job developer who expects dependents
 350 to define all of the sockets in the configuration file. This has the added
 351 benefit of making it possible to start the job based on demand instead of
 352 immediately.
 353 .Sh EXAMPLE XML PROPERTY LISTS
 354 .Pp
 355 The following XML Property List simply keeps "exampled" running continuously:
 356 .Pp
 357 .Dl <?xml version="1.0" encoding="UTF-8"?>
 358 .Dl <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 359 .Dl <plist version="1.0">
 360 .Dl <dict>
 361 .Dl     <key>Label</key>
 362 .Dl     <string>com.example.exampled</string>
 363 .Dl     <key>ProgramArguments</key>
 364 .Dl     <array>
 365 .Dl             <string>exampled</string>
 366 .Dl     </array>
 367 .Dl     <key>KeepAlive</key>
 368 .Dl     <true/>
 369 .Dl </dict>
 370 .Dl </plist>
 371 .Pp
 372 .Sh FILES
 373 .Bl -tag -width "/System/Library/LaunchDaemons" -compact
 374 .It Pa ~/Library/LaunchAgents
 375 Per-user agents provided by the user.
 376 .It Pa /Library/LaunchAgents
 377 Per-user agents provided by the administrator.
 378 .It Pa /Library/LaunchDaemons
 379 System wide daemons provided by the administrator.
 380 .It Pa /System/Library/LaunchAgents
 381 Mac OS X Per-user agents.
 382 .It Pa /System/Library/LaunchDaemons
 383 Mac OS X System wide daemons.
 384 .El
 385 .Sh SEE ALSO
 386 .Xr launchctl 1 ,
 387 .Xr launch 3 ,
 388 .Xr launchd 8 ,
 389 .Xr plist 5