System Startup Programming Topics 2006-10-03 Java and all Java-based trademarks are Apple Computer, Inc. trademarks or registered trademarks of Sun © 2003, 2006 Apple Computer, Inc. Microsystems, Inc. in the U.S. and other All rights reserved. countries. PowerPC and and the PowerPC logo are No part of this publication may be trademarks of International Business reproduced, stored in a retrieval system, or Machines Corporation, used under license transmitted, in any form or by any means, therefrom. mechanical, electronic, photocopying, recording, or otherwise, without prior Simultaneously published in the United written permission of Apple Computer, Inc., States and Canada. with the following exceptions: Any person Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR is hereby authorized to store documentation REPRESENTATION, EITHER EXPRESS OR on a single computer for personal use only IMPLIED, WITH RESPECT TO THIS and to print copies of documentation for DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A personal use provided that the PARTICULAR PURPOSE. AS A RESULT, THIS documentation contains Apple’s copyright DOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE notice. ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. The Apple logo is a trademark of Apple IN NO EVENT WILL APPLE BE LIABLE FOR Computer, Inc. DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES Use of the “keyboard” Apple logo RESULTING FROM ANY DEFECT OR (Option-Shift-K) for commercial purposes INACCURACY IN THIS DOCUMENT, even if without the prior written consent of Apple advised of the possibility of such damages. may constitute trademark infringement and THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN unfair competition in violation of federal LIEU OF ALL OTHERS, ORAL OR WRITTEN, and state laws. EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any No licenses, express or implied, are granted modification, extension, or addition to this with respect to any of the technology warranty. described in this document. Apple retains Some states do not allow the exclusion or limitation of implied warranties or liability for all intellectual property rights associated incidental or consequential damages, so the with the technology described in this above limitation or exclusion may not apply to you. This warranty gives you specific legal document. This document is intended to rights, and you may also have other rights which assist application developers to develop vary from state to state. applications only for Apple-labeled or Apple-licensed computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Carbon, Cocoa, iTunes, Mac, Mac OS, Macintosh, Pages, and Xcode are trademarks of Apple Computer, Inc., registered in the United States and other countries. Finder is a trademark of Apple Computer, Inc. Intel and Intel Core are registered trademarks of Intel Corportation or its subsidiaries in the United States and other countries. Contents Introduction to System Startup Programming Topics 7 Organization of This Document 7 The Boot Process 9 BootROM 9 BootX, boot.efi, and System Initialization 10 Authenticating Users 11 Configuring User Sessions 11 Logout Responsibilities 12 Application Responsibilities 13 Terminating Processes 14 Identifying the Scope of Processes 15 The Shutdown Process 15 Daemons 17 Communicating With Daemons 17 Viewing the Currently Running Daemons 18 Running a Process on a Schedule 19 Timed Jobs Using Periodic Jobs 19 Timed Jobs Using cron 20 Timed Jobs Using launchd 20 Timed Jobs Using at 21 Guidelines for Creating and Launching Daemons 23 When Is a Custom Daemon Appropriate? 23 Launching Custom Daemons On Demand 24 Launching Daemons From Startup Items 24 Creating Launch-On-Demand Daemons and Agents 25 The Launch-on-Demand Process 25 Daemon Requirements 26 Required Behaviors 26 Recommended Behaviors 27 Creating a Launchd Property List File 28 3 2006-10-03 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. Deciding When to Shut Down 29 Special Dependencies 29 For More Information 31 Creating a Startup Item 33 Anatomy of a Startup Item 33 Creating the Startup Item Executable 34 Specifying the Startup Item Properties 35 Managing Startup Items 37 Displaying and Localizing a Startup Message 37 Startup Item Permissions 38 Logging Errors and Warnings 41 Log Levels and Log Files 41 Logging Errors Using the syslog API 42 Logging Errors Using the asl API 44 Customizing Login and Logout 45 Login Items 45 Adding Login and Logout Items with Apple Events 45 Adding Login and Logout Items with CFPreferences 45 Adding Login and Logout Items Manually 46 Loginwindow Scripts 47 Installing Scripts Using Defaults 47 Installing Scripts Using Loginwindow Hooks 48 Bootstrap Daemons 49 Launchd User Agents 49 Document Revision History 51 Index 53 4 2006-10-03 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. Figures and Tables Daemons 17 Figure 1 Processes shown in Activity Monitor 19 Creating Launch-On-Demand Daemons and Agents 25 Table 1 Required and recommended property list keys 28 Creating a Startup Item 33 Table 1 StartupParameters.plist key-value pairs 35 Customizing Login and Logout 45 Table 1 loginwindow parameters 48 5 2006-10-03 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. 6 2006-10-03 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. Introduction to System Startup Programming Topics System startup (also known as the boot process) involves a sequence of actions that prepare the computer for use by the user. This sequence includes a number of different tasks, including initializing hardware, starting system daemons, and displaying the login window. After a user logs in, the system completes an additional series of actions that sets up the computing environment for that user. This document provides information that developers of daemons and other low-level system services need to write their code and incorporate it into the startup process. It also provides some useful information for system administrators who must manage the startup process on the computers they manage. You should read this document if you are writing or porting software that needs to be launched at boot time or at user login time. You should also read this document if you are interested in the system logging facilities provided by Apple system log (asl) facility. Organization of This Document This programming topic includes the following articles: ■ “The Boot Process” (page 9) describes the overall sequence that occurs when Mac OS X boots, focusing on the places where developers can customize the boot cycle. ■ “Daemons” (page 17) provides background information on daemons in Mac OS X. ■ “Guidelines for Creating and Launching Daemons” (page 23) provides basic guidelines for developers who want to run daemons on Mac OS X. ■ “Creating Launch-On-Demand Daemons” (page 25) provides guidance on how to create a daemon that runs under launchd. ■ “Creating a Startup Item” (page 33) provides information about how to create startup items to support the launching of daemons on versions of Mac OS X prior to 10.4. ■ “Logging Errors and Warnings” (page 41) provides sample code for logging errors and warnings using syslog(3) and asl(3). ■ “Customizing Login and Logout” (page 45) provides information on how to customize the login process on older versions of Mac OS X. Organization of This Document 7 2006-10-03 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. Introduction to System Startup Programming Topics 8 Organization of This Document 2006-10-03 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. The Boot Process From the moment a user turns on a Mac OS X system to beyond the time the login window appears, Mac OS X executes a boot sequence that readies the system for use. If you provide system services to all users, you might need to execute some code during this process. The following sections explain the basic boot sequence and the places where your code can tie into it. BootROM When the power to a Macintosh computer is turned on, the BootROM firmware is activated. BootROM (which is part of the computer’s hardware) has two primary responsibilities: it initializes system hardware and it selects an operating system to run. BootROM has two components to help it carry out these functions: ■ POST (Power-On Self Test) initializes some hardware interfaces and verifies that sufficient memory is available and in a good state. ■ On PowerPC-based Macintosh computers, Open Firmware initializes the rest of the hardware, builds the initial device tree (a hierarchical representation of devices associated with the computer), and selects the operating system to use. On Intel-based Macintosh computers, EFI does basic hardware initialization and selects which operating system to use. If multiple installations of Mac OS X are available, BootROM chooses the one that was last selected by the Startup Disk System Preference. The user can override this choice by holding down the Option key while the computer boots, which causes Open Firmware or EFI to display a screen for choosing the boot volume. BootROM 9 2006-10-03 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. The Boot Process Note: On some legacy hardware, the same version of BootROM can start either Mac OS 9 or Mac OS X. Most current hardware can start only Mac OS X. BootX, boot.efi, and System Initialization Once BootROM is finished and a Mac OS X partition has been selected, control passes to the BootX (PowerPC) or boot.efi (Intel) boot loader. The principal job of this boot loader is to load the kernel environment. As it does this, the boot loader draws the “booting” image on the screen.