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 .Xr fork 2
  25 and have the parent process
  26 .Xr exit 3
  27 or
  28 .Xr _exit 2 .
  29 .It
  30 Call
  31 .Xr daemon 3
  32 .El
  33 .Pp
  34 A daemon or agent launched by
  35 .Nm launchd
  36 SHOULD NOT do the following as a part of their startup initialization:
  37 .Pp
  38 .Bl -bullet -offset indent -compact
  39 .It
  40 Setup the user ID or group ID.
  41 .It
  42 Setup the working directory.
  43 .It
  44 .Xr chroot 2
  45 .It
  46 .Xr setsid 2
  47 .It
  48 Close "stray" file descriptors.
  49 .It
  50 Change
  51 .Xr stdio 3
  52 to /dev/null.
  53 .It
  54 Setup resource limits with
  55 .Xr setrusage 2 .
  56 .It
  57 Setup priority with
  58 .Xr setpriority 2 .
  59 .It
  60 Ignore the SIGTERM signal.
  61 .El
  62 .Pp
  63 A daemon or agent launched by
  64 .Nm launchd
  65 SHOULD:
  66 .Pp
  67 .Bl -bullet -offset indent -compact
  68 .It
  69 Launch on demand given criteria specified in the XML property list.
  70 More information can be found in
  71 .Xr launch 3 .
  72 .It
  73 Catch the SIGTERM signal.
  74 .El
  75 .Sh XML PROPERTY LIST KEYS
  76 The follow keys can be used to describe the configuration details of your daemon or agent.
  77 Property lists files are expected to have their name end in ".plist" but that is not strictly required.
  78 .Pp
  79 .Bl -ohang
  80 .It Sy Label <string>
  81 This required key uniquely identifies the job to
  82 .Nm launchd .
  83 .It Sy Disabled <boolean>
  84 This optional key is used to disable your job. The default is false.
  85 .It Sy UserName <string>
  86 This optional key specifies the user to run the job as. The default is the user who submitted the job to
  87 .Nm launchd .
  88 .It Sy GroupName <string>
  89 This optional key specifies the user to run the job as. The default is the group of the user who submitted the job to
  90 .Nm launchd .
  91 .It Sy inetdCompatibility <dictionary>
  92 The presence of this key specifies that the daemon expects to be run as if it were launched from
  93 .Xr inetd 8 .
  94 This flag is incompatible with the ServiceIPC key.
  95 .Bl -ohang -offset indent
  96 .It Sy Wait <boolean>
  97 This flag corresponds to the "wait" or "nowait" option of
  98 .Xr inetd 8 .
  99 .El
 100 .It Sy ProgramArguments <array of strings>
 101 This required key maps to the second argument of
 102 .Xr execvp 3 .
 103 .It Sy Program <string>
 104 This optional key maps to the first argument of
 105 .Xr execvp 3 .
 106 If this key is missing, then the first element of the array of strings provided to the ProgramArguments will be used instead.
 107 .It Sy OnDemand <boolean>
 108 This optional key is used to control whether your job is launched based on demand or to be kept continuously running. The default is true.
 109 .It Sy RunAtLoad <boolean>
 110 This optional key is used to control whether your job is launched once at the time the job is loaded. The default is false.
 111 .It Sy RootDirectory <string>
 112 This optional key is used to specific a directory to
 113 .Xr chroot 2
 114 to before running the job.
 115 .It Sy WorkingDirectory <string>
 116 This optional key is used to specific a directory to
 117 .Xr chdir 2
 118 to before running the job.
 119 .It Sy ServiceDescription <string>
 120 This optional key is used to specify a human readable description of the purpose of the job.
 121 .It Sy EnvironmentVariables <dictionary of strings>
 122 This optional key is used to specify additional environmental variables to be setup before running the job.
 123 .It Sy Umask <integer>
 124 This optional key specifies what value should be passed to
 125 .Xr umask 2
 126 before running the job.
 127 .It Sy ServiceIPC <boolean>
 128 This optional key specifies whether the job participates in advanced communication with
 129 .Nm launchd .
 130 The default is false. This flag is incompatible with the inetdCompatibility key.
 131 .It Sy TimeOut <integer>
 132 The recommended time out to pass to the job. If no value is specified, a default time out will be supplied by
 133 .Nm launchd
 134 for use by the job at check in time.
 135 .It Sy InitGroups <boolean>
 136 This optional key specifies whether the job should have
 137 .Xr initgroups 3
 138 be called before running the job.
 139 The default is false.
 140 .It Sy WatchPaths <array of strings>
 141 This optional key causes the job to be started if any one of the listed paths are modified.
 142 .It Sy QueueDirectories <array of strings>
 143 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.
 144 .It Sy StartInterval <integer>
 145 This optional key causes the job to be started every N seconds.
 146 If the system is asleep, the job will be started the next time the computer
 147 wakes up.  If multiple intervals transpire before the computer is woken, those
 148 events will be coalesced into one event upon wake from sleep.
 149 .It Sy StartCalendarInterval <dictionary of integers>
 150 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
 151 .Xr crontab 5 .
 152 Unlike cron which skips job invocations when the computer is asleep, launchd
 153 will start the job the next time the computer wakes up.  If multiple intervals
 154 transpire before the computer is woken, those events will be coalesced into one
 155 event upon wake from sleep.
 156 .Bl -ohang -offset indent
 157 .It Sy Minute <integer>
 158 The minute on which this job will be run.
 159 .It Sy Hour <integer>
 160 The hour on which this job will be run.
 161 .It Sy Day <integer>
 162 The day on which this job will be run.
 163 .It Sy Weekday <integer>
 164 The weekday on which this job will be run (0 and 7 are Sunday).
 165 .It Sy Month <integer>
 166 The month on which this job will be run.
 167 .El
 168 .It Sy StandardOutPath <string>
 169 This optional key specifies what file should be used for data being sent to stdout when using
 170 .Xr stdio 3 .
 171 .It Sy StandardErrorPath <string>
 172 This optional key specifies what file should be used for data being sent to stderr when using
 173 .Xr stdio 3 .
 174 .It Sy Debug <boolean>
 175 This optional key specifies that
 176 .Nm launchd
 177 should adjust its log mask temporarily to LOG_DEBUG while dealing with this job.
 178 .It Sy SoftResourceLimits <dictionary of integers>
 179 .It Sy HardResourceLimits <dictionary of integers>
 180 Resource limits to be imposed on the job. These adjust variables set with
 181 .Xr setrlimit 2 .
 182 The following keys apply:
 183 .Bl -ohang -offset indent
 184 .It Sy Core <integer>
 185 The largest size (in bytes) core file that may be created.
 186 .It Sy CPU <integer>
 187 The maximum amount of cpu time (in seconds) to be used by each process.
 188 .It Sy Data <integer>
 189 The maximum size (in bytes) of the data segment for a process; this defines how far a program may extend its break with the
 190 .Xr sbrk 2
 191 system call.
 192 .It Sy FileSize <integer>
 193 The largest size (in bytes) file that may be created.
 194 .It Sy MemoryLock <integer>
 195 The maximum size (in bytes) which a process may lock into memory using the
 196 .Xr mlock 2
 197 function.
 198 .It Sy NumberOfFiles <integer>
 199 The maximum number of open files for this process.
 200 .It Sy NumberOfProcesses <integer>
 201 The maximum number of simultaneous processes for this user id.
 202 .It Sy ResidentSetSize <integer>
 203 The maximum size (in bytes) to which a process's resident set size may grow.
 204 This imposes a limit on the amount of physical memory to be given to a process;
 205 if memory is tight, the system will prefer to take memory from processes that
 206 are exceeding their declared resident set size.
 207 .It Sy Stack <integer>
 208 The maximum size (in bytes) of the stack segment for a process; this defines
 209 how far a program's stack segment may be extended.  Stack extension is
 210 performed automatically by the system.
 211 .El
 212 .It Sy Nice <integer>
 213 This optional key specifies what
 214 .Xr nice 3
 215 value should be applied to the daemon.
 216 .It Sy LowPriorityIO <boolean>
 217 This optional key specifies whether the kernel should consider this daemon to be low priority when doing file system I/O.
 218 .It Sy Sockets <dictionary of dictionaries... OR dictionary of array of dictionaries...>
 219 This optional key is used to specify launch on demand sockets that can be used to let
 220 .Nm launchd
 221 know when to run the job. The job can check-in and get a copy of the file descriptors using APIs outlined in
 222 .Xr launch 3 .
 223 The keys of the top level Sockets dictionary can be anything. They are meant for the application developer to use to
 224 differentiate different which descriptors correspond to which application level protocols (e.g. http vs. ftp vs. DNS...).
 225 At check in time, the value of each Sockets dictionary key will be an array of descriptors. Daemon/Agent writers should
 226 consider all descriptors of a given key to be to be effectively equivalent, even though each file descriptor likely represents
 227 a different networking protocol which conforms to the criteria specified in the job configuration file.
 228 .Pp
 229 The paramters below are used as inputs to call
 230 .Xr getaddrinfo 3 .
 231 .Bl -ohang -offset indent
 232 .It Sy SockType <string>
 233 This optional key tells
 234 .Nm launchctl
 235 what type of socket to create. The default is "stream" and other valid values for this key
 236 are "dgram" and "seqpacket" respectively.
 237 .It Sy SockPassive <boolean>
 238 This optional key specifies whether
 239 .Xr listen 2
 240 or
 241 .Xr connect 2
 242 should be called on the created file descriptor. The default is true ("to listen").
 243 .It Sy SockNodeName <string>
 244 This optional key specifies the node to
 245 .Xr connect 2
 246 or
 247 .Xr bind 2
 248 to.
 249 .It Sy SockServiceName <string>
 250 This optional key specifies the service on the node to
 251 .Xr connect 2
 252 or
 253 .Xr bind 2
 254 to.
 255 .It Sy SockFamily <string>
 256 This optional key can be used to specifically request that "IPv4" or "IPv6" socket(s) be created.
 257 .It Sy SockProtocol <string>
 258 This optional key specifies the protocol to be passed to
 259 .Xr socket 2 .
 260 The only value understood by this key at the moment is "TCP".
 261 .It Sy SockPathName <string>
 262 This optional key implies SockFamily is set to "Unix". It specifies the path to
 263 .Xr connect 2
 264 or
 265 .Xr bind 2
 266 to.
 267 .It Sy Bonjour <boolean or string or array of strings>
 268 This optional key can be used to request that the service be registered with the
 269 .Xr mDNSResponder 8 .
 270 If the value is boolean, the service name is inferred from the SockServiceName.
 271 .It Sy MulticastGroup <string>
 272 This optional key can be used to request that the datagram socket join a multicast group.
 273 If the value is a hostname, then
 274 .Xr getaddrinfo 3
 275 will be used to join the correct multicast address for a given socket family.
 276 If an explicit IPv4 or IPv6 address is given, it is required that the SockFamily family also be set, otherwise the results are undefined.
 277 .El
 278 .El
 279 .Pp
 280 .Sh EXAMPLE XML PROPERTY LISTS
 281 .Pp
 282 The following XML Property List simply keeps "exampled" running continuously:
 283 .Pp
 284 .Dl <?xml version="1.0" encoding="UTF-8"?>
 285 .Dl <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 286 .Dl <plist version="1.0">
 287 .Dl <dict>
 288 .Dl     <key>Label</key>
 289 .Dl     <string>com.example.exampled</string>
 290 .Dl     <key>ProgramArguments</key>
 291 .Dl     <array>
 292 .Dl             <string>exampled</string>
 293 .Dl     </array>
 294 .Dl     <key>OnDemand</key>
 295 .Dl     <false/>
 296 .Dl </dict>
 297 .Dl </plist>
 298 .Pp
 299 .Sh FILES
 300 .Bl -tag -width "/System/Library/LaunchDaemons" -compact
 301 .It Pa ~/Library/LaunchAgents
 302 Per-user agents provided by the user.
 303 .It Pa /Library/LaunchAgents
 304 Per-user agents provided by the administrator.
 305 .It Pa /Library/LaunchDaemons
 306 System wide daemons provided by the administrator.
 307 .It Pa /System/Library/LaunchAgents
 308 Mac OS X Per-user agents.
 309 .It Pa /System/Library/LaunchDaemons
 310 Mac OS X System wide daemons.
 311 .El
 312 .Sh SEE ALSO
 313 .Xr launchctl 1 ,
 314 .Xr launch 3 ,
 315 .Xr launchd 8