AATP-Only Exercise 26.3
Troubleshoot a Misbehaving Startup Item
Prerequisite
You must have created the Local Admin (Exercise 2.1, “Configure a New macOS System for Exercises,” or Exercise 2.2, “Configure an Existing macOS System for Exercises”) and Chris Johnson (Exercise 5.1, “Create a Standard User Account”) accounts.
When troubleshooting macOS startup issues, you may come across an issue with a damaged or incompatible startup item. When you work with third-party utilities, especially in network environments where your end users might download and install startup items, it is especially helpful to be able to identify and resolve startup item issues. In this exercise, you will install a problematic startup item to see how you can fix the issues it causes.
Install a Problematic Startup Item
In this exercise, you will install some faulty software that causes issues for your users. You will then isolate the issue and fix it.
1 If necessary, log in as Chris Johnson.
2 Open the StudentMaterials/Lesson26 folder.
3 Open the Pretendco.pkg installer.
4 In the Installer introduction window, click Continue.
5 In Standard Install, click Install.
6 Authenticate as Local Admin.
7 When you are informed that the install requires a restart, click Continue Installation.
8 When the installation is complete, click Restart.
Observe the Symptoms of a Problematic Startup Item
You will use your knowledge of the startup process from the previous exercise and identify the correct issue resolution. You will log in to your computer, resolve the issue, and then restart to ensure that the issue has gone away.
1 Watch the computer start up, and attempt to log in again as Chris Johnson. Follow the startup process to identify when issues begin.
You should notice a problem somewhere along this process, although the precise problem (and when it appears) may vary.
2 Restart the computer to watch startup again. If necessary, you can hold down the computer’s power button for ten seconds to turn off the computer.
Ask yourself which startup task was executing, if any, when you saw the first indication of trouble. Is it user initiated? Is some background process causing it? Keep in mind that visible symptoms may not appear until some time after the issue originated.
In this case, you know what you did to the computer (installed a package), but understanding the startup process and what is happening at any given time is useful in resolving issues.
3 Restart the computer in verbose mode (hold down Command-V until you see text or the FileVault authentication screen appear).
Watch the startup process, and try to spot anything that might indicate what the issue is. If you have another computer available (that does not have this problem), it might be useful to compare what the two computers print during startup.
In this case, you aren’t likely to see anything informative.
4 Restart the computer in safe mode (hold down the Shift key until you see a progress indicator or the FileVault authentication screen).
Note that when the computer is running in safe mode, the login screen indicates “Safe Boot” at the login screen near the top right of the screen.
5 Log in as Chris Johnson.
You may notice that the computer is not operating quite normally. For example, things may run slower than normal, there may be glitches in the display, animations may be missing or jerkier than usual, sound may not work, and so on. Also, if you are using FileVault, you will need to authenticate twice to log in. These problems are normal side effects of certain system components being disabled in safe mode.
Is the original issue still there after restarting in safe mode?
In this case, the computer does not exhibit the same issue. This tells you that the issue has to be with one of the items the system does not load in safe mode.
Track Down the Problematic Startup Item
1 Open the installer package StudentMaterials/Lesson26/Pretendco.pkg again. Do not repeat the installation process.
2 In the Installer application, choose File menu > Show Files.
3 Click the two disclosure triangles to show which files are installed by the two components of the package.
You see two files that were installed, one of which is inside two folders (local and libexec). One looks like a property list file and is likely some sort of preference, setting, or configuration file. Unfortunately, Installer does not tell you where it installed the files and folders.
4 Quit Installer.
5 Click the Spotlight menu, and enter funkytown (a distinctive part of the installed files’ names).
You are in safe mode, so Spotlight cannot search files and folders. The services that provide Spotlight search are among those not started in safe mode. You may still see some results in other search categories.
Installer doesn’t tell you where the files were placed, and Spotlight isn’t available to help you find them, so recall the list of items turned off by safe mode. The issue must be one of these:
Unnecessary kernel extensions
Nonsystem launch daemons
Nonsystem launch agents
User fonts
Automatic login
Login items
Quartz Extreme
The first indications of the issue (lack of icons at the login screen, inability to log in) appear before any user has logged in, so you can eliminate items that activate only after a user has logged in: launch agents, user fonts, and login items. Also, automatic login wasn’t enabled to begin with, so that’s not the issue. Quartz Extreme is graphics acceleration technology, which doesn’t seem relevant to the symptoms.
That leaves unnecessary kernel extensions and nonsystem launch daemons as possible suspects.
6 Open Macintosh HD, and navigate to the local Library folder (/Library). Normally, third-party and optional system components are installed here.
7 Open /Library/Extensions, and check for installed kernel extensions.
There may be some extensions here, but their names don’t match the names of the files listed by Installer. Although it’s possible that one of these items might be the problem, it seems unlikely for the moment, so you should set this possibility aside and look elsewhere.
It’s also possible that an Apple-supplied but unnecessary extension might be at fault, but this is unlikely. Standard troubleshooting theory says you should investigate the most likely possibilities first, so move on to the other suspects.
8 Open /Library/LaunchDaemons, and look for suspicious items.
You see an item named com.pretendco.funkytown.plist. This matches the name of one of the files in the installer package, so that’s likely to be what’s causing the issue.
9 Use Quick Look to view com.pretendco.funkytown.plist.
Its ProgramArguments array lists /usr/local/libexec/funkytown, which matches another file in the installer package.
10 Disable the com.pretendco.funkytown.plist launch daemon by dragging it to the Trash. Authenticate as Local Admin when you are prompted to do so.
Note that, in general, throwing files out merely because they are possible sources of trouble is not a good practice—the file might not be the source of the issue, in which case you would want to restore it. However, this file is in a folder you do not have write permissions to, and the only way the Finder allows you to override this and move (rather than copy) the file is to drag it to the Trash. Do not empty your Trash until you are sure you want to get rid of the file.
11 Restart the computer without invoking safe mode, and look for a repeat of the previous behavior.
The issue appears to be gone.
Remove the Problematic Startup Item
Now that you are sure funkytown was the issue, you can delete it. But to properly clean your system, you should also delete the other installed file. Fortunately, the property list revealed its location, /usr/local/libexec/funkytown. Since this is in a hidden folder, you need to tell the Finder how to get to it.
1 If necessary, log in as Chris Johnson.
2 In the Finder, choose Go menu > Go to Folder (Command-Shift-G), enter /usr/local/libexec, and click Go.
3 Drag the funkytown file from libexec to the Trash, and authenticate as Local Admin when prompted.
You have now tracked down and removed all parts of the problematic software.