Apple MAC OS X SERVER 10.5 Command-Line Administration Manual

Mac OS X Server

Command-Line Administration

For Version 10.5 Leopard



Apple Inc.

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.

™

PowerPC

and the PowerPC logo™ 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

Preface 15 About This Guide

Using This Guide

Understanding Notation Conventions

16 16 16 17 17 18 19

19 20 20

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

Chapter 1 21 Executing Commands

UNIX 03 Certification

Opening Terminal

Specifying Files and Folders

Standard Pipes

23 24 25 26 26 26 26 26 27 27 28 29

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 2 31 Connecting to Remote Computers

Understanding SSH

31 32 33 34 35 35 35 36 37

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

Chapter 3 39 Installing Server Software and Finishing Basic Setup

Installing Server Software

41 42 42 42 43 45 45 48 49 49 49 50

51 52 53

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

Chapter 4 55 Restarting or Shutting Down a Computer

Restarting a Computer

55 56 56 56 57 57

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

Chapter 5 59 Setting General System Preferences

Viewing or Changing the Computer Name

Contents

Viewing or Changing the Date and Time

60 60 60

61 61 61

61 62 63 63 63 63 63 64 64

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

Chapter 6 65 Setting Network Preferences

Configuring Network Interfaces

Managing Network Interface Information

66 66 66 67 67 67 67 67 68 69 70

71 72 72 73 74 75 75 76 76 77 78 78

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

78 78 79 79 79 79 80 80

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

80 Computer Name

81 Hostname

81 Bonjour Name 82 Managing Preference Files and the Configuration Daemon 83 Changing Network Locations

Chapter 7 85 Working with Disks and Volumes

85 Understanding Disks, Partitions, and the File System 85 Mounting and Unmounting Volumes 86 Mounting Volumes 86 Unmounting Volumes 86 Displaying Disk Information 87 Monitoring Disk Space 88 Reclaiming Disk Space Using Log-Rolling Scripts 89 Using the diskutil Tool

91 Using the pdisk, disklabel, and newfs Tools

91 Partitioning a Disk 92 Labeling a Disk 92 Formatting a Disk 93 Troubleshooting Disk Problems 93 Managing Disk Journaling 93 Determining if Journaling Is Enabled 93 Enabling Journaling for a Volume 94 Enabling Journaling When You Erase a Disk 94 Disabling Journaling 95 Understanding Spotlight Technology 95 Enabling and Disabling Spotlight 95 Performing Spotlight Searches 96 Controlling Spotlight Indexing 97 Managing RAID Volumes 98 Imaging and Cloning Volumes Using ASR

Chapter 8 99 Managing User and Group Accounts

99 User, Group, Computer, and Computer Group Accounts

10 0 Administering and Creating User Accounts

Contents

10 0 Creating a Local Administrator User Account for a Server 101 Creating a Domain Administrator User Account 10 2 Verifying a User’s Administrator Privileges 10 2 Creating a Nonadministrator User Account 10 5 Retrieving a User’s GUID 10 6 Removing a User Account 10 6 Preventing a User from Logging In 10 7 Verifying a Server User’s Name, UID, or Password 10 8 Modifying a User Account 10 9 Managing Home Folders

11 0 Administering Group Accounts

111 Creating a Group Account 112 Removing a Group Account 113 Adding a User to a Group 11 4 Removing a User from a Group 11 5 Creating and Deleting a Nested Group 117 Editing Group Records 117 Creating a Group Folder 11 8 Viewing the Workgroup a User Selects at Login 11 8 Working with Managed Preferences 11 8 Using MCX Extensions

121 Determining Effective Managed Preferences 12 2 Importing Users and Groups 12 3 Creating a Character-Delimited User Import File 12 7 Exporting Users and Groups 12 7 Setting Permissions 12 8 Viewing Permissions 12 9 Setting the umask Setting for a User 13 0 Changing Permissions 13 0 Changing the Owner 131 Changing the Group 131 Securing System Accounts 131 Securing Initial System Accounts 131 Securing the Root Account 13 2 Restricting Use of the sudo Tool 13 3 Securing Single-User Boot 13 4 Setting Password Policy 13 6 Finding User Account Information

Chapter 9 137 Working with File Services

13 7 Managing Share Points 13 8 Listing Share Points 13 8 Creating a Share Point

Contents 7

14 0 Modifying a Share Point 14 0 Disabling a Share Point 14 0 Setting Disk Quotas

