Revision: 23902 http://trac.macosforge.org/projects/launchd/changeset/23902 Author: dsorresso@apple.com Date: 2009-04-20 15:46:16 -0700 (Mon, 20 Apr 2009) Log Message: ----------- <rdar://problem/6802599> ?\195?\162?\194?\152?\194?\130: launchd needs documentation updates Modified Paths: -------------- trunk/launchd/src/launchctl.1 trunk/launchd/src/launchd.8 trunk/launchd/src/launchd.plist.5 Modified: trunk/launchd/src/launchctl.1 =================================================================== --- trunk/launchd/src/launchctl.1 2009-04-17 22:04:16 UTC (rev 23901) +++ trunk/launchd/src/launchctl.1 2009-04-20 22:46:16 UTC (rev 23902) @@ -32,9 +32,18 @@ Load the specified configuration files or directories of configuration files. Jobs that are not on-demand will be started as soon as possible. All specified jobs will be loaded before any of them are allowed to start. +Note that per-user configuration files (LaunchAgents) must be owned by the user +loading them. All system-wide daemons (LaunchDaemons) must be owned by root. Configuration files +must not be group- or world-writable. These restrictions are in place for security reasons, +as allowing writability to a launchd configuration file allows one to specify which executable +will be launched. + +Note that allowing non-root write access to the /System/Library/LaunchDaemons directory WILL render your system unbootable. .Bl -tag -width -indent .It Fl w -Remove the disabled key and write the configuration files back out to disk. +Overrides the Disabled key and sets it to false. In previous versions, this option +would modify the configuration file. Now the state of the Disabled key is stored +elsewhere on-disk. .It Fl F Force the loading of the plist. Ignore the Disabled key. .It Fl S Ar sessiontype @@ -61,7 +70,9 @@ This will also stop the job if it is running. .Bl -tag -width -indent .It Fl w -Add the disabled key and write the configuration files back out to disk. +Overrides the Disabled key and sets it to true. In previous versions, this option +would modify the configuration file. Now the state of the Disabled key is stored +elsewhere on-disk. .It Fl S Ar sessiontype Some jobs only make sense in certain contexts. This flag instructs .Nm launchctl @@ -105,9 +116,36 @@ restart the job if launchd finds any criteria that is satisfied. Non-demand based jobs will always be restarted. Use of this subcommand is discouraged. Jobs should ideally idle timeout by themselves. -.It Ar list -List all of the jobs loaded into +.It Xo Ar list +.Op Ar -x +.Op Ar label +.Xc +With no arguments, list all of the jobs loaded into +.Nm launchd +in three columns. The first column displays the PID of the job if it is running. +The second column displays the last exit status of the job. If the number in this +column is negative, it represents the negative of the signal which killed the job. +Thus, "-15" would indicate that the job was terminated with SIGTERM. The third column +is the job's label. + +Note that you may see some jobs in the list whose labels are in the style "0xdeadbeef.anonymous.program". +These are jobs which are not managed by +.Nm launchd , +but, at one point, made a request to it. +.Nm launchd +claims no ownership and makes no guarantees regarding these jobs. They are stored purely for +bookkeeping purposes. + +Similarly, you may see labels of the style "0xdeadbeef.mach_init.program". These are legacy jobs that run +under mach_init emulation. This mechanism will be removed in future versions, and all remaining mach_init +jobs should be converted over to .Nm launchd . + +If +.Op Ar label +is specified, prints information about the requested job. If +.Op Ar -x +is specified, the information for the specified job is output as an XML property list. .It Ar setenv Ar key Ar value Set an environmental variable inside of .Nm launchd . @@ -155,14 +193,35 @@ .Xr umask 2 of .Nm launchd . -.It Ar bslist Op Ar PID +.It Xo Ar bslist +.Op Ar PID | .. +.Xc This prints out Mach bootstrap services and their respective states. While the namespace appears flat, it is in fact hierarchical, thus allowing for certain services to be only available to a subset of processes. The three states a -service can be in are active ("A"), inactive ("I") and on-demand ("D"). +service can be in are active ("A"), inactive ("I") and on-demand ("D"). If +.Op Ar PID +is specified, print the Mach bootstrap services available to that PID. If +.Op Ar .. +is specified, print the Mach bootstrap services available in the parent of the +current bootstrap. Note that in Mac OS X v10.6, the per-user Mach bootstrap namespace +is flat, so you will only see a different set of services in a per-user bootstrap +if you are in an explicitly-created bootstrap subset. .It Ar bsexec Ar PID command Op Ar args This executes the given command in the same Mach bootstrap namespace hierachy as the given PID. +.It Ar bstree +This prints a hierarchical view of the entire Mach bootstrap tree. Requires root +privileges. +.It Ar managerpid +This prints the PID of the launchd which manages the current bootstrap. +.It Ar manageruid +This prints the UID of the launchd which manages the current bootstrap. +.It Ar managername +This prints the name of the launchd job manager which manages the current bootstrap. +See LimitLoadToSessionType in +.Xr launchd.plist 5 +for more details. .It Ar help Print out a quick usage statement. .El Modified: trunk/launchd/src/launchd.8 =================================================================== --- trunk/launchd/src/launchd.8 2009-04-17 22:04:16 UTC (rev 23901) +++ trunk/launchd/src/launchd.8 2009-04-20 22:46:16 UTC (rev 23902) @@ -55,14 +55,19 @@ This variable is exported when invoking a command via the launchd command line. It informs launchctl how to find the correct launchd to talk to. .El .Sh NOTES -In Darwin it is preferable to have your daemon launch via launchd instead of modifying -.Nm rc -or creating a -.Nm SystemStarter -Startup Item. -.Pp -At some point in the future, we hope to completely phase out the use of -.Nm rc . +In Darwin, the canonical way to launch a daemon is through +.Nm launchd +as opposed to more traditional mechanisms or mechanisms provided in earlier versions of Mac OS X. These alternate methods should +be considered deprecated and not suitable for new projects. + +Also, in the +.Nm launchd +lexicon, a "daemon" is, by definition, a system-wide service of which there is one instance for all clients. An "agent" is a service that runs on +a per-user basis. If you wish your service to run as a certain user, in that user's environment, making it a +.Nm launchd +agent is the ONLY supported means of accomplishing this on Mac OS X. In other words, it is not sufficient to perform a +.Xr setuid 2 +to become a user in the truest sense on Mac OS X. .Sh FILES .Bl -tag -width "/System/Library/LaunchDaemons" -compact .It Pa ~/Library/LaunchAgents @@ -70,11 +75,11 @@ .It Pa /Library/LaunchAgents Per-user agents provided by the administrator. .It Pa /Library/LaunchDaemons -System wide daemons provided by the administrator. +System-wide daemons provided by the administrator. .It Pa /System/Library/LaunchAgents -Mac OS X Per-user agents. +Per-user agents provided by Mac OS X. .It Pa /System/Library/LaunchDaemons -Mac OS X System wide daemons. +System-wide daemons provided by Mac OS X. .El .Sh SEE ALSO .Xr launchctl 1 , Modified: trunk/launchd/src/launchd.plist.5 =================================================================== --- trunk/launchd/src/launchd.plist.5 2009-04-17 22:04:16 UTC (rev 23901) +++ trunk/launchd/src/launchd.plist.5 2009-04-20 22:46:16 UTC (rev 23902) @@ -79,13 +79,45 @@ Property lists are Apple's standard configuration file format. Please see .Xr plist 5 for more information. Please note: property 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". .Pp .Bl -ohang .It Sy Label <string> This required key uniquely identifies the job to .Nm launchd . .It Sy Disabled <boolean> -This optional key is used to disable your job. The default is false. +This optional key is used as a hint to +.Xr launchctl 1 +that it should not submit this job to +.Nm 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 +.Nm launchd +for the presence of the job using the +.Xr launchctl 1 +.Ar 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 +.Op Ar -w +option of the +.Xr launchctl 1 +.Ar load +and +.Ar unload +subcommands. These subcommands no longer modify the configuration file, so the value displayed in the configuration file is not necessarily the value that +.Xr launchctl 1 +will apply. See +.Xr 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 conditions under which your job needs to run. The cost +to have a job loaded in +.Nm launchd +is negligible, so there is no harm in loading a job which only runs once or very rarely. .It Sy UserName <string> This optional key specifies the user to run the job as. This key is only applicable when launchd is running as root. .It Sy GroupName <string> @@ -186,7 +218,7 @@ .Xr chdir 2 to before running the job. .It Sy EnvironmentVariables <dictionary of strings> -This optional key is used to specify additional environmental variables to be setup before running the job. +This optional key is used to specify additional environmental variables to be set before running the job. .It Sy Umask <integer> This optional key specifies what value should be passed to .Xr umask 2 @@ -206,9 +238,9 @@ 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. .It Sy InitGroups <boolean> -This optional key specifies whether the job should have +This optional key specifies whether .Xr initgroups 3 -be called before running the job. +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. .It Sy WatchPaths <array of strings> This optional key causes the job to be started if any one of the listed paths are modified. @@ -356,8 +388,8 @@ know when to run the job. The job must check-in to get a copy of the file descriptors using APIs outlined in .Xr launch 3 . The keys of the top level Sockets dictionary can be anything. They are meant for the application developer to use to -differentiate different 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 +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 protocol which conforms to the criteria specified in the job configuration file. .Pp