User manual APPLE LEOPARD - COMMAND-LINE ADMINISTRATION

Mac OS X Server Command-Line Administration For Version 10.5 Leopard Apple Inc. © 2007 Apple Inc. All rights reserved. The owner or authorized user of a valid copy of Mac OS X Server software may reproduce this publication for the purpose of learning to use such software. No part of this publication may be reproduced or transmitted for commercial purposes, such as selling copies of this publication or for providing paid-for support services. Every effort has been made to ensure that the information in this manual is accurate. Apple Inc. is not responsible for printing or clerical errors. Apple 1 Infinite Loop Cupertino CA 95014-2084 408-996-1010 www.apple.com The Apple logo is a trademark of Apple Inc., registered in the U.S. and other countries. Use of the "keyboard" Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. Apple, the Apple logo, AppleScript, Bonjour, iCal, FireWire, iMac, iPod, iTunes, Keychain, Mac, the Mac logo, Macintosh, Mac OS, Power Mac, QuickTime, Xsan, Xgrid, and Xserve are trademarks of Apple Inc., registered in the U.S. and other countries. ARD, Finder, Leopard, and Spotlight are trademarks of Apple Inc. Apple Store is a service mark of Apple Inc., registered in the U.S. and other countries. Adobe and PostScript are trademarks of Adobe Systems Incorporated. The Bluetooth® word mark and logos are registered trademarks owned by Bluetooth SIG, Inc. and any use of such marks by Apple is under license. Intel, Intel Core, and Xeon are trademarks of Intel Corp. in the U.S. and other countries. PowerPCTM and the PowerPC logoTM are trademarks of International Business Machines Corporation, used under license therefrom. UNIX is a registered trademark of The Open Group. Other company and product names mentioned herein are trademarks of their respective companies. Mention of third-party products is for informational purposes only and constitutes neither an endorsement nor a recommendation. Apple assumes no responsibility with regard to the performance of these products. 019-0947/2007-11-01 1 Contents Preface 15 16 16 16 16 16 17 17 18 19 19 20 20 21 21 21 22 23 23 24 25 26 26 26 26 26 27 27 28 29 About This Guide Using This Guide Understanding Notation Conventions Summary Commands and Other Terminal Text Command Parameters and Options Default Settings Commands Requiring Root Privileges Mac OS X Server Administration Guides Viewing PDF Guides Onscreen Printing PDF Guides Getting Documentation Updates Getting Additional Information Executing Commands UNIX 03 Certification Opening Terminal Specifying Files and Folders Standard Pipes Redirecting Input and Output Using Environment Variables Executing Commands and Running Tools Correcting Typing Errors Repeating Commands Including Paths Using Drag and Drop Searching for Text in a File Commands Requiring Root Privileges Terminating Commands Scheduling Tasks Sending Commands to a Remote Computer Viewing Command Information Chapter 1 3 Chapter 2 31 31 31 32 33 34 35 35 35 36 37 39 39 41 41 42 42 42 43 45 45 48 49 49 49 50 51 51 52 53 55 55 55 56 56 56 57 57 59 59 Connecting to Remote Computers Understanding SSH How SSH Works Generating Key Pairs for Key-Based SSH Connections Updating SSH Key Fingerprints An SSH Man-in-the-Middle Attack Controlling Access to SSH Service Connecting to a Remote Computer Using SSH Using Telnet Remotely Controlling the Xserve Front Panel Installing Server Software and Finishing Basic Setup Installing Server Software Locating Computers for Installation Specifying the Target Computer Volume Preparing the Target Volume for a Clean Installation Restarting After Installation Automating Server Setup Creating a Configuration File Working with an Encrypted Configuration File Customizing a Configuration File Storing a Configuration File in an Accessible Location Configuring the Server Remotely from the Command Line Changing Server Settings Using the serversetup Tool Using the serveradmin Tool General and Network Preferences Viewing, Validating, and Setting the Software Serial Number Updating Server Software Moving a Server Restarting or Shutting Down a Computer Restarting a Computer Automatic Restart Changing a Remote Computer's Startup Disk Shutting Down a Computer Shutting Down While Leaving the Computer on and Powered Manipulating Open Firmware NVRAM Variables Monitoring and Restarting Critical Services Setting General System Preferences Viewing or Changing the Computer Name Chapter 3 Chapter 4 Chapter 5 4 Contents 59 60 60 60 61 61 61 61 62 63 63 63 63 63 64 64 Chapter 6 65 65 65 66 66 66 67 67 67 67 67 68 69 70 71 72 72 73 74 75 75 76 76 77 78 78 Viewing or Changing the Date and Time Viewing or Changing the System Date Viewing or Changing the System Time Viewing or Changing the System Time Zone Viewing or Changing Network Time Server Usage Viewing or Changing Energy Saver Settings Viewing or Changing Sleep Settings Viewing or Changing Automatic Restart Settings Changing Power Management Settings Viewing or Changing Startup Disk Settings Viewing or Changing Sharing Settings Viewing or Changing Remote Login Settings Viewing or Changing Apple Event Response Creating the Groups Share Point Viewing or Changing Language and Keyboard Settings Viewing and Changing Login Settings Setting Network Preferences Configuring Network Interfaces Managing Network Interface Information Viewing Port Names and Hardware Addresses Viewing or Changing MTU Values Viewing or Changing Media Settings Managing Network Port Configurations Creating or Deleting Port Configurations Activating Port Configurations Changing Configuration Precedence Managing TCP/IP Settings Changing a Server's IP Address Viewing or Changing the IP Address, Subnet Mask, or Router Address Viewing or Changing DNS Servers Enabling TCP/IP Statically Configuring Ethernet Interfaces Creating, Deleting, and Viewing VLANs IEEE 802.3ad Ethernet Link Aggregation Managing AppleTalk Settings Managing SNMP Settings Setting Up SNMP Starting SNMP Configuring SNMP Collecting SNMP Information from the Host Managing Proxy Settings Viewing or Changing FTP Proxy Settings Contents 5 78 78 79 79 79 79 80 80 80 81 81 82 83 Chapter 7 85 85 85 86 86 86 87 88 89 91 91 92 92 93 93 93 93 94 94 95 95 95 96 97 98 99 99 100 Viewing or Changing Web Proxy Settings Viewing or Changing Secure Web Proxy Settings Viewing or Changing Streaming Proxy Settings Viewing or Changing Gopher Proxy Setting Viewing or Changing SOCKS Firewall Proxy Settings Viewing or Changing Proxy Bypass Domains Managing AirPort Settings Managing Computer, Host, and Bonjour Names Computer Name Hostname Bonjour Name Managing Preference Files and the Configuration Daemon Changing Network Locations Working with Disks and Volumes Understanding Disks, Partitions, and the File System Mounting and Unmounting Volumes Mounting Volumes Unmounting Volumes Displaying Disk Information Monitoring Disk Space Reclaiming Disk Space Using Log-Rolling Scripts Using the diskutil Tool Using the pdisk, disklabel, and newfs Tools Partitioning a Disk Labeling a Disk Formatting a Disk Troubleshooting Disk Problems Managing Disk Journaling Determining if Journaling Is Enabled Enabling Journaling for a Volume Enabling Journaling When You Erase a Disk Disabling Journaling Understanding Spotlight Technology Enabling and Disabling Spotlight Performing Spotlight Searches Controlling Spotlight Indexing Managing RAID Volumes Imaging and Cloning Volumes Using ASR Managing User and Group Accounts User, Group, Computer, and Computer Group Accounts Administering and Creating User Accounts Chapter 8 6 Contents 100 101 102 102 105 106 106 107 108 109 110 111 112 113 114 115 117 117 118 118 118 121 122 123 127 127 128 129 130 130 131 131 131 131 132 133 134 136 Chapter 9 137 137 138 138 Creating a Local Administrator User Account for a Server Creating a Domain Administrator User Account Verifying a User's Administrator Privileges Creating a Nonadministrator User Account Retrieving a User's GUID Removing a User Account Preventing a User from Logging In Verifying a Server User's Name, UID, or Password Modifying a User Account Managing Home Folders Administering Group Accounts Creating a Group Account Removing a Group Account Adding a User to a Group Removing a User from a Group Creating and Deleting a Nested Group Editing Group Records Creating a Group Folder Viewing the Workgroup a User Selects at Login Working with Managed Preferences Using MCX Extensions Determining Effective Managed Preferences Importing Users and Groups Creating a Character-Delimited User Import File Exporting Users and Groups Setting Permissions Viewing Permissions Setting the umask Setting for a User Changing Permissions Changing the Owner Changing the Group Securing System Accounts Securing Initial System Accounts Securing the Root Account Restricting Use of the sudo Tool Securing Single-User Boot Setting Password Policy Finding User Account Information Working with File Services Managing Share Points Listing Share Points Creating a Share Point Contents 7 140 140 140 141 141 141 141 142 142 145 146 147 147 148 149 150 151 151 151 151 151 152 152 152 152 152 153 153 155 155 155 156 156 156 156 157 157 159 160 161 161 162 162 Modifying a Share Point Disabling a Share Point Setting Disk Quotas Managing AFP Service Starting and Stopping AFP Service Viewing AFP Service Status Viewing all AFP Settings Changing AFP Settings Available AFP Settings Available AFP serveradmin Commands Viewing Connected Users Sending a Message to AFP Users Disconnecting AFP Users Canceling a User Disconnect Viewing AFP Log Files Viewing AFP Service Statistics Managing NFS Service Starting and Stopping NFS Service Viewing NFS Service Status Viewing NFS Service Settings Changing NFS Service Settings Managing FTP Service Starting FTP Service Stopping FTP Service Viewing FTP Service Status Viewing FTP Service Settings Changing FTP Service Settings Available FTP Service Settings Available FTP serveradmin Commands Viewing the FTP Transfer Log Viewing for Connected FTP Users Managing SMB Service Starting and Stopping SMB Service Viewing SMB Service Status Viewing SMB Service Settings Changing SMB Service Settings Available SMB Service Settings Available SMB serveradmin Commands Viewing SMB User Information Disconnecting SMB Users Listing SMB Service Statistics Updating Share Point Information Viewing SMB Service Logs 8 Contents 162 163 164 Chapter 10 167 167 169 169 169 169 169 172 173 173 173 174 175 175 177 177 177 178 178 178 178 179 180 180 181 182 182 182 183 183 184 184 185 185 185 186 186 Managing ACLs Using chmod to Modify ACLs Using fsaclctl to Enable and Disable ACL Support Working with the Print Service Understanding the Print Process Performing Print Service Tasks Starting and Stopping Print Service Viewing the Status of Print Service Viewing Print Service Settings Changing Print Service Settings Managing Print Service Listing Queues Pausing and Releasing a Queue Listing Jobs and Job Information Holding and Releasing a Job Viewing Print Service Log Files and Log Paths Viewing Cover Pages Working with NetBoot Service and System Images Understanding NetBoot Service Starting and Stopping NetBoot Service Viewing NetBoot Service Status Viewing NetBoot Settings Changing NetBoot Settings Changing General Netboot Service Settings The Storage Record Array The Filters Record Array The Image Record Array The Port Record Array Working with System Images Updating an Image Booting from an Image Using hdiutil with System Images Using asr to Clone a Volume or to Restore System Images Imaging Multiple Clients Using Multicast asr Choosing a Boot Device Using systemsetup Managing Mail Service Understanding Mail Service Postfix Agent Cyrus Mailman Chapter 11 Chapter 12 Contents 9 187 187 187 187 187 188 200 200 201 202 203 203 205 206 206 206 207 208 208 Chapter 13 211 211 212 212 212 212 213 213 213 214 214 214 214 216 217 218 218 221 221 222 222 222 Managing Mail Service Starting and Stopping Mail Service Checking the Status of Mail Service Viewing Mail Service Settings Changing Mail Service Settings Mail Service Settings Mail serveradmin Commands Viewing Mail Service Statistics Viewing Mail Service Logs Backing Up Mail Files Setting Up SSL for Mail Service Generating a CSR and Creating a Keychain Obtaining an SSL Certificate Importing an SSL Certificate into the Keychain Accessing Server Certificates Creating a Password File Configuring Mailboxes Enabling Sieve Scripting Enabling Sieve Support Configuring and Managing Web Technologies Understanding Web Service Managing Web Service Starting and Stopping Web Service Checking Web Service Status Viewing Web Settings Changing Web Settings Apache Settings and serveradmin Changing Settings Using serveradmin Web serveradmin Commands Listing Hosted Sites Viewing Service Logs and Log Paths Viewing Service Statistics Example Script for Adding a Website Tuning Server Performance Apache Tomcat The MySQL Database Configuring and Managing Network Services Managing Network Services Managing DHCP Service Starting and Stopping DHCP Service Viewing the Status of DHCP Service Chapter 14 10 Contents 222 223 223 224 226 227 228 228 228 228 228 229 229 229 229 229 230 230 231 231 231 231 232 232 232 232 233 236 236 237 237 237 237 238 238 238 238 239 239 240 240 241 241 Viewing DHCP Service Settings Changing DHCP Service Settings DHCP Service Settings DHCP Subnet Settings Array Adding a DHCP Subnet Adding a DHCP Static Map Viewing the Location of the DHCP Service Log Viewing the DHCP Service Log Managing DNS Service Starting and Stopping DNS Service Checking the Status of DNS Service Viewing DNS Service Settings Changing DNS Service Settings DNS Service Settings Available DNS serveradmin Commands Viewing the DNS Service Log and Log Path Viewing DNS Service Statistics Configuring IP Forwarding Managing Firewall Service Firewall Startup Starting and Stopping Firewall Service Disabling Firewall Service Checking the Status of Firewall Service Viewing Firewall Service Settings Changing Firewall Service Settings Available Firewall Service Settings Defining Firewall Rules The ipfilter Rules Array Firewall serveradmin Commands Viewing the Firewall Service Log and Log Path Using Firewall Service to Simulate Network Activity Managing NAT Service Starting and Stopping NAT Service Viewing the Status of NAT Service Viewing NAT Service Settings Changing NAT Service Settings NAT Service Settings NAT serveradmin Commands Port Mapping Viewing the NAT Service Log and Log Path Managing VPN Service Starting and Stopping VPN Service Checking the Status of VPN Service Contents 11 241 241 242 245 245 245 246 247 247 247 248 248 249 251 251 Chapter 15 253 253 254 254 254 254 254 255 255 256 257 257 260 260 261 261 261 264 264 265 265 266 266 269 269 270 Viewing VPN Service Settings Changing VPN Service Settings Available VPN Service Settings Available VPN serveradmin Commands Viewing the VPN Service Log and Log Path Site-to-Site VPN Configuring Site-to-Site VPN Adding a VPN Keyagent User Setting Up IP Failover IP Failover Prerequisites IP Failover Operation Enabling IP Failover Configuring IP Failover Enabling PPP Dial-In Restoring the Default Configuration for Server Services Configuring and Managing Open Directory Understanding Open Directory Using General Directory Tools Testing Your Open Directory Configuration Modifying a Directory Domain Testing Open Directory Plug-ins Changing Open Directory Service Settings Managing OpenLDAP Configuring LDAP Configuring slapd and slurpd Daemons Idle Rebinding Options Searching the LDAP Server Using LDIF Files Additional Information About LDAP Managing Open Directory Passwords Open Directory Password Server Kerberos and Apple Single Sign-On Using Directory Service Tools Operating on Directory Service Domains Manipulating a Single Named Group Record Adding or Removing LDAP Server Configurations Configuring the Active Directory Plug-In Configuring the RADIUS Server Configuring and Managing QuickTime Streaming Server Understanding QTSS Performing QTSS Tasks Chapter 16 12 Contents 270 270 270 271 271 274 275 275 276 276 277 277 277 278 279 280 281 281 281 281 282 Chapter 17 283 283 283 283 284 284 285 285 285 286 286 286 287 287 287 287 287 287 288 288 289 Starting and Stopping QTSS Viewing QTSS Status Viewing QTSS Settings Changing QTSS Settings Available QTSS Parameters Managing QTSS Viewing QTSS Connections Viewing QTSS Statistics Viewing Service Logs and Log Paths Forcing QTSS to Reread Preferences Preparing Older Home Folders for User Streaming Configuring Streaming Security Resetting the Streaming Server Admin User Name and Password Controlling Access to Streamed Media Creating an Access File Accessing Protected Media Adding User Accounts and Passwords Adding or Deleting Groups Making Changes to the User or Group File Manipulating QuickTime and MP4 Movies Creating Reference Movies Configuring the Podcast Producer Service Controlling Podcast Capture Connecting to a Podcast Producer Server Submitting QuickTime Movies for Processing Viewing Cameras and Workflows Viewing and Clearing Uploads Binding and Unbinding Cameras Configuring Podcast Producer Agent Controlling Cameras Configuring Podcast Producer Service Configuring Workflows Configuring Cameras Configuring Properties Controlling Access to Properties Setting Up Podcast Producer as an Upload-Only Node Controlling Podcast Producer Service Starting and Stopping the Podcast Producer Service Viewing Status Information Launching Podcast Producer Server Upon System Startup Processing Submitted Content Applying Quartz Composer Compositions to Movies Contents 13 289 290 292 292 293 293 Chapter 18 295 295 296 297 297 297 297 298 299 301 305 321 Applying a Quartz Composer Transition Applying a Quartz Composer Effect Shared File System Uploading Mechanisms Copy Upload FTP Upload HTTPS CGI POST Upload Configuring and Managing iCal Service and iChat Service Configuring iCal Service Configuring iChat Service Configuring and Managing System Logging Logging System Events Configuring the Log File Configuring System Logging Local Logging Remote Logging PCI RAID Card Command Reference Chapter 19 Appendix Glossary Index 14 Contents This guide describes Mac OS X Server command-line tools and commands, including the syntax, purpose, and parameters, and provides examples of usage and output. Command-Line Administration is written for system administrators familiar with administering and managing servers, storage, and networks. Beneath the interface of Mac OS X is a core operating system known as Darwin. Darwin integrates a number of technologies, most importantly Mach 3.0, operating-system services based on Berkeley Software Distribution (BSD) release 4.4 high-performance networking facilities, and support for multiple integrated file systems. Darwin maintains most of the functionality of BSD 4.4 commands. Although some commands are modified, most commands are kept as is, or their functionality has been extended to support Apple-specific technologies. This guide focuses on commands developed by Apple to allow administrators to perform functions available in the graphical interface from the command line. The guide also highlights BSD commands that have been modified or extended to support Apple-specific functionality. Finally, the guide describes important commands commonly used by UNIX system administrators. Note: Because Apple periodically releases new versions and updates to its software, images shown in this book may be different from what you see on your screen. Preface 15 About This Guide Using This Guide This guide describes commands that perform functions used to configure and manage Mac OS X computers. Chapters in this guide describe sets of commands that work for specific aspects of the operating system. Use this guide to:  Learn which commands are available for specific tasks  Learn how the commands work, and how to execute them  Review examples of command usage Understanding Notation Conventions The following conventions are used throughout this book. Summary Notation monospaced font $ [text_in_brackets] (one|other) Indicates A command or other text typed in a Terminal window A shell prompt An optional parameter Alternative parameters (use one or the other) A parameter you must replace with a value A parameter that can be repeated A displayed value that depends on your server configuration italicized [...] Commands and Other Terminal Text Commands or command parameters that you enter, along with other text that appears in a Terminal window, are shown in this font. For example: You can use the doit command to get things done. When a command is shown on a line by itself in this manual, it is preceded by a dollar sign and a space that represent the shell prompt. For example: $ doit To use this command, enter it without the dollar sign and the space in a Terminal window, and then press Return. (Terminal is found in /Applications/Utilities/.) Command Parameters and Options Most commands require parameters to specify command options or the item to which the command is applied to. 16 Preface About This Guide Parameters You Must Enter as Shown If you must enter a parameter as shown, it appears following the command in the same font. For example: $ doit -w later -t 12:30 To use the command in this example, enter the entire line as shown (without the $ and space). Parameter Values You Provide If you must provide a value, its placeholder is italicized and has a name that indicates what you need to provide. For example: $ doit -w later -t hh:mm In this example, you replace hh with the hour and mm with the minute, as shown in the previous example. Optional Parameters If a parameter is not required, it appears in square brackets. For example: $ doit [-w later] To use the command in this example, enter doit or doit vary, but you perform the command either way. -w later. The result might Alternative Parameters If you must enter one of a number of parameters, they're separated by a vertical line and grouped within parentheses (|). For example: $ doit -w (now|later) To perform this command, enter doit -w now or doit -w later. Default Settings Descriptions of server settings usually include the default value for each setting. When this default value depends on your configuration (such as the name or IP address of your server), it's enclosed in angle brackets. For example, the default value for the IMAP mail server is the host name of your server. This is indicated by mail:imap:servername = "." Commands Requiring Root Privileges Throughout this manual, commands that require root privileges begin with sudo. See "Commands Requiring Root Privileges" on page 26. Preface About This Guide 17 Mac OS X Server Administration Guides Getting Started covers installation and setup for standard and workgroup configurations of Mac OS X Server. For advanced configurations, Server Administration covers planning, installation, setup, and general server administration. A suite of additional guides, listed below, covers advanced planning, setup, and management of individual services. You can get these guides in PDF format from the Mac OS X Server documentation website: www.apple.com/server/documentation This guide ... Getting Started and Mac OS X Server Worksheet Command-Line Administration File Services Administration iCal Service Administration iChat Service Administration Mac OS X Security Configuration Mac OS X Server Security Configuration Mail Service Administration Network Services Administration Open Directory Administration Podcast Producer Administration Print Service Administration QuickTime Streaming and Broadcasting Administration Server Administration tells you how to: Install Mac OS X Server and set it up for the first time. Install, set up, and manage Mac OS X Server using UNIX commandline tools and configuration files. Share selected server volumes or folders among server clients using the AFP, NFS, FTP, and SMB protocols. Set up and manage iCal shared calendar service. Set up and manage iChat instant messaging service. Make Mac OS X computers (clients) more secure, as required by enterprise and government customers. Make Mac OS X Server and the computer it's installed on more secure, as required by enterprise and government customers. Set up and manage IMAP, POP, and SMTP mail services on the server. Set up, configure, and administer DHCP, DNS, VPN, NTP, IP firewall, NAT, and RADIUS services on the server. Set up and manage directory and authentication services, and configure clients to access directory services. Set up and manage Podcast Producer service to record, process, and distribute podcasts. Host shared printers and manage their associated queues and print jobs. Capture and encode QuickTime content. Set up and manage QuickTime streaming service to deliver media streams live or on demand. Perform advanced installation and setup of server software, and manage options that apply to multiple services or to the server as a whole. Use NetBoot, NetInstall, and Software Update to automate the management of operating system and other software used by client computers. Use data and service settings from an earlier version of Mac OS X Server or Windows NT. System Imaging and Software Update Administration Upgrading and Migrating 18 Preface About This Guide This guide ... User Management Web Technologies Administration Xgrid Administration and High Performance Computing Mac OS X Server Glossary tells you how to: Create and manage user accounts, groups, and computers. Set up managed preferences for Mac OS X clients. Set up and manage web technologies, including web, blog, webmail, wiki, MySQL, PHP, Ruby on Rails, and WebDAV. Set up and manage computational clusters of Xserve systems and Mac computers. Learn about terms used for server and storage products. Viewing PDF Guides Onscreen While reading the PDF version of a guide onscreen:  Show bookmarks to see the guide's outline, and click a bookmark to jump to the corresponding section.  Search for a word or phrase to see a list of places where it appears in the document. Click a listed place to see the page where it occurs.  Click a cross-reference to jump to the referenced section. Click a web link to visit the website in your browser. Printing PDF Guides If you want to print a guide, you can take these steps to save paper and ink:  Save ink or toner by not printing the cover page.  Save color ink on a color printer by looking in the panes of the Print dialog for an option to print in grays or black and white.  Reduce the bulk of the printed document and save paper by printing more than one page per sheet of paper. In the Print dialog, change Scale to 115% (155% for Getting Started). Then choose Layout from the untitled pop-up menu. If your printer supports two-sided (duplex) printing, select one of the Two-Sided options. Otherwise, choose 2 from the Pages per Sheet pop-up menu, and optionally choose Single Hairline from the Border menu. (If you're using Mac OS X v10.4 or earlier, the Scale setting is in the Page Setup dialog and the Layout settings are in the Print dialog.) You may want to enlarge the printed pages even if you don't print double sided, because the PDF page size is smaller than standard printer paper. In the Print dialog or Page Setup dialog, try changing Scale to 115% (155% for Getting Started, which has CD-size pages). Preface About This Guide 19 Getting Documentation Updates Periodically, Apple posts revised help pages and new editions of guides. Some revised help pages update the latest editions of the guides.  To view new onscreen help topics for a server application, make sure your server or administrator computer is connected to the Internet and click "Latest help topics" or "Staying current" in the main help page for the application.  To download the latest guides in PDF format, go to the Mac OS X Server documentation website: www.apple.com/server/documentation Getting Additional Information For more information, consult these resources:  Read Me documents--important updates and special information. Look for them on the server discs.  Mac OS X Server website (www.apple.com/server/macosx)--gateway to extensive product and technology information.  Mac OS X Server Support website (www.apple.com/support/macosxserver)--access to hundreds of articles from Apple's support organization.  Apple Training website (www.apple.com/training)--instructor-led and self-paced courses for honing your server administration skills.  Apple Discussions website (discussions.apple.com)--a way to share questions, knowledge, and advice with other administrators.  Apple Mailing Lists website (www.lists.apple.com)--subscribe to mailing lists so you can communicate with other administrators using email.  Man pages (developer.apple.com/documentation/Darwin/Reference/ManPages)-- The Apple Developer Connection (ADC) Reference Library contains man pages for many BSD and POSIX functions and applications included with Mac OS X.  The public source website (developer.apple.com/darwin)--Access to Darwin source code, developer information, and FAQs. 20 Preface About This Guide 1 Executing Commands 1 Use this chapter to learn how to execute commands and to view online information about commands and tools. A command-line interface is a way for you to manipulate your computer in situations where a graphical approach is not available. The Terminal application is the Mac OS X gateway to the BSD command-line interface (UNIX shell command prompt). Each window in Terminal contains an execution context, called a shell, that is separate from all other execution contexts. The shell is an interactive programming language interpreter, with a specialized syntax for executing commands and writing structured programs called shell scripts. Different shells feature slightly different capabilities and programming syntax. Although you can use any shell, the examples in this book assume that you are using bash, the standard Mac OS X shell. UNIX 03 Certification Mac OS X Server v10.5 is now an "Open Brand UNIX 03 Registered Product," conforming to the SUSv3 and POSIX 1003.1 specifications for the C API, Shell Utilities, and Threads. Because Mac OS X Server v10.5 can compile and run your existing UNIX 03-compliant code, you can deploy it in environments that demand full conformance. At the same, Mac OS X Server v10.5 provides full compatibility with existing server and application software. Opening Terminal To enter shell commands or run server command-line tools, you need access to the UNIX shell prompt on the local server or on a remote server. To open Terminal, click the Terminal icon in the dock or double-click the application icon in the Finder (in /Applications/Utilities/). 21 Terminal presents a prompt when it is ready to accept a command. The prompt you see depends on your Terminal and shell preferences, but it often includes the name of the host you're logged in to, your current working folder, your user name, and a prompt symbol. For example, if you're using the default bash shell, the prompt appears as: server1:~ anne$ where you are logged in to a computer named server1 as the user named anne, and your current folder is anne's home folder (~). Throughout this manual, where a command is shown, the prompt is abbreviated as $. Specifying Files and Folders Most commands operate on files and folders, the locations of which are identified by paths. The folder names that make up a path are separated by slash characters. For example, the path to the Terminal application is /Applications/Utilities/Terminal.app. Standard shortcuts used to represent specific folders are shown in the following table. Because they are relative to the current folder, these shortcuts eliminate the need to enter full paths in many situations. Path string . Description A single period represents the current folder. This value is often used as a shortcut to eliminate the need to enter in a full path. For example, the string "./Test.c" represents the Test.c file in the current folder. Two periods represent the parent folder of the current folder. This string is used for navigating up one level from the current folder through the folder hierarchy. For example, the string "../Test" represents a sibling folder (named Test) of the current folder. The tilde character represents the home folder of the user logged in. In Mac OS X, this folder resides in the local /Users folder or on a network server. For example, to specify the Documents folder of the current user, you would specify ~/Documents. .. ~ File and folder names traditionally include letters, numbers, a period, or the underscore character. Avoid most other characters, including space characters. Although some Mac OS X file systems permit the use of these other characters, including spaces, you might need to add single or double quotation marks around pathnames that contain them. For individual characters, you can also "escape" the character--that is, put a backslash character immediately before the character in your string. For example, the pathname My Disk is "My Disk" or My\ Disk. 22 Chapter 1 Executing Commands Standard Pipes Many commands can receive text input from the user and print text to the console. They do so using standard pipes, which are created by the shell and passed to the command. Standard pipes include:  stdin--The standard input pipe is the means through which data enters a command. By default, the user enters this from the command-line interface. You can also redirect the output from files or other commands to stdin.  stdout--The standard output pipe is where the command output is sent. By default, command output is sent to the command line. You can also redirect the output from the command line to other commands and tools.  stderr--The standard error pipe is where error messages are sent. By default, errors are displayed on the command line like standard output. Redirecting Input and Output From the command line, you can redirect input and output from a command to a file or another command. Redirecting output lets you capture the results of running the command and store it in a file for later use. Similarly, providing an input file lets you provide a command with preset input data, instead of needing to enter that data. You can use the following characters to redirect input and output: Redirect > < >> Description Use the greater-than character to redirect command output to a file. Use the less-than character to use the contents of a file as input to the command. Use a double greater-than to append output from a command to a file. In addition to using file redirection, you can also redirect the output of one command to the input of another using the vertical bar character, or pipe. You can combine commands in this manner to implement more sophisticated versions of the same commands. For example, the command man bash | grep "commands" passes the formatted contents of the bash man page to the grep tool, which searches those contents for lines containing the word "commands." The result is a listing of lines with the specified text, instead of the entire man page. For more information about redirection, see the bash man page. Chapter 1 Executing Commands 23 Using Environment Variables Some commands require the use of environment variables for their execution. Environment variables are inherited by all commands executed in the shell's context. The shell uses environment variables to store information, such as the name of the current user, the name of the host computer, and the paths to any commands. You can create environment variables and use them to control the behavior of your command without modifying the command itself. For example, you can use an environment variable to have your command print debug information to the console. To set the value of an environment variable, use the appropriate shell command to associate a variable name with a value. For example, to set the variable PATH to the value /bin:/sbin:/user/bin:/user/sbin:/system/Library/, you would enter the following command in a Terminal window: $ PATH=/bin:/sbin:/user/bin:/user/sbin:/system/Library/ export PATH This modifies the environment variable PATH with the value assigned. To view all environment variables, enter the following: $ env When you launch an application from a shell, the application inherits much of the shell's environment, including exported environment variables. This form of inheritance can be a useful way to configure the application dynamically. For example, your application can verify for the presence (or value) of an environment variable and change its behavior accordingly. Different shells support different semantics for exporting environment variables, so see the man page for your preferred shell for further information. Although child processes of a shell inherit the environment of that shell, shells are separate execution contexts that do not share environment information with one another. Thus, variables you set in one Terminal window are not set in other Terminal windows. After you close a Terminal window, variables you set in that window are gone. If you want the value of a variable to persist between sessions and in all Terminal windows, you must set it in a shell startup script. Another way to set environment variables in Mac OS X is with a special property list in your home folder. At login, the computer looks for the ~/.MacOSX/environment.plist file. If the file is present, the computer registers the environment variables in the property list file. 24 Chapter 1 Executing Commands Executing Commands and Running Tools To execute a command in the shell, enter the complete pathname of the tool's executable file, followed by arguments, and then press Return. If a command is located in one of the shell's known folders, you can omit path information and enter the command name. The list of known folders is stored in the shell's PATH environment variable and includes the folders containing most command-line tools. For example, to run the ls command in the current user's home folder, you could enter the following at the command line and press Return: host:~ anne$ ls To run a command in the current user's home folder, you would precede it with the folder specifier. For example, to run MyCommandLineProg, you would use something like the following: host:~ anne$ ./MyCommandLineProg To launch a tool package, you can use the open command (open MyProg.app) or launch the tool by entering the pathname of the executable file inside the package, usually something like ./MyProg.app/Contents/MacOS/MyProg. When entering commands, if you get the message command spelling. Here is an example: server:/ anne$ sudo serversetup -getHostname serversetup: Command not found. not found, check your If the error recurs, the command you're trying to run might not be in your default search path. You can add the path before the command name, for example: server:/ anne$ sudo /System/Library/ServerSetup/serversetup -getHostname server.example.com or change your working folder to the folder that contains the tool. For example: server:/ anne$ cd /System/Library/ServerSetup server:/System/Library/ServerSetup anne$ sudo ./serversetup -getHostname server.example.com or server:/System/Library/ServerSetup anne$ cd / server:/ anne$ PATH="$PATH:/System/Library/ServerSetup" server:/ anne$ sudo serversetup -getHostname server.example.com Chapter 1 Executing Commands 25 Correcting Typing Errors You can use the Left and Right Arrow keys to correct typing errors before you press Return to execute a command. To correct a typing error: 1 Press Left Arrow or Right Arrow to skip over parts of the command you don't want to change. 2 Press Delete to remove characters. 3 Enter regular characters to insert them. 4 Press Return to execute the command. To ignore what you entered and start again, press Control­U. Repeating Commands To repeat a command, press Up Arrow until you see the command, then make modifications and press Return. Including Paths Using Drag and Drop To include a fully qualified filename or folder path in a command, you can drag and drop the folder or file from a Finder window into the Terminal window. Searching for Text in a File To locate a string within a file, use the grep tool. The grep tool searches the named input files for lines containing a match to the given pattern. By default, grep prints the matching lines. To search for a unique string in a file: $ grep search_string filename Replace search_string with the the string to search for and filename with the name of the file you want to search through. Commands Requiring Root Privileges Many commands used to manage a server must be executed by the root user. If you get a message such as permission denied, the command probably requires root privileges. However, when logged in as a root user, be careful: you have sufficient privileges to make changes that can cause your server to stop working. Important: Don't execute commands as the root user unless you know what you're doing. Instead, log in as an administrator user and selectively use sudo, which gives you root user privileges to execute one command. This helps you avoid making unintended changes when running other commands. 26 Chapter 1 Executing Commands The sudo command gives root user privileges to users specified in the sudoers file. If you're logged in as an administrator user and your username is specified in the etc/sudoers file, you can use this command. To execute a single command with root user privileges, begin the command with sudo (short for super user do). For example: $ sudo serveradmin list If you haven't used sudo recently, you're prompted for your administrator password. To switch to the root user so you don't need to repeatedly enter sudo, use the su command: $ su root or simply: $ su You're prompted for the root user password and are then logged in as the root user until you log out or use the su command to switch to another user. Note: The root user password is set to the administrator user password when you install Mac OS X Server. Important: To avoid running commands as root, log out after you finish using the su command. For more information about the sudo and su commands, see their man pages. Terminating Commands To terminate the currently running command, enter Control-C. This keyboard shortcut sends an abort signal to the command. In most cases this causes the command to terminate, although commands can install signal handlers to trap this signal and respond differently. Scheduling Tasks To schedule tasks to run at defined times, use the cron tool. This tool is a daemon that executes scheduled commands defined in crontab files. The cron tool searches the /var/cron/tabs/ folder for crontab files that are named after accounts in /etc/passwd, and loads the files into memory. The cron tool also searches for crontab files in the /etc/crontab/ folder, which are in a different format. cron then cycles every minute, examining stored crontab files and checking each command to see if it should be run in the current minute. Chapter 1 Executing Commands 27 When commands execute, output is mailed to the owner of the crontab file or to the user named in the MAILTO environment variable in the crontab file, if one exists. If you modify a crontab file, you must restart cron. You use crontab to install, deinstall, or list the tables used to drive the cron daemon. Users can have their own crontab file. To configure your crontab file, use the crontab crontab file. An example of a configured crontab file: SHELL=/bin/sh PATH=/bin:/sbin:/usr/bin:/usr/sbin HOME=/var/log #min hour mday month wday 30 18 * * 1-5 50 23 * * 0 command diskutil repairPermissions /Volumes/MacHD diskutil repairVolume /Volumes/MacHD -e command. This displays an empty Listed below is an explanation of the crontab structure shown above. The following crontab entry repairs disk permissions for the MacHD volume at 18:30 every day, Monday through Friday: 30 18 * * 1-5 diskutil repairPermissions /Volumes/MacHD The following crontab entry schedules a repair volume operation to run at 23:50 every Sunday: 50 23 * * 0 diskutil repairVolume /Volumes/MacHD Sending Commands to a Remote Computer You must connect to a remote computer before you can execute commands on it. You can send commands to a remote computer using:  Secure Shell (SSH), a tool for logging in to a remote computer and for executing commands on a remote computer.  Telnet, a tool for communicating with another computer using the TELNET protocol. For information about sending commands to remote computers, see Chapter 2, "Connecting to Remote Computers," on page 31. 28 Chapter 1 Executing Commands Viewing Command Information Most command-line documentation comes in the form of man pages. These formatted pages provide reference information for shell commands, tools, and high-level concepts. You can also access command information using the help command, and sometimes information is displayed if you enter the command without parameters or options. To access a man page: $ man command where command is the topic you want to find information about. The man page contains detailed information about the command, its options, parameters, and proper use. For help using the man command, enter: $ man man If man pages are too long to fit on your screen, use the more or less command to paginate the file. This allows you to view the file faster by loading screens of the man page at a time, rather than the entire file: $ man serveradmin | less When you use more or less, an information bar appears at the bottom of the screen. When you see the bar, you can press the Space bar to go to the next page, the B key to go back a page, or the Return key to scroll the file forward one line at a time. When you get to the end of a file, you to press the Q key to quit. more returns you to the prompt and less waits for Several third-party Mac OS X applications are available for viewing formatted man pages in scrollable windows. You can find one by choosing Mac OS X Software from the Apple menu and then searching for "man page." Note: Not all commands and tools have man pages. For a list of available man pages, look in /usr/share/man. Chapter 1 Executing Commands 29 To access command help: m Enter the command followed by the -help, -h, --help, or help parameter: $ hdiutil help $ dig -h $ diff --help To view a list of options and parameters you can use with the command: m Enter the command without options or parameters: $ sudo serveradmin Note: Not all techniques work for all commands, and some commands don't have onscreen help. 30 Chapter 1 Executing Commands 2 Connecting to Remote Computers 2 Use this chapter to learn the commands to connect to remote computers. Connecting to remote computers helps you manage and configure resources efficiently. This chapter covers using Secure Shell (SSH) and Telnet to connect to remote computers. Understanding SSH SSH lets you send secure, encrypted commands to a computer remotely, as if you were sitting at the computer. You use the ssh tool in Terminal to open a command-line connection to a remote computer. While the connection is open, commands you enter are performed on the remote computer. Note: You can use any application that supports SSH to connect to a computer running Mac OS X or Mac OS X Server. How SSH Works SSH works by setting up encrypted tunnels using public and private keys. Here is a description of an SSH session: 1 The local and remote computers exchange public keys. If the local computer has never encountered a given public key, SSH and your web browser prompt you whether to accept the unknown key. 2 The two computers use the public keys to negotiate a session key used to encrypt subsequent session data. 3 The remote computer attempts to authenticate the local computer using RSA or DSA certificates. If this is not possible, the local computer is prompted for a standard user-name/password combination. 4 After successful authentication, the session begins and remote shell, a secure file transfer, a remote command, or other action is begun through the encrypted tunnel. 31 The following are SSH tools:  sshd--Daemon that acts as a server to all other commands  ssh--Primary user tool that includes a remote shell, remote command, and portforwarding sessions  scp--Secure copy, a tool for automated file transfers  sftp--Secure FTP, a replacement for FTP Generating Key Pairs for Key-Based SSH Connections By default, SSH supports the use of password, key, and Kerberos authentication. The standard method of SSH authentication is to supply login credentials in the form of a user name and password. Identity key pair authentication enables you to log in to the server without supplying a password. Key-based authentication is more secure than password authentication because it requires that you have the private key file and know the password that lets you access that key file. Password authentication can be compromised without a private key file. This process works as follows: 1 A private and a public key are generated, each associated with a user name to establish that user's authenticity. 2 When you attempt to log in as that user, the user name is sent to the remote computer. 3 The remote computer looks in the user's .ssh/ folder for the user's public key. This folder is created after using SSH the first time. 4 A challenge is sent to the user based on his or her public key. 5 The user verifies his or her identity by using the private portion of the key pair to decode the challenge. 6 After the key is decoded, the user is logged in without the need for a password. This is especially useful when automating remote scripts. Note: If the server uses FileVault to encrypt the home folder of the user you want to use SSH to connect as, you must be logged in on the server to use SSH. Alternatively, you can store the keys for the user in a location that is not protected by FileVault, but this is not secure. 32 Chapter 2 Connecting to Remote Computers To generate the identity key pair: 1 Enter the following command on the local computer: $ ssh-keygen -t dsa 2 When prompted, enter a filename in the user's folder to save the keys in; then enter a password followed by password verification (empty for no password). For example: Generating public/private dsa key pair. Enter file in which to save the key (/Users/anne/.ssh/id_dsa): frog Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in frog. Your public key has been saved in frog.pub. The key fingerprint is: 4a:5c:6e:9f:3e:35:8b:e5:c9:5a:ac:00:e6:b8:d7:96 annejohnson1@mac.com This creates two files. Your identification or private key is saved in one file (frog in our example) and your public key is saved in the other (frog.pub in our example). The key fingerprint, which is derived cryptographically from the public key value, also appears. This secures the public key, making it computationally infeasible for duplication. 3 Copy the resulting public file, which contains the local computer's public key, to the .ssh/authorized_keys file in the user's home folder on the remote computer (~/.ssh/ authorized_keys). The next time you log in to the remote computer from the local computer you won't need to enter a password. Note: If you are using an Open Directory user account and have logged in using the account, you do not need to supply a password for SSH login. On Mac OS X Server computers, SSH uses Kerberos for single sign-on authentication with any user account that has an Open Directory password. (Kerberos must be running on the Open Directory server.) For more information, see Open Directory Administration. Updating SSH Key Fingerprints The first time you connect to a remote computer using SSH, the local computer prompts for permission to add the remote computer's fingerprint (or encrypted public key) to a list of known remote computers. You might see a message like this: The authenticity of host "server1.example.com" can't be established. RSA key fingerprint is a8:0d:27:63:74:f1:ad:bd:6a:e4:0d:a3:47:a8:f7. Are you sure you want to continue connecting (yes/no)? The first time you connect, you have no way of knowing whether this is the correct host key. Most people respond "yes." The host key is then inserted into the ~/.ssh/ known_hosts file so it can be verified in later sessions. Chapter 2 Connecting to Remote Computers 33 Be sure this is the correct key before accepting it. If possible, provide users with the encryption key through FTP, mail, or a download from the web, so they can be sure of the identity of the server. If you later see a warning message about a man-in-the-middle attack (see below) when you try to connect, it might be because the key on the remote computer no longer matches the key stored on the local computer. This can happen if you:  Change your SSH configuration on the local or remote computer.  Perform a clean installation of the server software on the computer you are attempting to log in to using SSH.  Start up from a Mac OS X Server CD on the computer you are attempting to log in to using SSH.  Attempt to use SSH to access a computer that has the same IP address as a computer that you used SSH with on another network. To connect again, delete the entries corresponding to the remote computer (which can be stored by name and IP address) in the file ~/.ssh/known_hosts. An SSH Man-in-the-Middle Attack Sometimes an attacker can access your network and compromise routing information, so that packets intended for a remote computer are routed to the attacker, who then impersonates the remote computer to the local computer and the local computer to the remote computer. Here's a typical scenario: A user connects to the remote computer using SSH. By means of spoofing techniques, the attacker poses as the remote computer and receives information from the local computer. The attacker then relays the information to the intended remote computer, receives a response, and then relays the remote computer's response to the local computer. Throughout the process, the attacker is privy to all information that goes back and forth, and can modify it. A sign that can indicate a man-in-the-middle attack is the following message that appears when connecting to the remote computer using SSH. @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ Protect for this type of attack by verifying that the host key sent back is the correct host key for the computer you are trying to reach. Be watchful for the warning message, and alert your users to its meaning. 34 Chapter 2 Connecting to Remote Computers Important: Removing an entry from the known_hosts file bypasses a security mechanism that would help you avoid imposters and man-in-the-middle attacks. Before you delete its entry from the known_hosts file, be sure you understand why the key on the remote computer has changed. Controlling Access to SSH Service You can use Server Admin to control which users can open a command-line connection using the ssh tool in Terminal. Users with administrator privileges can always open a connection using SSH. The ssh tool uses the SSH service. For information about controlling access to the SSH service, see Open Directory Administration. Connecting to a Remote Computer You can connect to a remote computer using SSH (secure) or Telnet (nonsecure). Using SSH Use the ssh tool to create a secure shell connection to a remote computer. To access a remote computer using ssh: 1 Open Terminal. 2 Log in to the remote computer by entering the following command: $ ssh -l username server Replace username with the name of an administrator user on the remote computer. Replace server with the name or IP address of the remote computer. For example: $ ssh -l anne 10.0.1.2 If this is the first time you've connected to the remote computer, you're prompted to continue connecting after the remote computer's RSA fingerprint appears. 3 Enter yes. 4 When prompted, enter the user's password for the remote computer. The command prompt changes to show that you're connected to the remote computer. In the case of the previous example, the prompt might look like this: 10.0.1.2:~ anne$ Chapter 2 Connecting to Remote Computers 35 5 To send a command to the remote computer, enter the command. 6 To close a remote connection, enter logout. You can authenticate and send a command using a single line by appending the command to execute to the basic ssh tool. For example, to delete a file you could use: $ ssh -l anne server1.example.com rm /Users/anne/Documents/report or $ ssh -l anne@server1.example.com "rm /Users/anne/Documents/report" You're prompted for the user's password. Using Telnet Use the telnet tool to create a Telnet connection to a remote computer. Because telnet isn't as secure as SSH, Telnet access is disabled by default. To enable Telnet access: $ sudo service telnet start To disable Telnet access: $ sudo service telnet stop You are strongly advised not to enable Telnet. When you log in using Telnet, your login information, user name, and password (as well as your entire Telnet session) are passed over the Internet in clear text. Any person on the network running tcpdump, ethereal, or similar applications can sniff the network and take possession of your user name and password. If you run something as root during your Telnet session, your root user account is also compromised. To access a remote computer using telnet: $ telnet -l username server Replace username with the name of an administrator user on the remote computer. Replace server with the name or IP address of the remote computer. For example: $ telnet -l anne 10.0.1.2 After being connected, the remote computer prompts for a login name and password. Depending on the type of computer you are accessing, you may see a message of the form: TERM = (vt100) Press Enter to accept this default setting. 36 Chapter 2 Connecting to Remote Computers You may see a series of messages on the screen, followed by the remote computer's prompt. You are now logged in. When you finish working, log out from the remote computer by entering logout or exit at the remote computer's prompt. The telnet client exits when you log out from the remote computer. For more information, see the telnet man page. Remotely Controlling the Xserve Front Panel You can use the ipmitool command to remotely control an Xserve's front panel. To display the list of supported virtual front panel commands: $ ipmitool chassis bootdev bootdev [clear-cmos=yes|no] none : Do not change boot device order pxe : Force PXE boot (LOM: Force boot NetBoot server) disk : Force boot from default Hard-drive safe : Force boot from default Hard-drive, request Safe Mode (LOM: Not used) diag : Force boot from Diagnostic Partition (LOM: Force boot diagnostic mode from NetBoot server) cdrom : Force boot from CD/DVD bios : Force boot into BIOS Setup (LOM: Not used) Lights-out Management additional options nvram : Force reset of NVRAM tdm : Force boot into Target Disk Mode other : Skip current startup disk selection, and boot from other Mac OS X Server v10.5 supports the following commands: nvram, tdm, and other. none, pxe, disk, diag, cdrom, For example, entering the following command and then restarting an Xserve system starts the system in Target Disk Mode: $ ipmitool chassis bootdev tdm After the system starts, the ipmitool command reverts to the default setting (none). Restarting the Xserve system without running the ipmitool command does not change the boot device order. For more information about ipmitool, see its man page. Chapter 2 Connecting to Remote Computers 37 38 Chapter 2 Connecting to Remote Computers 3 Installing Server Software and Finishing Basic Setup 3 Use this chapter to learn the commands to install, set up, and update Mac OS X Server software on local or remote computers. This chapter explains the commands to perform software setup and installation tasks. Some computers come with Mac OS X Server software installed. However, you might want to upgrade from a previous version, change a computer configuration, automate software installation, or refresh your server environment. Installing Server Software To install Mac OS X Server or other software on a computer, use the /usr/sbin/installer tool. You can use the installer tool locally or remotely. The installer tool requires at least two arguments: the installation package and the destination of the installation package. For a standard installation, your target would be the root drive. Here is an example installation command: $ installer -pkg OSInstall.mpkg -target / Other useful options include:  lang--The operating system package requires that you choose a language. This flag allows you to do so from the command line. The argument is a two-character ISO language code. For English, it's en.  verbose--Prints the details of the installation. It's useful for monitoring progress. For more information, see the installer man page. 39 To use the installer to install Mac OS X Server software: 1 Start the target computer from the first installation CD or the installation DVD. The procedure you use depends on the target computer hardware:  If the target computer has a keyboard and an optical drive, insert the first installation disc into the optical drive; then hold down the C key on the keyboard while restarting the computer.  If the target computer is an Xserve with a built-in optical drive, start the computer using the first installation disc by following the instructions for starting from a system disc in the Xserve User's Guide.  If the target computer is an Xserve with no built-in optical drive, you can start it in target disk mode and insert the installation disc into the optical drive on your administrator computer. You can also use an external FireWire optical drive or an optical drive from another Xserve system to start the computer from the installation disc. Instructions for using target disk mode and external optical drives are in the Quick Start guide or Xserve User's Guide that came with your Xserve system. 2 If you're installing on a local computer, when Installer opens choose Utilities > Open Terminal to open the Terminal application. If you're installing on a remote computer, from Terminal on an administrator computer or from a UNIX workstation, establish an SSH session as the root user with the target computer, substituting ip_address with the target computer's actual IP address: $ ssh root@ip_address If you don't know the IP address, use the sa_srchr tool to identify computers, on the local subnet where you can install server software: $ /System/Library/Serversetup/sa_srchr 224.0.0.1 mycomputer.example.com#PowerMac4,4###Mac OS X Server 10.5#RDY4PkgInstall#2.0#512 You can also use Server Assistant to generate information for computers on the local subnet. To access the Destination pane and generate a list of computers awaiting installation in Open Server Assistant, select "Install software on a remote computer" and click Continue. 3 When prompted for a password, enter the first eight digits of the computer's built-in hardware serial number. To find a computer's serial number, look for a label on the computer. If the target computer is set up as a server, you'll also find the hardware serial number in /System/ Library/ServerSetup/SerialNumber. If you're installing on an older computer that has no built-in hardware serial number, use 12345678 for the password. 40 Chapter 3 Installing Server Software and Finishing Basic Setup Locating Computers for Installation If you are installing software on a remote computer from Terminal, you must first establish an SSH session as the root user with the remote computer. To do so, you need the remote computer's IP address and serial number. You can find the serial number on a label on the computer. Enter the serial number as the password when establishing the SSH session. If you are installing on an older computer that has no built-in hardware serial number, use 12345678 for the password. To identify the IP address of each computer that's ready for installation on your subnet, use the sa_srchr tool. Note: To locate remote computers, start up your computer from the installation CD. To view computers on the local network: $ /System/Library/ServerSetup/sa_srchr 224.0.0.1 The sa_srchr tool uses the broadcast address 224.0.0.1 to request a response (via sa_rspndr) from all computers ready for installation or setup. The response from a ready computer comes from sa_rspndr running on a computer started up from the Mac OS X Server installation CD. The computer responds with output similar to the following: localhost#unknown###Mac OS X Server 10.5#RDY4PkgInstall#2.0#512 where is the working IP address and is the unique MAC address of the network interface on a computer that is ready for installation. Specifying the Target Computer Volume To specify the target computer volume where you want to install the server software, use the installer tool. To list volumes available for server software: $ /usr/sbin/installer -volinfo -pkg /System/Installation/Packages/ OSInstall.mpkg To choose a network installation image you've created and mounted: $ /usr/sbin/installer -volinfo -pkg /Volumes/ServerNetworkImage10.5/System/ Installation/Packages/OSInstall.mpkg The list displayed reflects your environment, but here's an example showing three available volumes: /Volumes/Mount 01 /Volumes/Mount 1 /Volumes/Mount 02 Chapter 3 Installing Server Software and Finishing Basic Setup 41 Preparing the Target Volume for a Clean Installation If the target volume has Mac OS X Server v10.3 or v10.4 installed, when you run installer, it upgrades the server to v10.5 and preserves user files. If you're performing a clean installation, back up the user files you want to preserve, then use diskutil to erase the volume, format it, and enable journaling: $ /usr/sbin/diskutil eraseVolume HFS+ "Mount 01" "/Volumes/Mount 01" $ /usr/sbin/diskutil enableJournal "/Volumes/Mount 01" You can also use case-sensitive Journaled HFS+ as a startup volume format, which is an available format for the Erase and Install option for local installations, but not for remotely controlled installations. Important: Third-party applications might have problems with case-sensitive Journaled HFS+ format because of case mismatch. For example, when referencing the PlugIns folder, some third-party applications might use the term PlugIns while other parts might use the term Plugins. This works on HFS+ and Journaled HFS+, but not on casesensitive Journaled HFS+. You can also use diskutil to partition the volume and set up mirroring. For more information, see the diskutil man page or Chapter 7, "Working with Disks and Volumes," on page 85. Important: Don't store data on the hard disk partition where the operating system is installed. If you must store additional software or data on the system partition, consider mirroring the drive. With this approach, you won't risk losing data if you reinstall or upgrade system software. Restarting After Installation When installation from the disc is complete, restart the computer by entering: $ /sbin/reboot or $ /sbin/shutdown -r Automating Server Setup You can automate server setup by providing a configuration file that contains setup settings. Normally when you install Mac OS X Server on a computer and restart, Server Assistant opens and prompts you for the basic information necessary to get the server running. This includes the user name and password of the administrator, the TCP/IP configuration information for the computer's network interfaces, and how the computer uses directory services. 42 Chapter 3 Installing Server Software and Finishing Basic Setup Servers that have had Mac OS X Server v10.5 installed automatically detect the presence of the saved setup information and use it to complete initial server setup without user interaction. You can define generic setup data that can be used to set up any computer. For example, you can define generic setup data for a computer that's on order, or for 50 Xserve computers you want to be identically configured. You can also save setup data that's specifically tailored for a computer. Important: When you perform an upgrade, saved setup data is used and overwrites existing server settings. If you do not want saved server setup data to be used after an upgrade, rename the saved setup configuration file. Creating a Configuration File An easy way to prepare configuration files to automate the setup of a group of computers is to start with a file you save using Server Assistant. You can save the file as the last step when you use Server Assistant to set up the first computer, or you can run Server Assistant later to create the file. You can then use that configuration file as a template for creating configuration files for other computers. You can edit the file directly, or write scripts to create customized configuration files for computers that use similar hardware. Note: If you intend to create a generic configuration file because you want to use the file to set up additional computers, don't specify network names (computer names or local hostnames), and make sure each network interface (port) is set to be configured using DHCP or using BootP. To save a configuration file during server setup: 1 In the final pane of Server Assistant, after you review the settings, click Save As. 2 In the dialog that appears, choose Configuration File next to "Save As" and click OK:  If encryption is not required, don't select "Save in Encrypted Format."  To encrypt the file, select "Save in Encrypted Format" and enter and verify a passphrase. You must supply the passphrase before an encrypted setup file can be used by a target computer. 3 Navigate to the location where you want to save the configuration file, name the file using one of the following options, and click Save. Target computers search for names in the order listed:  MAC-address-of-server.plist (include leading zeros but omit colons)--for example, 0030654dbcef.plist  IP-address-of-server.plist--for example, 10.0.0.4.plist Chapter 3 Installing Server Software and Finishing Basic Setup 43  partial-DNS-name-of-server.plist--for example, myserver.plist  built-in-hardware-serial-number-of-server.plist (first 8 characters only)--for example, ABCD1234.plist  fully-qualified-DNS-name-of-server.plist--for example, myserver.example.com.plist  partial-IP-address-of-server.plist--for example, 10.0.plist (matches 10.0.0.4 and 10.0.1.2)  generic.plist--file that any server will recognize, used to set up servers that need the same setup values Server Assistant uses the file to set up the computer with the matching address, name, or serial number. If Server Assistant cannot find a file named for a specific computer, it will use the file named generic.plist. To create a configuration file after initial setup: 1 Open Server Assistant (located in /Applications/Server/). 2 In the Welcome pane, select "Save advanced setup information in a file or a directory record" and click Continue. 3 Enter settings in the remaining panes; then, after you review the settings in the final pane, click Save As. 4 In the dialog that appears, choose Configuration File next to Save As and click OK:  If encryption is not required, don't select "Save in Encrypted Format."  To encrypt the file, select "Save in Encrypted Format" and then enter and verify a passphrase. You must supply the passphrase before an encrypted setup file can be used by a target computer. 5 Navigate to the location where you want to save the configuration file, name the file using one of the following options, and click Save. Target computers search for names in the order listed here:  MAC-address-of-server.plist (include leading zeros but omit colons)--for example, 0030654dbcef.plist  IP-address-of-server.plist--for example, 10.0.0.4.plist  partial-DNS-name-of-server.plist--for example, myserver.plist  built-in-hardware-serial-number-of-server.plist (first 8 characters only)--for example, ABCD1234.plist  fully-qualified-DNS-name-of-server.plist--for example, myserver.example.com.plist  partial-IP-address-of-server.plist--for example, 10.0.plist (matches 10.0.0.4 and 10.0.1.2)  generic.plist--file that any computer will recognize, used to set up computers that need the same setup values. Server Assistant uses the file to set up the computer with the matching address, name, or serial number. If Server Assistant cannot find a file named for a computer, it uses the file named generic.plist. 44 Chapter 3 Installing Server Software and Finishing Basic Setup Working with an Encrypted Configuration File If the setup data in the configuration file is encrypted, make the passphrase available to target computers. You can supply the passphrase interactively using Server Assistant, or you can provide it in a text file. To provide a passphrase in a file: 1 Create a text file and enter the passphrase for the saved setup file on the first line. 2 Save the file using one of the following names. Target computers search for names in the order listed here:  MAC-address-of-server.pass (include leading zeros but omit colons)--for example, 0030654dbcef.pass  IP-address-of-server.pass--for example, 10.0.0.4.pass  partial-DNS-name-of-server.pass--for example, myserver.pass  built-in-hardware-serial-number-of-server.pass (first 8 characters only)--for example, ABCD1234.pass  fully-qualified-DNS-name-of-server.pass--for example, myserver.example.com.pass  partial-IP-address-of-server.pass--for example, 10.0.pass (matches 10.0.0.4 and 10.0.1.2)  generic.pass--file that any computer will recognize 3 Put the passphrase file on a volume mounted locally on the target computer in /Volumes/*/Auto Server Setup/, where * is any device mounted under /Volumes. To provide a passphrase interactively: 1 Use Server Assistant on an administrator computer that can connect to the target computer. 2 In the Welcome or Destination pane, choose File > Supply Passphrase. 3 In the dialog box, enter the target computer's IP address, password, and passphrase, then click Send. Customizing a Configuration File After you create a configuration file, you can modify it using a text editor, or you can write a script to generate custom configuration files for a group of computers. The file uses XML format to encode the setup information. The name of an XML key indicates the setup parameter it contains. Chapter 3 Installing Server Software and Finishing Basic Setup 45 The following sample configuration file shows the basic structure and contents of a configuration file for a computer with this configuration:  An administrator user named "Administrator" (short name "admin") with a user ID of 501 and the password "secret"  A computer name and host name of "server1.example.com"  A single Ethernet network interface set to get its address from DHCP  No server services set to start automatically Note: Angle brackets used in XML format do not have the same usage as angle brackets used in Mac OS X Server commands. Sample Configuration File AdminUser exists name admin password secret realname admin uid 501 Bonjour BonjourEnabled BonjourName leopardserver ComputerName leopardserver DS DSType Standalone DefaultGroupName longname Work Group shortname 46 Chapter 3 Installing Server Software and Finishing Basic Setup workgroup HostName leopardserver.example.com InstallLanguage English Keyboard DefaultFormat 0 DefaultScript 0 ResName U.S. ScriptID 0 kbResID 0 NetworkInterfaces ActiveAT ActiveTCPIP DNSServers 10.0.0.1 DeviceName en0 EthernetAddress 00:00:00:00:00:00 IPv6 IPv6Type 3 PortName Built-in Ethernet Settings IPAddress 10.0.0.2 Router 10.0.0.1 SubnetMask 255.255.255.0 Type Manual Configuration Chapter 3 Installing Server Software and Finishing Basic Setup 47 PrimaryLanguage English SerialNumber XSVR-???-???-?-???-???-???-???-???-???-?|Registered_to| Organization ServiceNTP HostNTP HostNTPServer time.apple.com UseNTP TimeZone US/Pacific VersionNumber 3 Note: The contents of the configuration file depend on the hardware configuration of the computer it's created on, so you should customize a configuration file created on a computer similar to those you plan to set up. Storing a Configuration File in an Accessible Location Server Assistant looks for configuration files in the following location: /Volumes/vol/Auto Server Setup/ where vol is a device volume mounted in /Volumes. Devices you can use to provide configuration files include:  A partition on a computer's hard disk  An iPod  An optical (CD or DVD) drive  A USB or FireWire drive  Any other portable storage device that mounts in the /Volumes folder 48 Chapter 3 Installing Server Software and Finishing Basic Setup Configuring the Server Remotely from the Command Line It's possible to configure the server remotely from the command line. Performing this task requires the following tools:  dscl--Use to create, read, and manage directory service data. If invoked without commands, dscl runs interactively, reading commands from standard input. For more information about this command, see Chapter 8, "Managing User and Group Accounts."  to set a number of system-wide preferences. If you used Server Assistant, you would need to select the proper keyboard and time zone. The systemsetup tool can configure these preferences, and more. For more information about this command, see Chapter 5, "Setting General System Preferences." systemsetup--Use  to configure anything that you can configure in the Network pane of System Preferences. For more information about this command, see Chapter 6, "Setting Network Preferences." networksetup--Use For more information about these tools, see their man pages. The man pages for systemsetup and networksetup are available only on Mac OS X Server. Changing Server Settings After initial setup, you can use a variety of commands to view or change Mac OS X Server configuration settings and services. Using the serversetup Tool The serversetup tool is located in /System/Library/ServerSetup/. To run it, you can enter the full path: $ /System/Library/ServerSetup/serversetup -getHostname To use the tool to perform several commands, change your working folder and enter a shorter command: $ cd /System/Library/ServerSetup $ ./serversetup -getHostname $ ./serversetup -getComputername Or, add the folder to your search path for this session and enter an even shorter command: $ PATH="$PATH:/System/Library/ServerSetup" $ serversetup -getHostname To permanently add the folder to your search path, add the path to the file /etc/profile. Chapter 3 Installing Server Software and Finishing Basic Setup 49 Using the serveradmin Tool You use the serveradmin tool to administer service-related tasks. Some services must be restarted after you change specific settings. If you make a change using a service's writeSettings tool that requires you to restart the service, the output from the command includes the setting :needsRecycleOrRestart with a value of yes. Important: The needsRecycleOrRestart setting appears only if you use the serveradmin svc:command = writeSettings command to change settings. You won't see it if you use the serveradmin settings command. Other chapters in this guide provide information about using serveradmin to administer specific services. Notes on Communication Security and the servermgrd Tool  When you run the serveradmin tool, you're communicating with a local or remote servermgrd process.  By default, port 687, which allows cleartext connections with servermgrd, is disabled. You can enable this port by changing the listenForRegularConnections parameter or key to yes in the /Library/Preferences/com.apple.servermgrd.plist file.  For encryption and client authentication, servermgrd uses SSL, but not for user authentication. User authentication uses Open Directory services.  servermgrd uses a self-signed (test) SSL certificate installed by default, located in /etc/servermgrd/ssl.crt/. You can replace this with an actual certificate. To create and manage certificates, use Certificate Manager in Server Admin. For more information, see Mail Service Administration.  The default certificate format for SSLeay/OpenSSL is PEM. PEM format can contain private keys (RSA and DSA), public keys (RSA and DSA), and (x509) certificates. It stores data in Base64-encoded DER format with ASCII header and footer lines, which makes it suitable for text-made transfers between computers. For some tools, you need the certificate in plain DER format. You can convert a PEM file (cert.pem) into the corresponding DER file (cert.der) with the following command: $ openssl x509 -in cert.pem -out cert.der -outform DER 50 Chapter 3 Installing Server Software and Finishing Basic Setup