141 Managing AFP Service 141 Starting and Stopping AFP Service 141 Viewing AFP Service Status

141 Viewing all AFP Settings 14 2 Changing AFP Settings 14 2 Available AFP Settings 14 5 Available AFP serveradmin Commands 14 6 Viewing Connected Users 14 7 Sending a Message to AFP Users 14 7 Disconnecting AFP Users 14 8 Canceling a User Disconnect 14 9 Viewing AFP Log Files 15 0 Viewing AFP Service Statistics

151 Managing NFS Service

151 Starting and Stopping NFS Service

151 Viewing NFS Service Status

151 Viewing NFS Service Settings

151 Changing NFS Service Settings 15 2 Managing FTP Service 15 2 Starting FTP Service 15 2 Stopping FTP Service 15 2 Viewing FTP Service Status 15 2 Viewing FTP Service Settings 15 3 Changing FTP Service Settings 15 3 Available FTP Service Settings 15 5 Available FTP serveradmin Commands 15 5 Viewing the FTP Transfer Log 15 5 Viewing for Connected FTP Users 15 6 Managing SMB Service 15 6 Starting and Stopping SMB Service 15 6 Viewing SMB Service Status 15 6 Viewing SMB Service Settings 157 Changing SMB Service Settings 157 Available SMB Service Settings 15 9 Available SMB serveradmin Commands 160 Viewing SMB User Information

161 Disconnecting SMB Users

161 Listing SMB Service Statistics 162 Updating Share Point Information 162 Viewing SMB Service Logs

8 Contents

162 Managing ACLs 163 Using chmod to Modify ACLs 164 Using fsaclctl to Enable and Disable ACL Support

Chapter 10 167 Working with the Print Service

167 Understanding the Print Process 169 Performing Print Service Tasks 169 Starting and Stopping Print Service 169 Viewing the Status of Print Service 169 Viewing Print Service Settings 169 Changing Print Service Settings 17 2 Managing Print Service 17 3 Listing Queues 17 3 Pausing and Releasing a Queue 17 3 Listing Jobs and Job Information

174 Holding and Releasing a Job 17 5 Viewing Print Service Log Files and Log Paths 17 5 Viewing Cover Pages

Chapter 11 177 Working with NetBoot Service and System Images

17 7 Understanding NetBoot Service 17 7 Starting and Stopping NetBoot Service 17 8 Viewing NetBoot Service Status 17 8 Viewing NetBoot Settings 17 8 Changing NetBoot Settings 17 8 Changing General Netboot Service Settings 17 9 The Storage Record Array 18 0 The Filters Record Array 18 0 The Image Record Array

181 The Port Record Array 18 2 Working with System Images 18 2 Updating an Image 18 2 Booting from an Image 183 Using hdiutil with System Images 183 Using asr to Clone a Volume or to Restore System Images 18 4 Imaging Multiple Clients Using Multicast asr 18 4 Choosing a Boot Device Using systemsetup

Chapter 12 185 Managing Mail Service

185 Understanding Mail Service 185 Postfix Agent 18 6 Cyrus 18 6 Mailman

Contents 9

187 Managing Mail Service 187 Starting and Stopping Mail Service 187 Checking the Status of Mail Service 187 Viewing Mail Service Settings 187 Changing Mail Service Settings 18 8 Mail Service Settings

200 Mail serveradmin Commands 200 Viewing Mail Service Statistics 201 Viewing Mail Service Logs 202 Backing Up Mail Files 203 Setting Up SSL for Mail Service 203 Generating a CSR and Creating a Keychain 205 Obtaining an SSL Certificate 206 Importing an SSL Certificate into the Keychain 206 Accessing Server Certificates 206 Creating a Password File 207 Configuring Mailboxes 208 Enabling Sieve Scripting 208 Enabling Sieve Support

Chapter 13 211 Configuring and Managing Web Technologies

211 Understanding Web Service 212 Managing Web Service 212 Starting and Stopping Web Service 212 Checking Web Service Status 212 Viewing Web Settings 213 Changing Web Settings 213 Apache Settings and serveradmin 213 Changing Settings Using serveradmin 214 Web serveradmin Commands 214 Listing Hosted Sites 214 Viewing Service Logs and Log Paths 214 Viewing Service Statistics 216 Example Script for Adding a Website 217 Tuning Server Performance 218 Apache Tomcat 218 The MySQL Database

Chapter 14 221 Configuring and Managing Network Services

