launchd/src/launchctl.1

   1 .Dd 1 May, 2009
   2 .Dt launchctl 1
   3 .Os Darwin
   4 .Sh NAME
   5 .Nm launchctl
   6 .Nd Interfaces with launchd
   7 .Sh SYNOPSIS
   8 .Nm
   9 .Op Ar subcommand Op Ar arguments ...
  10 .Sh DESCRIPTION
  11 .Nm
  12 interfaces with
  13 .Nm launchd
  14 to load, unload daemons/agents and generally control
  15 .Nm launchd .
  16 .Nm
  17 supports taking subcommands on the command line, interactively or even redirected from standard input.
  18 These commands can be stored in
  19 .Nm $HOME/.launchd.conf
  20 or
  21 .Nm /etc/launchd.conf
  22 to be read at the time
  23 .Nm launchd
  24 starts.
  25 .Sh SUBCOMMANDS
  26 .Bl -tag -width -indent
  27 .It Xo Ar load Op Fl wF
  28 .Op Fl S Ar sessiontype
  29 .Op Fl D Ar domain
  30 .Ar paths ...
  31 .Xc
  32 Load the specified configuration files or directories of configuration files.
  33 Jobs that are not on-demand will be started as soon as possible.
  34 All specified jobs will be loaded before any of them are allowed to start.
  35 Note that per-user configuration files (LaunchAgents) must be owned by the user
  36 loading them. All system-wide daemons (LaunchDaemons) must be owned by root. Configuration files
  37 must not be group- or world-writable. These restrictions are in place for security reasons,
  38 as allowing writability to a launchd configuration file allows one to specify which executable
  39 will be launched.
  40 .Pp
  41 Note that allowing non-root write access to the /System/Library/LaunchDaemons directory WILL render your system unbootable.
  42 .Bl -tag -width -indent
  43 .It Fl w
  44 Overrides the Disabled key and sets it to false. In previous versions, this option
  45 would modify the configuration file. Now the state of the Disabled key is stored
  46 elsewhere on-disk.
  47 .It Fl F
  48 Force the loading of the plist. Ignore the Disabled key.
  49 .It Fl S Ar sessiontype
  50 Some jobs only make sense in certain contexts. This flag instructs
  51 .Nm launchctl
  52 to look for jobs in a different location when using the -D flag, and allows
  53 .Nm launchctl
  54 to restrict which jobs are loaded into which session types. Currently known
  55 session types include: Aqua, LoginWindow, Background, StandardIO and System.
  56 .It Fl D Ar domain
  57 Look for
  58 .Xr plist 5 files ending in *.plist in the domain given. Valid domains include
  59 "system," "local," "network" and "all." When providing a session type, an additional
  60 domain is available for use called "user." For example, without a session type given,
  61 "-D system" would load from property list files from /System/Library/LaunchDaemons.
  62 With a session type passed, it would load from /System/Library/LaunchAgents.
  63 .El
  64 .It Xo Ar unload Op Fl w
  65 .Op Fl S Ar sessiontype
  66 .Op Fl D Ar domain
  67 .Ar paths ...
  68 .Xc
  69 Unload the specified configuration files or directories of configuration files.
  70 This will also stop the job if it is running.
  71 .Bl -tag -width -indent
  72 .It Fl w
  73 Overrides the Disabled key and sets it to true. In previous versions, this option
  74 would modify the configuration file. Now the state of the Disabled key is stored
  75 elsewhere on-disk.
  76 .It Fl S Ar sessiontype
  77 Some jobs only make sense in certain contexts. This flag instructs
  78 .Nm launchctl
  79 to look for jobs in a different location when using the -D flag, and allows
  80 .Nm launchctl
  81 to restrict which jobs are loaded into which session types. Currently known
  82 session types include: Aqua, LoginWindow, Background, StandardIO and System.
  83 .It Fl D Ar domain
  84 Look for
  85 .Xr plist 5 files ending in *.plist in the domain given. Valid domains include
  86 "system," "local," "network" and "all." When providing a session type, an additional
  87 domain is available for use called "user." For example, without a session type given,
  88 "-D system" would load from property list files from /System/Library/LaunchDaemons.
  89 With a session type passed, it would load from /System/Library/LaunchAgents.
  90 .El
  91 .It Xo Ar submit Fl l Ar label
  92 .Op Fl p Ar executable
  93 .Op Fl o Ar path
  94 .Op Fl e Ar path
  95 .Ar -- command
  96 .Op Ar args
  97 .Xc
  98 A simple way of submitting a program to run without a configuration file. This mechanism also tells launchd to keep the program alive in the event of failure.
  99 .Bl -tag -width -indent
 100 .It Fl l Ar label
 101 What unique label to assign this job to launchd.
 102 .It Fl p Ar program
 103 What program to really execute, regardless of what follows the -- in the submit sub-command.
 104 .It Fl o Ar path
 105 Where to send the stdout of the program.
 106 .It Fl e Ar path
 107 Where to send the stderr of the program.
 108 .El
 109 .It Ar remove Ar job_label
 110 Remove the job from launchd by label.
 111 .It Ar start Ar job_label
 112 Start the specified job by label. The expected use of this subcommand is for
 113 debugging and testing so that one can manually kick-start an on-demand server.
 114 .It Ar stop Ar job_label
 115 Stop the specified job by label. If a job is on-demand, launchd may immediately
 116 restart the job if launchd finds any criteria that is satisfied.
 117 Non-demand based jobs will always be restarted. Use of this subcommand is discouraged.
 118 Jobs should ideally idle timeout by themselves.
 119 .It Xo Ar list
 120 .Op Ar -x
 121 .Op Ar label
 122 .Xc
 123 With no arguments, list all of the jobs loaded into
 124 .Nm launchd
 125 in three columns. The first column displays the PID of the job if it is running.
 126 The second column displays the last exit status of the job. If the number in this
 127 column is negative, it represents the negative of the signal which killed the job.
 128 Thus, "-15" would indicate that the job was terminated with SIGTERM. The third column
 129 is the job's label.
 130 .Pp
 131 Note that you may see some jobs in the list whose labels are in the style "0xdeadbeef.anonymous.program".
 132 These are jobs which are not managed by
 133 .Nm launchd ,
 134 but, at one point, made a request to it.
 135 .Nm launchd
 136 claims no ownership and makes no guarantees regarding these jobs. They are stored purely for
 137 bookkeeping purposes.
 138 .Pp
 139 Similarly, you may see labels of the style "0xdeadbeef.mach_init.program". These are legacy jobs that run
 140 under mach_init emulation. This mechanism will be removed in future versions, and all remaining mach_init
 141 jobs should be converted over to
 142 .Nm launchd .
 143 .Pp
 144 If
 145 .Op Ar label
 146 is specified, prints information about the requested job. If
 147 .Op Ar -x
 148 is specified, the information for the specified job is output as an XML property list.
 149 .It Ar setenv Ar key Ar value
 150 Set an environmental variable inside of
 151 .Nm launchd .
 152 .It Ar unsetenv Ar key
 153 Unset an environmental variable inside of
 154 .Nm launchd .
 155 .It Ar getenv Ar key
 156 Get an environmental variable inside of
 157 .Nm launchd .
 158 .It Ar export
 159 Export all of the environmental variables of
 160 .Nm launchd
 161 for use in a shell eval statement.
 162 .It Ar getrusage self | children
 163 Get the resource utilization statistics for
 164 .Nm launchd
 165 or the children of
 166 .Nm launchd .
 167 .It Xo Ar log
 168 .Op Ar level loglevel
 169 .Op Ar only | mask loglevels...
 170 .Xc
 171 Get and set the
 172 .Xr syslog 3
 173 log level mask. The available log levels are: debug, info, notice, warning, error, critical, alert and emergency.
 174 .It Xo Ar limit
 175 .Op Ar cpu | filesize | data | stack | core | rss | memlock | maxproc | maxfiles
 176 .Op Ar both Op Ar soft | hard
 177 .Xc
 178 With no arguments, this command prints all the resource limits of
 179 .Nm launchd
 180 as found via
 181 .Xr getrlimit 2 .
 182 When a given resource is specified, it prints the limits for that resource.
 183 With a third argument, it sets both the hard and soft limits to that value.
 184 With four arguments, the third and forth argument represent the soft and hard limits respectively.
 185 See
 186 .Xr setrlimit 2 .
 187 .It Ar shutdown
 188 Tell
 189 .Nm launchd
 190 to prepare for shutdown by removing all jobs.
 191 .It Ar umask Op Ar newmask
 192 Get or optionally set the
 193 .Xr umask 2
 194 of
 195 .Nm launchd .
 196 .It Xo Ar bslist
 197 .Op Ar PID | ..
 198 .Op Ar -j
 199 .Xc
 200 This prints out Mach bootstrap services and their respective states. While the
 201 namespace appears flat, it is in fact hierarchical, thus allowing for certain
 202 services to be only available to a subset of processes. The three states a
 203 service can be in are active ("A"), inactive ("I") and on-demand ("D").
 204 .Pp
 205 If
 206 .Op Ar PID
 207 is specified, print the Mach bootstrap services available to that PID. If
 208 .Op Ar ..
 209 is specified, print the Mach bootstrap services available in the parent of the
 210 current bootstrap. Note that in Mac OS X v10.6, the per-user Mach bootstrap namespace
 211 is flat, so you will only see a different set of services in a per-user bootstrap
 212 if you are in an explicitly-created bootstrap subset.
 213 .Pp
 214 If
 215 .Op Ar -j
 216 is specified, each service name will be followed by the name of the job which registered
 217 it.
 218 .It Ar bsexec Ar PID command Op Ar args
 219 This executes the given command in the same Mach bootstrap namespace hierachy
 220 as the given PID.
 221 .It Ar bstree Op Ar -j
 222 This prints a hierarchical view of the entire Mach bootstrap tree. If
 223 .Op Ar -j
 224 is specified, each service name will be followed by the name of the job which registered it.
 225 Requires root
 226 privileges.
 227 .It Ar managerpid
 228 This prints the PID of the launchd which manages the current bootstrap.
 229 .It Ar manageruid
 230 This prints the UID of the launchd which manages the current bootstrap.
 231 .It Ar managername
 232 This prints the name of the launchd job manager which manages the current bootstrap.
 233 See LimitLoadToSessionType in
 234 .Xr launchd.plist 5
 235 for more details.
 236 .It Ar help
 237 Print out a quick usage statement.
 238 .El
 239 .Sh ENVIRONMENTAL VARIABLES
 240 .Bl -tag -width -indent
 241 .It Pa LAUNCHD_SOCKET
 242 This variable informs launchctl how to find the correct launchd to talk to. If it is missing, launchctl will use a built-in default.
 243 .El
 244 .Sh FILES
 245 .Bl -tag -width "/System/Library/LaunchDaemons" -compact
 246 .It Pa ~/Library/LaunchAgents
 247 Per-user agents provided by the user.
 248 .It Pa /Library/LaunchAgents
 249 Per-user agents provided by the administrator.
 250 .It Pa /Library/LaunchDaemons
 251 System wide daemons provided by the administrator.
 252 .It Pa /System/Library/LaunchAgents
 253 Mac OS X Per-user agents.
 254 .It Pa /System/Library/LaunchDaemons
 255 Mac OS X System wide daemons.
 256 .El
 257 .Sh SEE ALSO
 258 .Xr launchd.plist 5 ,
 259 .Xr launchd.conf 5 ,
 260 .Xr launchd 8