In 10.9 and older, if you wanted to\u00a0load launchagent the command would look like:<\/p>\n
launchctl load \/Library\/LaunchAgents\/com.company.launchagent.plist<\/span>\r\n<\/pre>\nAnd to unload it:<\/p>\n
launchctl unload \/Library\/LaunchAgents\/com.company.launchagent.plist<\/span><\/pre>\nAn\u00a0assumption is made about how the launchagent is being loaded. For starters, it assumes the user loading\u00a0the agent\u00a0is\u00a0the\u00a0user\u00a0in the shell environment.\u00a0It might also make assumptions about whether the user is logged in a GUI.<\/p>\n
To better illustrate this, get on a computer which has 2+ users on it. Log into one account normally via the GUI. Open up Terminal, and switch the account (su -l username<\/span><\/span>). If you have a computer which has multiple users and you switch the user in Terminal for one that is NOT logged in, you will get an error when running the above commands.<\/p>\nSo\u00a0what if you want to load the agent under a different user account? Previously you could rely on the following sub-commands:<\/p>\n
bsexec PID command [args]
\nThis executes the given command in as similar an execution context as possible to the target PID. Adopted attributes include the Mach bootstrap namespace, exception server and security audit session. It does not modify the process\u2019 credentials (UID, GID, etc.) or adopt any environment variables from the target process. It affects only the Mach bootstrap context and directly-related attributes.<\/p>\n
asuser UID command [args]
\nThis executes the given command in as similar an execution context as possible to that of the target user\u2019s bootstrap. Adopted attributes include the Mach bootstrap namespace, exception server and security audit session. It does not modify the process\u2019 credentials (UID, GID, etc.) or adopt any user-specific environment variables. It affects only the Mach bootstrap context and directly- related attributes.<\/p><\/blockquote>\n
But these sub-commands have been deprecated so they shouldn\u2019t be relied on.<\/p>\n
As you can see, it can get a little involved because you would need to gather certain information about the user or process. Rich Trouton\u00a0documents this in an excellent blog post<\/a>.\u00a0Unfortunately, from what\u00a0I can tell, there is no replacement for\u00a0asuser<\/span><\/span>\u00a0or\u00a0bsexec<\/span><\/span>.<\/p>\nIn 10.10 or\u00a0greater, launchctl is much more explicit. In fact, Apple explains it as follows (can be found by typing\u00a0launchctl<\/span><\/span>\u00a0in Terminal in 10.11):<\/p>\nWhen using a legacy subcommand which manipulates a domain, the target domain is\u00a0inferred from the current execution context. When run as root (whether it is\u00a0via a root shell or sudo(1)), the target domain is assumed to be the\u00a0system-wide domain. When run from a normal user\u2019s shell, the target is assumed\u00a0to be the per-user domain for that current user.<\/p><\/blockquote>\n
For 10.10 and 10.11, if you want to\u00a0load a\u00a0launchagent, the command would look like:<\/p>\n
launchctl bootstrap gui\/<user's UID> \/Library\/LaunchAgents\/com.company.launchagent.plist<\/span><\/pre>\nAt least for 10.11, to unload it:<\/p>\n
launchctl bootout gui\/<user's UID> \/Library\/LaunchAgents\/com.company.launchagent.plist<\/span><\/pre>\nUnfortunately, for 10.10 the sub-command\u00a0unbootstrap<\/span><\/span>\u00a0that is documented in the manual to unload the agent\u00a0does not work. You will get the output\u00a0Command is not yet implemented<\/span><\/span>.\u00a0Since it\u2019s an older operating system, you may want to rely on the deprecated command at least for that OS as they\u2019ve clearly changed the command name in 10.11. And don\u2019t worry, there are still other commands in 10.11 which also do not work as of yet and give you the same output.<\/p>\nPay attention to the spacing after\u00a0gui\/<user\u2019s UID><\/span><\/span>. To gather the user\u2019s UID, you can run the command:\u00a0id -u <username><\/span><\/span>\u00a0where <username> would be the user account name you want to target.<\/p>\nThe biggest change to point out is that you need to target a domain. The 3 most\u00a0applicable will be:<\/p>\n
system\/[service-name]
\nTargets the system-wide domain or service within. Root privileges are required\u00a0to make modifications.<\/p>\n
user\/<uid>\/[service-name]
\nTargets the user domain or service within. A process running as the target user\u00a0may make modifications. Root may modify any user\u2019s domain. User domains do not\u00a0exist on iOS.<\/p>\n
gui\/<uid>\/[service-name]
\nTargets the GUI domain or service within. Each GUI domain is associated with a\u00a0user domain, and a process running as the owner of that user domain may make\u00a0modifications. Root may modify any GUI domain. GUI domains do not exist on iOS.<\/p><\/blockquote>\n
Note<\/span>: This information is available by typing\u00a0man launchctl<\/span><\/span>\u00a0in Terminal. Other domains do exist.<\/p>\nSome benefits to this change become apparent if you accidentally run something\u00a0under root or with\u00a0sudo. For example, this deprecated command would load the daemon as root.<\/p>\n
sudo launchctl load \/Library\/LaunchDaemon\/com.company.launchdaemon.plist<\/span><\/pre>\nBut the following deprecated command would also load the agent as root because its implicit due to sudo:<\/p>\n
sudo launchctl load \/Library\/LaunchAgent\/com.company.launchdaemon.plist<\/span><\/pre>\nPerhaps that\u2019s not what you meant to do. With the new syntax you can use sudo all you want (and in cases where you want to access another user environment other than the one you\u2019re in its required).<\/p>\n
Another thing to note is that you can unload everything in the user domain by not specifying a path:<\/p>\n
launchctl bootout gui\/<user's UID><\/pre>\nThis leads to weird results so be careful using this.<\/p>\n
Listing running daemons\/agents<\/span><\/h1>\nUnder 10.9 or older, you would be able to list running\u00a0agents with the simple command:<\/p>\n
launchctl list<\/pre>\nAnd if you wanted to get all the launch daemons\/launch agents running, you would simply do:<\/p>\n
sudo launchctl list<\/pre>\nThis would give you a\u00a0Process ID (PID) of the daemon\/agent\u00a0along with the\u00a0exit code and the\u00a0job name. If you writing scripts, it can be rather handy to\u00a0grep<\/span><\/span>\u00a0against some of the results to compare against in conditional\u00a0statements.<\/p>\nWith 10.10 and newer, the\u00a0list<\/span><\/span>\u00a0sub-command is deprecated. The closest I can find is\u00a0print<\/span><\/span>which gives you a great deal more of detail. I\u2019ll give you a few\u00a0examples below.<\/p>\nlaunchctl print gui\/<user's UID><\/pre>\nwill print all the running services under that particular user domain.<\/p>\n
launchctl print\u00a0system<\/pre>\nwill print all the running services under root<\/p>\n
launchctl print gui\/<user's UID>\/com.comapny.launchagent.label<\/span><\/pre>\nwill print detailed information about the specific launch agent. And if it\u2019s not running or you\u2019ve mistyped, you will get some output with a non-zero exit code:\u00a0Could not find service \u201ccom.comapny.launchagent.label<\/span>\u201d in domain for login<\/span><\/span><\/p>\nUnfortunately, Apple states:<\/p>\n
IMPORTANT: This output is NOT API in any sense at all. Do NOT rely on the structure or information emitted for ANY reason. It may change from release to release without warning.<\/p><\/blockquote>\n
So be sure to revisit every new OS to see if things change here.<\/p>\n
Other sub-commands<\/h1>\nenable\/disable<\/h2>\n
The sub-commands\u00a0enable<\/span><\/span>\u00a0and\u00a0disable<\/span><\/span>\u00a0will enable\/disable a service.<\/p>\nThe syntax looks as follows:<\/p>\n
launchctl disable gui\/<user's UID>\/com.comapny.launchagent.label<\/span><\/pre>\nFrom what I gather, this may be more useful for a developer working with apps, but there is some interesting behavior to note here.<\/p>\n
Let\u2019s say you\u2019ve loaded a launch agent\u00a0and then\u00a0disable it. You won\u2019t be able to load the launch agent thereafter until it has been re-enabled. For example, the following commands in succession:<\/p>\n
launchctl bootstrap gui\/<user's UID> \/Library\/LaunchAgents\/com.company.launchagent.plist<\/span><\/pre>\nlaunchctl disable gui\/<user's UID>\/com.comapny.launchagent.label<\/span><\/pre>\nlaunchctl bootstrap gui\/<user's UID> \/Library\/LaunchAgents\/com.company.launchagent.plist<\/span><\/pre>\nThat should give you an output of:
\/Library\/LaunchAgents\/com.company.launchagent.plist<\/span>: Service is disabled<\/span><\/span><\/p>\nWhat\u2019s interesting here is that the launch agent is actually still loaded. Check it out yourself using the new\u00a0launchctl\u00a0print<\/span><\/span>\u00a0command (launchctl print gui\/<user\u2019s UID>\/com.company.launchagent.label<\/span><\/span><\/span>\u00a0). The state will show as\u00a0Running<\/span><\/span>. If you do disable the agent using\u00a0launchctl bootout<\/span><\/span>\u00a0then you\u00a0cannot\u00a0load it again until you\u2019ve re-enabled the service.\u00a0Like I said, this may not be very useful to an admin, but something to be aware of nonetheless.<\/p>\nuncache<\/h2>\n
The sub-command\u00a0uncache<\/span><\/span>\u00a0is\u00a0not yet implemented.<\/p>\nkickstart<\/h2>\n
The sub-command\u00a0kickstart<\/span><\/span>\u00a0does have one interesting use. It does have a few options you can use with it, but the interesting one to know is how to restart\u00a0a service:<\/p>\nlaunchctl kickstart -k gui\/<user's UID>\/com.comapny.launchagent.label<\/span><\/pre>\nThe\u00a0-k<\/span><\/span>\u00a0indicates you want to terminate the current service before it is restarted. If your launch agent uses\u00a0\u00a0KeepAlive<\/span><\/span>\u00a0then it will restart the agent and should be pretty apparent right away.\u00a0However, I want to caution\u00a0that this may not be the proper way to restart a launch agent and you should properly stick to unloading and loading using the commands shown earlier. My reasoning is that I\u2019m not a developer and launchd has been expanded to work with XPC services so its unclear to me if this is really meant for XPC services.<\/p>\nkill<\/h2>\n
The sub-command\u00a0kill<\/span><\/span>\u00a0can be used as follows:<\/p>\nlaunchctl kill <signal name or number> gui\/<user's UID>\/com.comapny.launchagent.label<\/span><\/pre>\nThis one is a little interesting because it utilizes signals that you can send to the launch agent. Might be handy for troubleshooting. Signal names and numbers can be found in\u00a0this Apple document<\/a>.<\/p>\nFor example, to terminate a process\u00a0simple do:<\/p>\n
launchctl kill 9 gui\/<user's UID>\/com.comapny.launchagent.label<\/span><\/pre>\nor<\/p>\n
launchctl kill SIGKILL gui\/<user's UID>\/com.comapny.launchagent.label<\/span><\/pre>\nconfig<\/h2>\n