221 Managing Network Services 222 Managing DHCP Service 222 Starting and Stopping DHCP Service 222 Viewing the Status of DHCP Service

10 Contents

222 Viewing DHCP Service Settings 223 Changing DHCP Service Settings 223 DHCP Service Settings 224 DHCP Subnet Settings Array 226 Adding a DHCP Subnet 227 Adding a DHCP Static Map 228 Viewing the Location of the DHCP Service Log 228 Viewing the DHCP Service Log 228 Managing DNS Service 228 Starting and Stopping DNS Service 228 Checking the Status of DNS Service 229 Viewing DNS Service Settings 229 Changing DNS Service Settings 229 DNS Service Settings 229 Available DNS serveradmin Commands 229 Viewing the DNS Service Log and Log Path 230 Viewing DNS Service Statistics 230 Configuring IP Forwarding

231 Managing Firewall Service

231 Firewall Startup

231 Starting and Stopping Firewall Service

231 Disabling Firewall Service 232 Checking the Status of Firewall Service 232 Viewing Firewall Service Settings 232 Changing Firewall Service Settings 232 Available Firewall Service Settings 233 Defining Firewall Rules 236 The ipfilter Rules Array 236 Firewall serveradmin Commands 237 Viewing the Firewall Service Log and Log Path 237 Using Firewall Service to Simulate Network Activity 237 Managing NAT Service 237 Starting and Stopping NAT Service 238 Viewing the Status of NAT Service 238 Viewing NAT Service Settings 238 Changing NAT Service Settings 238 NAT Service Settings 239 NAT serveradmin Commands 239 Port Mapping 240 Viewing the NAT Service Log and Log Path 240 Managing VPN Service

241 Starting and Stopping VPN Service

241 Checking the Status of VPN Service

Contents 11

241 Viewing VPN Service Settings

241 Changing VPN Service Settings 242 Available VPN Service Settings 245 Available VPN serveradmin Commands 245 Viewing the VPN Service Log and Log Path 245 Site-to-Site VPN 246 Configuring Site-to-Site VPN 247 Adding a VPN Keyagent User 247 Setting Up IP Failover 247 IP Failover Prerequisites 248 IP Failover Operation 248 Enabling IP Failover 249 Configuring IP Failover

251 Enabling PPP Dial-In

251 Restoring the Default Configuration for Server Services

Chapter 15 253 Configuring and Managing Open Directory

253 Understanding Open Directory 254 Using General Directory Tools 254 Testing Your Open Directory Configuration 254 Modifying a Directory Domain 254 Testing Open Directory Plug-ins 254 Changing Open Directory Service Settings 255 Managing OpenLDAP 255 Configuring LDAP 256 Configuring slapd and slurpd Daemons 257 Idle Rebinding Options 257 Searching the LDAP Server 260 Using LDIF Files 260 Additional Information About LDAP

261 Managing Open Directory Passwords

261 Open Directory Password Server

261 Kerberos and Apple Single Sign-On 264 Using Directory Service Tools 264 Operating on Directory Service Domains 265 Manipulating a Single Named Group Record 265 Adding or Removing LDAP Server Configurations 266 Configuring the Active Directory Plug-In 266 Configuring the RADIUS Server

Chapter 16 269 Configuring and Managing QuickTime Streaming Server

269 Understanding QTSS 270 Performing QTSS Tasks

12 Contents

270 Starting and Stopping QTSS 270 Viewing QTSS Status 270 Viewing QTSS Settings

271 Changing QTSS Settings

271 Available QTSS Parameters 274 Managing QTSS 275 Viewing QTSS Connections 275 Viewing QTSS Statistics 276 Viewing Service Logs and Log Paths 276 Forcing QTSS to Reread Preferences 277 Preparing Older Home Folders for User Streaming 277 Configuring Streaming Security 277 Resetting the Streaming Server Admin User Name and Password 278 Controlling Access to Streamed Media 279 Creating an Access File 280 Accessing Protected Media

281 Adding User Accounts and Passwords

281 Adding or Deleting Groups

281 Making Changes to the User or Group File

281 Manipulating QuickTime and MP4 Movies 282 Creating Reference Movies

Chapter 17 283 Configuring the Podcast Producer Service

283 Controlling Podcast Capture 283 Connecting to a Podcast Producer Server 283 Submitting QuickTime Movies for Processing 284 Viewing Cameras and Workflows 284 Viewing and Clearing Uploads 285 Binding and Unbinding Cameras 285 Configuring Podcast Producer Agent 285 Controlling Cameras 286 Configuring Podcast Producer Service 286 Configuring Workflows 286 Configuring Cameras 287 Configuring Properties 287 Controlling Access to Properties 287 Setting Up Podcast Producer as an Upload-Only Node 287 Controlling Podcast Producer Service 287 Starting and Stopping the Podcast Producer Service 287 Viewing Status Information 288 Launching Podcast Producer Server Upon System Startup 288 Processing Submitted Content 289 Applying Quartz Composer Compositions to Movies

Contents 13

289 Applying a Quartz Composer Transition 290 Applying a Quartz Composer Effect 292 Shared File System Uploading Mechanisms 292 Copy Upload 293 FTP Upload 293 HTTPS CGI POST Upload

Chapter 18 295 Configuring and Managing iCal Service and iChat Service

295 Configuring iCal Service 296 Configuring iChat Service

Chapter 19 297 Configuring and Managing System Logging

297 Logging System Events 297 Configuring the Log File 297 Configuring System Logging 298 Local Logging 299 Remote Logging

Appendix 301 PCI RAID Card Command Reference

Glossary 305

Index 321

14 Contents

About This Guide

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.

Preface

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.

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 Indicates

monospaced font A command or other text typed in a Terminal window

$ A shell prompt

[text_in_brackets] An optional parameter

(one|other) Alternative parameters (use one or the other)

italicized

[...] A parameter that can be repeated

<angle brackets> A displayed value that depends on your server configuration

A parameter you must replace with a value

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:

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 -w later. The result might vary, but you perform the command either way.

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 = "<hostname>."

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 ... tells you how to:

Getting Started and Mac OS X Server Worksheet

Command-Line Administration Install, set up, and manage Mac OS X Server using UNIX command-

File Services Administration Share selected server volumes or folders among server clients

iCal Service Administration Set up and manage iCal shared calendar service.

iChat Service Administration Set up and manage iChat instant messaging service.

Mac OS X Security Configuration Make Mac OS X computers (clients) more secure, as required by

Mac OS X Server Security Configuration

Mail Service Administration Set up and manage IMAP, POP, and SMTP mail services on the

Network Services Administration Set up, configure, and administer DHCP, DNS, VPN, NTP, IP firewall,

Open Directory Administration Set up and manage directory and authentication services, and

Podcast Producer Administration Set up and manage Podcast Producer service to record, process,

Print Service Administration Host shared printers and manage their associated queues and print

QuickTime Streaming and Broadcasting Administration

Server Administration Perform advanced installation and setup of server software, and

System Imaging and Software Update Administration

Upgrading and Migrating Use data and service settings from an earlier version of Mac OS X

Install Mac OS X Server and set it up for the first time.

line tools and configuration files.

using the AFP, NFS, FTP, and SMB protocols.

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.

server.

NAT, and RADIUS services on the server.

configure clients to access directory services.

and distribute podcasts.

jobs.

Capture and encode QuickTime content. Set up and manage QuickTime streaming service to deliver media streams live or on demand.

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.

Server or Windows NT.

18 Preface About This Guide

This guide ... tells you how to:

User Management Create and manage user accounts, groups, and computers. Set up

managed preferences for Mac OS X clients.

Web Technologies Administration Set up and manage web technologies, including web, blog,

webmail, wiki, MySQL, PHP, Ruby on Rails, and WebDAV.

Xgrid Administration and High Performance Computing

Mac OS X Server Glossary Learn about terms used for server and storage products.

Set up and manage computational clusters of Xserve systems and Mac computers.

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

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/).

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

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.

PATH

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 not found, check your spelling. Here is an example:

server:/ anne$ sudo serversetup -getHostname

serversetup: Command not found.

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

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

Replace search_string with the the string to search for and filename with the name of the file you want to search through.

search_string filename

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 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.

cron tool also searches

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 -e command. This displays an empty 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 command 30 18 * * 1-5 diskutil repairPermissions /Volumes/MacHD 50 23 * * 0 diskutil repairVolume /Volumes/MacHD

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

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.

is the topic you want to find information about. The man page contains

When you get to the end of a file, more returns you to the prompt and less waits for you to press the Q key to quit.

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

+ 299 hidden pages

Apple MAC OS X SERVER 10.5 Command-Line Administration Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

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

Viewing PDF Guides Onscreen

Printing PDF Guides

Getting Documentation Updates

Getting Additional Information

1 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