Apple MAC OS X SERVER 10.5 Command-Line Administration Manual

Download

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

2 Connecting to Remote Computers

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.

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

forwarding 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): Enter passphrase (empty for no passphrase): Enter same passphrase again:

frog

Your identification has been saved in Your public key has been saved in The key fingerprint is: 4a:5c:6e:9f:3e:35:8b:e5:c9:5a:ac:00:e6:b8:d7:96 annejohnson1@mac.com

frog

.pub.

frog

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

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$

username server

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

$ 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 <device> [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: none, pxe, disk, diag, cdrom,

nvram, tdm, and other.

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

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.

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

$ ssh root@

ip_address

with the target computer’s actual 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#<ip address>#<mac address>#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#<ip address>#<mac address>#Mac OS X Server

10.5#RDY4PkgInstall#2.0#512

where <ip_address> is the working IP address and <mac address> 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

$ /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/<pass-phrase-file>, 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

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/

DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict>

<key>AdminUser</key> <dict>

<key>exists</key>

<string>admin</string>

<key>password</key>

<string>secret</string>

<key>realname</key>

<string>admin</string>

</dict> <key>Bonjour</key> <dict>

<key>BonjourEnabled</key>

<true/>

<key>BonjourName</key>

<string>leopardserver</string>

</dict> <key>ComputerName</key> <string>leopardserver</string> <key>DS</key> <dict>

<key>DSType</key>

<string>Standalone</string>

</dict> <key>DefaultGroupName</key> <dict>

<key>longname</key>

<string>Work Group</string>

<key>shortname</key>

46 Chapter 3 Installing Server Software and Finishing Basic Setup

<string>workgroup</string>

</dict> <key>HostName</key> <string>leopardserver.example.com</string> <key>InstallLanguage</key> <string>English</string> <key>Keyboard</key> <dict>

<key>DefaultFormat</key>

<key>DefaultScript</key>

<key>ResName</key>

<key>ScriptID</key>

<key>kbResID</key>

</dict> <key>NetworkInterfaces</key> <array>

<dict>

<key>ActiveAT</key> <false/> <key>ActiveTCPIP</key> <true/> <key>DNSServers</key> <array>

<string>10.0.0.1</string> </array> <key>DeviceName</key> <string>en0</string> <key>EthernetAddress</key> <string>00:00:00:00:00:00</string> <key>IPv6</key> <dict>

<string>3</string> </dict> <key>PortName</key> <string>Built-in Ethernet</string> <key>Settings</key> <dict>

<key>IPAddress</key>

<key>Router</key>

<key>SubnetMask</key>

<string>Manual Configuration</string>

Chapter 3 Installing Server Software and Finishing Basic Setup 47

</dict>

</dict> </array> <key>PrimaryLanguage</key> <string>English</string> <key>SerialNumber</key> <string>XSVR-???-???-?-???-???-???-???-???-???-?|Registered_to|

Organization</string> <key>ServiceNTP</key> <dict>

<key>HostNTP</key>

<key>HostNTPServer</key>

<string>time.apple.com</string>

<key>UseNTP</key>

<true/> </dict> <key>TimeZone</key> <string>US/Pacific</string> <key>VersionNumber</key> <integer>3</integer>

</dict> </plist>

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/

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

vol

/Auto Server 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.”

Â systemsetup—Use 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.”

Â networksetup—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.”

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

<svc>:needsRecycleOrRestart with a value of yes.

Important: The needsRecycleOrRestart setting appears only if you use the

serveradmin

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

svc

:command = writeSettings command to change settings. You won’t

50 Chapter 3 Installing Server Software and Finishing Basic Setup

Â servermgrd checks the validity of the SSL certificate if the “Require valid digital

signature” option is selected in Server Admin preferences. This option uses an SSL certificate installed on a remote server to ensure that the remote server is a valid server. If this option is enabled, the certificate must be valid and not expired, or Server Admin will refuse to connect.

Before enabling this option, use the instructions in Mail Service Administration for generating a Certificate Signing Request (CSR), obtaining an SSL certificate from an issuing authority, and installing the certificate on each remote server.

Instead of placing files in /etc/httpd/, place them in /etc/servermgrd/.

You can also generate a self-signed certificate and install it on the remote server.

Â You can change servermgrd SSL encryption options by editing the

com.apple.servermgrd.plist configuration file located in /Library/Preferences/. Your SSL certificate (ssl.crt/server.crt) and keyfile (ssl.key/server.key) are located in /private/etc/servermgrd/.

General and Network Preferences

For information about changing general system preferences and network settings, see the following:

Â Chapter 5, “Setting General System Preferences,” on page 59 Â Chapter 6, “Setting Network Preferences,” on page 65

Viewing, Validating, and Setting the Software Serial Number

To view or set the server’s software serial number or to validate a server software serial number, use the serversetup tool, located in /System/Library/ServerSetup/.

To view the server’s software serial number:

$ sudo serversetup -getServerSerialNumber

To set the server software serial number:

$ sudo serversetup -setServerSerialNumber

where

serialnumber

is a valid Mac OS X Server software serial number, as found on the

software packaging that comes with the software.

To validate a server software serial number:

$ sudo serversetup -verifyServerSerialNumber

watermarkinformation

This displays 0 if the serial number is valid, or 1 if the serial number is invalid.

Chapter 3 Installing Server Software and Finishing Basic Setup 51

serialnumber watermarkinformation

serialnumber

Serial numbers generated for the server can be generated with watermarks so they can be tracked to a specific company, group, or individual. If a serial number has watermarking strings associated with it, it is necessary to supply the watermark information when setting or validating the serial number.

To verify that a serial number is site-licensed:

$ sudo serversetup -isSiteLicensedSerialNumber

Updating Server Software

You can use the softwareupdate tool to check for and install software updates over the Internet from Apple’s website.

To check for available updates:

$ sudo softwareupdate --list

The output is similar to the following:

Software Update found the following new or updated software:

- WebObjects5.3.1ServerUpdate-5.3.1 WebObjects5.3.1 Server Update (5.3.1), 29110K [recommended] [restart] * J2SE50Release3-3.0 **PRERELEASE** J2SE 5.0 Release 3 (8M318) (3.0), 44020K [recommended]

- AirPort-1.0 AirPort Update 2005-001 (1.0), 1440K [restart]

To install an update:

$ sudo softwareupdate --install

Parameter Description

update-version

The hyphenated product version string that appears in the list of updates when you use the

--list option

Some updates require that you agree to a license agreement. To work around this in an automated command-line environment, execute the following command before running softwareupdate:

$ command_line_install=1 export command_line_install

This creates an environment variable named command_line_install that automates update responses.

For more information, see the

52 Chapter 3 Installing Server Software and Finishing Basic Setup

softwareupdate man page.

Moving a Server

Before setting a server up for the first time, try to place it in its final network location (subnet). If you’re concerned about unauthorized or premature access, set up a firewall to protect the server while you’re finishing its configuration.

If you must move a server after setup, you must change settings that are sensitive to network location before the server can be used. For example, the server’s IP address and host name—stored in both folders and configuration files that reside on the server—must be updated.

When you move a server, consider these guidelines: Â Minimize the time the server is in its temporary location so the information you must

change is limited.

Â Don’t configure services that depend on network settings until the server is in its

final location. Such services include Open Directory replication, Apache settings (such as virtual hosts), DHCP, and other network infrastructure settings that other computers depend on.

Â Wait to import final user accounts. Limit accounts to test accounts so you minimize

the user-specific network information (such as home folder location) that must be changed after the move.

Â After you move the server, use the changeip tool to change IP addresses, host names,

and other data stored in Open Directory and LDAP folders on the server. See “Changing a Server’s IP Address” on page 68. After using the tool, you may need to adjust network configurations, such as the local DNS database.

Â Reconfigure the search policy of computers (such as user computers and DHCP

servers) that have been configured to use the server in its original location. For information about configuring a computer’s search policy, see Open Directory Administration.

Chapter 3 Installing Server Software and Finishing Basic Setup 53

54 Chapter 3 Installing Server Software and Finishing Basic Setup

4 Restarting or Shutting Down a

Computer

Use this chapter to learn the commands to shut down or restart a local or remote computer.

This chapter covers the commands that shut down or restart a local or remote computer. Computers must be shut down or restarted, whether locally or remotely, when installing tools or making computer repairs.

Restarting a Computer

To restart a computer at a specific time, use the reboot or shutdown -r command. For more information, see the relevant man pages.

To restart the local computer:

$ shutdown -r now

To restart a remote computer immediately:

$ ssh -l root

computer

shutdown -r now

To restart a remote computer at a specific time:

$ ssh -l root

Parameter Description

computer

hhmm

computer

shutdown -r

The IP address or DNS name of the computer

The hour and minute when the computer restarts

hhmm

Automatic Restart

You can also use the systemsetup tool to set up the computer to start up after a power failure or system freeze. See “Viewing or Changing Automatic Restart Settings” on page 61.

Changing a Remote Computer’s Startup Disk

You can change a remote computer’s startup disk using SSH.

To change the startup disk:

disk

$ bless -folder "/Volumes/

Parameter Description

disk

/System/Library/CoreServices" -setBoot

The name of the disk that contains the startup volume

For information about using SSH to log in to a remote computer, see “Sending Commands to a Remote Computer” on page 28.

Shutting Down a Computer

To shut down a computer at a specific time, use the shutdown tool. For more information, see the shutdown man page.

To shut down a remote computer immediately:

$ ssh -l root

To shut down the local computer in 30 minutes:

$ shutdown -h +30

computer

shutdown -h now

Parameter Description

computer

The IP address or DNS name of the computer

Shutting Down While Leaving the Computer on and Powered

To support UPS restart after power failure, the shutdown tool provides the -u option. This option halts system shutdown before the shutdown tool instructs the power manager to turn off the power supply.

The -u option keeps the system halted and waits for 5 minutes before removing power so an external UPS can forcibly remove power.

Using the -u option simulates a dirty shutdown, which allows a later automatic power on. The operating system uses the -u option with supported UPS devices in emergency shutdowns.

56 Chapter 4 Restarting or Shutting Down a Computer

Manipulating Open Firmware NVRAM Variables

To manipulate Open Firmware NVRAM variables, use the nvram tool. If you modify a value with For more information, see the

nvram, the value is saved only if the computer cleanly restarts or shuts down.

nvram man page.

To view NVRAM variables:

$ nvram -p

Monitoring and Restarting Critical Services

In earlier versions of Mac OS X, a daemon called watchdog monitored critical services and restarted them if they failed or quit unexpectedly after a computer restarted.

watchdog daemon relied on the configuration file watchdog.conf, located in /etc/.

The

In Mac OS X Server v10.4, watchdog was replaced by launchd. The launchd daemon manages other daemons, both for the computer and for users. You can configure the

launchd daemon to launch other daemons on demand, based on criteria specified in

their respective XML property lists.

During system startup, launchd is the first process invoked by the kernel to run and set up the computer. In Mac OS X Server, it is preferable to have your daemon started by

launchd.

Note: Some system administrators must modify the boot process to insert a script or implement a change in the default system configuration. System administrators are encouraged to work with launchd to implement changes, and avoid modifying rc or creating a SystemStarter Startup Item. The rc command script might be phased out in the future.

The configuration files are in the following folders:

Folder Usage

/System/Library/LaunchAgents/ Configuration for the system

/System/Library/LaunchDaemons/ Configuration for the daemons

~/Library/LaunchAgents/ Configuration per user

Chapter 4 Restarting or Shutting Down a Computer 57

58 Chapter 4 Restarting or Shutting Down a Computer

5 Setting General System

Preferences

Use this chapter to learn the commands to set system preferences.

You can use Mac OS X Server to manage the work environment of Mac OS X users by defining preferences. Preferences are settings that customize and control a user’s computer experience.

Viewing or Changing the Computer Name

You can use the systemsetup tool to view or change a computer name (the name used to browse for AFP share points on the server), which would otherwise be set using the Sharing pane of System Preferences.

To display the computer name:

$ sudo systemsetup -getcomputername

$ sudo networksetup -getcomputername

To change the computer name:

$ sudo systemsetup -setcomputername

$ sudo networksetup -setcomputername

computername

Viewing or Changing the Date and Time

You can use the systemsetup or serversetup tool to view or change a computer’s system date, time, and time zone. In addition, you can use the systemsetup tool to view or change whether a server uses a network time server.

You can also change these settings using the Date & Time pane of System Preferences.

Viewing or Changing the System Date

To view the system date

$ sudo systemsetup -getdate

$ serversetup -getDate

To set the system date:

$ sudo systemsetup -setdate

mm:dd:yy

$ sudo serversetup -setDate

mm/dd/yy

Viewing or Changing the System Time

To view the system time:

$ sudo systemsetup -gettime

$ serversetup -getTime

To change the system time:

$ sudo systemsetup -settime

hh:mm:ss

$ sudo serversetup -setTime

hh:mm:ss

Viewing or Changing the System Time Zone

To view the time zone:

$ sudo systemsetup -gettimezone

$ serversetup -getTimeZone

To view available time zones:

$ sudo systemsetup -listtimezones

To change the system time zone:

$ sudo systemsetup -settimezone

$ sudo serversetup -setTimeZone

timezone

60 Chapter 5 Setting General System Preferences

Viewing or Changing Network Time Server Usage

To see if a network time server is being used:

$ sudo systemsetup -getusingnetworktime

To enable or disable a network time server:

$ sudo systemsetup -setusingnetworktime (on|off)

To view the network time server:

$ sudo systemsetup -getnetworktimeserver

To specify a network time server:

$ sudo systemsetup -setnetworktimeserver

timeserver

Viewing or Changing Energy Saver Settings

To view or change a server’s energy saver settings, use the systemsetup tool (or the Energy Saver pane of System Preferences).

Viewing or Changing Sleep Settings

To view the idle time before sleep:

$ sudo systemsetup -getsleep

To set the idle time before sleep:

$ sudo systemsetup -setsleep

minutes

To see if the system is set to wake for modem activity:

$ sudo systemsetup -getwakeonmodem

To set the system to wake for modem activity:

$ sudo systemsetup -setwakeonmodem (on|off)

To see if the system is set to wake for network access:

$ sudo systemsetup -getwakeonnetworkaccess

To set the system to wake for network access:

$ sudo systemsetup -setwakeonnetworkaccess (on|off)

Viewing or Changing Automatic Restart Settings

To see if the system is set to restart after a power failure:

$ sudo systemsetup -getrestartpowerfailure

To set the system to restart after a power failure:

$ sudo systemsetup -setrestartpowerfailure (on|off)

To see how long the system waits to restart after a power failure:

$ sudo systemsetup -getwaitforstartupafterpowerfailure

Chapter 5 Setting General System Preferences 61

To set how long the system waits to restart after a power failure:

$ sudo systemsetup -setwaitforstartupafterpowerfailure

Parameter Description

seconds

Must be a multiple of 30 seconds

seconds

To see if the system is set to restart after a system freeze:

$ sudo systemsetup -getrestartfreeze

To set the system to restart after a system freeze:

$ sudo systemsetup -setrestartfreeze (on|off)

Changing Power Management Settings

You can use the pmset tool to change power management settings, including:

Â Display dim timer Â System sleep timer Â Wake on network activity Â Wake on modem activity Â Restart after power failure Â Dynamic processor speed change Â Reduce processor speed Â Sleep computer on power button press

You configure settings for power modes using pmset. There are four pmset flags:

Flag Description

-a Applies the power settings to all.

-b Applies the power settings to battery operation.

-c Applies the power settings to the charger (wall power).

-u Applies the power settings to the Uninterruptible Power Supply (UPS).

To set the disk sleep timer for all modes of operation:

$ sudo pmset -u disksleep

Parameter Description

minutes

Must be a multiple of 30 seconds

minutes

To display the settings in use:

$ sudo pmset -g

For more information, see the pmset man page.

62 Chapter 5 Setting General System Preferences

Viewing or Changing Startup Disk Settings

To view or change a computer’s startup disk, use the systemsetup tool (or the Startup Disk pane of System Preferences).

To view the startup disk:

$ sudo systemsetup -getstartupdisk

To view available startup disks:

$ sudo systemsetup -liststartupdisks

To change the startup disk:

$ sudo systemsetup -setstartupdisk

path

Viewing or Changing Sharing Settings

To view or change Sharing settings, use the systemsetup tool (or the Sharing pane of System Preferences).

Viewing or Changing Remote Login Settings

You can use SSH to log in to a remote server if remote login is enabled.

To see if the system is set to allow remote login:

$ sudo systemsetup -getremotelogin

To enable or disable remote login:

$ sudo systemsetup -setremotelogin (on|off)

$ serversetup -enableSSH

By default, Telnet access is disabled because it isn’t as secure as SSH. However, you can enable Telnet access. See “Using Telnet” on page 36.

Viewing or Changing Apple Event Response

To see if the system is set to respond to remote events:

$ sudo systemsetup -getremoteappleevents

To set the server to respond to remote events:

$ sudo systemsetup -setremoteappleevents (on|off)

Creating the Groups Share Point

To create the Groups share point:

$ serversetup -createGroupsSharePoint

Chapter 5 Setting General System Preferences 63

Viewing or Changing Language and Keyboard Settings

To view or change language settings, use the serversetup tool (or the International pane of System Preferences).

To view the primary language:

$ serversetup -getPrimaryLanguage

To view the installed language:

$ serversetup -getInstallLanguage

To set the installation language:

$ sudo serversetup -setInstallLanguage

To select a keyboard:

$ sudo serversetup -setKeyboardSelection ScripID(0) kbResID(0) ResName(U.S.)

To select a keyboard:

$ sudo serversetup --setNewPrimaryLanguage adminshortname

installLanguage

To view the script setting:

$ serversetup -getPrimaryScriptCode

language

primaryLanguage

Viewing and Changing Login Settings

You can enable or disable the Restart and Shutdown buttons that appear in the login dialog.

To disable or enable the Restart and Shutdown buttons in the login dialog:

$ sudo serversetup -setDisableRestartShutdown (0|1)

disables the buttons and 1 enables the buttons.

To view the current setting:

$ serversetup -getDisableRestartShutdown

64 Chapter 5 Setting General System Preferences

6 Setting Network Preferences

Use this chapter to learn the commands to change network settings on a server.

Mac OS X Server provides command-line control to manage servers in a mixedplatform environment and to configure, deploy, and manage powerful network services. These tools make it easy to configure and maintain core network services, while providing the advanced features and functionality required by experienced IT professionals.

Configuring Network Interfaces

To configure network interfaces, Mac OS X Server provides networksetup and

serversetup. Although ifconfig (the standard UNIX tool for configuring networks) is

available, it’s better to use networksetup and serversetup because if you use ifconfig, your computer will be out of sync and will revert to using the contents of preferences.plist after a restart.

You can still use ifconfig to view the network interface configuration. This is particularly beneficial when your computer is using an autonegotiated Ethernet connection.

For more information, see the networksetup and serversetup man pages.

Managing Network Interface Information

This section describes commands you address to a specific hardware device (for example, en0) or port (for example, Built-in Ethernet).

If you prefer to work with network port configurations following the approach used in the Network preferences pane of System Preferences, see the commands in “Managing Network Port Configurations” on page 67.

Viewing Port Names and Hardware Addresses

To list all port names with their Ethernet (MAC) addresses:

$ sudo networksetup -listallhardwareports

To list hardware port information by port configuration:

$ sudo networksetup -listallnetworkservices

An asterisk (*) in the results marks an inactive configuration.

To view the default (en0) Ethernet (MAC) address of the server:

$ serversetup -getMacAddress

To view the Ethernet (MAC) address of a port:

$ sudo networksetup -getmacaddress (

devicename|"portname

To scan for new hardware ports:

$ sudo networksetup -detectnewhardware

This command checks the computer for new network hardware and creates a default configuration for each new port.

Viewing or Changing MTU Values

All data transmitted over a network travels in data packets. The size of a packet is called a maximum transmission unit (MTU), which if too large or too small will affect performance. To change the MTU size for a port, use the networksetup tool.

To view the MTU value for a hardware port:

$ sudo networksetup -getMTU (

devicename|"portname

To list valid MTU values for a hardware port:

$ sudo networksetup -listvalidMTUrange (

To change the MTU value for a hardware port:

$ sudo networksetup -setMTU (

devicename|"portname

Viewing or Changing Media Settings

To view media settings for a port:

$ sudo networksetup -getMedia (

To list valid media settings for a port:

$ sudo networksetup -listValidMedia (

To change media settings for a port:

$ sudo networksetup -setMedia (

[option2] [...]

66 Chapter 6 Setting Network Preferences

devicename|"portname

") subtype [option1]

Managing Network Port Configurations

Network port configurations are sets of network preferences that can be assigned to a network interface and then enabled or disabled. The Network pane of System Preferences stores and displays network settings as port configurations.

Creating or Deleting Port Configurations

To list a port configuration:

$ sudo networksetup -listallnetworkservices

To create a port configuration:

$ sudo networksetup -createnetworkservice

To duplicate a port configuration:

$ sudo networksetup -duplicatenetworkservice

To rename a port configuration:

$ sudo networksetup -renamenetworkservice

To delete a port configuration:

$ sudo networksetup -removenetworkservice

Activating Port Configurations

To see if a port configuration is on:

$ sudo networksetup -getnetworkserviceenabled

configuration hardwareport

configuration newconfig

configuration newname

configuration

To enable or disable a port configuration:

$ sudo networksetup -setnetworkserviceenabled

configuration

(on|off)

Changing Configuration Precedence

To list the configuration order:

$ sudo networksetup -listnetworkserviceorder

The configurations are listed in the order that they’re tried when a network connection is established. An asterisk (*) marks an inactive configuration.

To change the order of port configurations:

$ sudo networksetup -ordernetworkservices

config1 config2 [config3

] [...]

Managing TCP/IP Settings

TCP/IP is a set of layered protocols that allow communication between computers on a high-speed network. You can use the following commands to change the TCP/IP settings of a server.

Chapter 6 Setting Network Preferences 67

Changing a Server’s IP Address

The server’s setup must reflect the network settings of the server’s primary interface. The primary interface is the topmost active connection in the Network pane of System Preferences.

When using your server as a gateway to the Internet, the server uses the primary interface to connect to the Internet. Therefore, during server setup, you configure the primary interface to use the server’s public IP address and DNS information.

The server setup program uses this information to configure other server components (such as Open Directory, Kerberos, and Password Server). As such, the IP address and the DNS settings of the primary interface and these other components must always match.

If at some point you change the IP address or DNS name of the primary interface, the system will run the changeip command within a minute or two. If not, you must register the IP address change with the server setup program.

The changeip command makes all necessary changes at once, updating the settings of all components configured during server setup, including Open Directory, Kerberos, and Password Server.

The changeip command is a python script that runs tools from the /usr/libexec/ changeip folder. Three tools are available: changeip_ds, changeip_jabber, and

changeip_mail.

The changeip_ds tool updates the following local configuration files:

Â /Library/Preferences/DirectoryService/DSLDAPv3PlugInConfig.plist Â /etc/openldap/slapd_macosxserver.conf Â /etc/hostconfig (if there is a static hostname) Â /etc/smb.conf

The changeip_ds tool also updates the following records in the local directory domain, as well as a parent directory domain, if specified:

Â AuthAuthority and HomeDirectory in user records Â Addresses and hostname in machine records Â Addresses and hostname in computer records Â Mount paths and addresses in mount records Â Addresses in LDAP and Password Server config records

The changeip_jabber tool updates the jabber configuration using serveradmin.

The changeip_mail tool updates the mailman, postfix, and imap configurations using

serveradmin.

68 Chapter 6 Setting Network Preferences

To change a server’s IP address:

1 Run the changeip tool:

$ sudo changeip [(

Parameter Description

Viewing or Changing the IP Address, Subnet Mask, or Router Address

To change a computer’s TCP/IP settings, use the serversetup and networksetup tools.

Important: Changing a computer’s IP address isn’t as simple as changing the TCP/IP

settings. You must first run the changeip tool to make sure necessary changes are made throughout the system. See “Changing a Server’s IP Address” on page 68.

To list TCP/IP settings for a configuration:

$ sudo networksetup -getinfo "configuration"

Chapter 6 Setting Network Preferences 69

For example, for built-in Ethernet, the computer responds with the following output:

$ networksetup -getinfo "Built-In Ethernet" Manual Configuration IP Address: 192.168.10.12 Subnet mask: 255.255.0.0 Router: 192.18.10.1 Ethernet Address: 1a:2b:3c:4d:5e:6f

To view TCP/IP settings for a port or device:

$ serversetup -getInfo (

devicename|"portname

To change TCP/IP settings for a port or device:

$ sudo serversetup -setInfo (

router

devicename|"portname

ipaddress subnetmask

To set manual TCP/IP information for a configuration:

$ sudo networksetup -setmanual "

configuration" ipaddress subnetmask router

To validate an IP address:

$ serversetup -isValidIPAddress

ipaddress

Displays 0 if the address is valid, 1 if it isn’t.

To validate a subnet mask:

$ serversetup -isValidSubnetMask

subnetmask

To set a configuration to use DHCP:

$ sudo networksetup -setdhcp "

configuration

" [

clientID

To set a configuration to use DHCP with a manual IP address:

$ sudo networksetup -setmanualwithdhcprouter "

configuration" ipaddress

To set a configuration to use BootP:

$ sudo networksetup -setbootp "

configuration

Viewing or Changing DNS Servers

To view and modify DNS settings, use the serversetup tool.

To view DNS servers for port en0:

$ serversetup -getDefaultDNSServer (

To change DNS servers for port en0:

$ sudo serversetup -setDefaultDNSServer (

[

server2

] [...]

To view DNS servers for a port or device:

$ serversetup -getDNSServer (

devicename|"portname

]

server1

70 Chapter 6 Setting Network Preferences

To change DNS servers for a port or device:

$ sudo serversetup -setDNSServer (

[...]

devicename|"portname

server1 [server2

]

To list DNS servers for a configuration:

$ sudo networksetup -getdnsservers "

configuration

To view DNS search domains for port en0:

$ serversetup -getDefaultDNSDomain (

devicename|"portname

To change DNS search domains for port en0:

$ sudo serversetup -setDefaultDNSDomain (

domain2

[

] [...]

devicename|"portname

domain1

To view DNS search domains for a port or device:

$ serversetup -getDNSDomain (

devicename|"portname

To change DNS search domains for a port or device:

$ sudo serversetup -setDNSDomain (

[...]

devicename|"portname

domain1 [domain2

]

To list DNS search domains for a configuration:

$ sudo networksetup -getsearchdomains "

configuration

To set DNS servers for a configuration:

$ sudo networksetup -setdnsservers "

configuration" dns1 [dns2

] [...]

To set search domains for a configuration:

$ sudo networksetup -setsearchdomains "

[...]

configuration" domain1 [domain2

]

To validate a DNS server:

$ serversetup -verifyDNSServer

server1 [server2

] [...]

To validate DNS search domains:

$ serversetup -verifyDNSDomain

domain1 [domain2

] [...]

Enabling TCP/IP

To enable or disable TCP/IP on a computer, use the serversetup tool.

To enable TCP/IP on a port:

$ serversetup -EnableTCPIP [(

If you don’t provide an interface, en0 is assumed.

To disable TCP/IP on a port:

$ serversetup -DisableTCPIP [(

If you don’t provide an interface, en0 is assumed.

Chapter 6 Setting Network Preferences 71

devicename|"portname

")]

Statically Configuring Ethernet Interfaces

You can configure your server to define an IPv4 address on an interface that does not have a live link.

To define an IPv4 address on an interface that does not have a live link:

1 Edit the network preferences file located at /Library/Preferences/SystemConfiguration/

preferences.plist.

In the preferences.plist, navigate to the block that defines the relevant interface (say, en1), look for the IPv4 configuration block, and add the IgnoreLinkStatus key.

Here is an example:

<key>Addresses</key> <array>

<string>10.12.0.7</string> </array> <key>ConfigMethod</key> <string>Manual</string> <key>IgnoreLinkStatus</key> <true/> <key>Router</key> <string>10.12.0.1</string> <key>SubnetMasks</key> <array>

</dict>

2 Save the /Library/Preferences/SystemConfiguration/preferences.plist file.

3 To activate the modified preference, restart your system or use scselect to reselect the

current service (typically named Automatic, for example, scselect Automatic).

Creating, Deleting, and Viewing VLANs

A virtual local area network (VLAN) connects devices that may be on separate physical LANs to perform and communicate as if they were on the same physical LAN. Use the

networksetup tool to configure and modify a VLAN.

To create a VLAN:

$ networksetup -createVLAN

To delete a VLAN:

$ networksetup -deleteVLAN

To list available VLANs:

$ networksetup -listVLANs

72 Chapter 6 Setting Network Preferences

name parentdevice tag

To list devices that support VLANs:

$ networksetup -listdevicesthatsupportVLAN

IEEE 802.3ad Ethernet Link Aggregation

IEEE 802.3ad provides increased bandwidth and automatic failover for the server environment.

Apple introduced the implementation of the IEEE 802.3ad Ethernet Link Aggregation standard as part of the ifconfig tool. IEEE 802.3ad is a standard for bonding or aggregating multiple Ethernet ports into one virtual interface.

The aggregated ports appear as a single IP address internally to your computer and tools and externally to other clients on the Internet. Any tool or server that relies on your IP address will continue to work seamlessly without modifications.

The advantage of aggregation is that the virtual interface provides increased bandwidth by merging the bandwidth of individual ports. The TCP connection load is then balanced across the ports.

In addition to load balancing, IEEE 802.3ad provides automatic failover in the event a port or cable fails. Traffic that was routed over the failed port is rerouted to a remaining port. This failover is transparent to the software using the connection.

Configuring a Network Interface

You can configure a network interface for TCP/IP using ifconfig. This tool is used to bring the interface up or down and set the interface IP address and subnet mask.

To add an Ethernet interface to a bond virtual device (pseudo device):

$ ifconfig

The

bond_interface_name

physical_interface

bond_interface_name

parameter is the name of the pseudo device and the

parameter is the Ethernet interface you want to associate with the

bondev

physical_interface

pseudo device (for example, en0).

If this is the first physical interface to be associated with the bond interface, the bond interface inherits the Ethernet address from the physical interface.

Physical interfaces that are added to the bond interface have their Ethernet address reprogrammed so members of the bond have the same Ethernet address.

If the physical interface is subsequently removed from the bond, a new Ethernet address is chosen from the remaining interfaces, and interfaces are reprogrammed with the new Ethernet address. If no remaining interfaces exist, the bond interface’s Ethernet address is cleared.

Chapter 6 Setting Network Preferences 73

To remove an Ethernet interface from a bond virtual device (pseudo device):

$ ifconfig

bond_interface_name

-bondev

physical_interface

The link status of the bond interface depends on the state of link aggregation. If no active partner is detected, the link status remains inactive. To monitor the IEEE 802.3ad Link Aggregation state, use the -b option.

For more information, see the ifconfig man page.

Configuring Ethernet Link Aggregation

You can also use networksetup to configure Ethernet Link Aggregation. The following commands are supported.

To see if a device can be added to a bond:

$ sudo networksetup -isBondSupported

device

To create a bond and add devices to it:

$ sudo networksetup -createBond

name [device1

] [

device2

] [...]

To delete a bond:

$ sudo networksetup -deleteBond

bond

To add a device to a bond:

$ sudo networksetup -addDeviceToBond

device bond

To remove a device from a bond:

$ sudo networksetup -removeDeviceFromBond

device bond

To list available bonds:

$ sudo networksetup -listBonds

To display a bond status:

$ sudo networksetup -showBondStatus

bond

Managing AppleTalk Settings

AppleTalk is a suite of protocols developed to implement file sharing, mail service, and printing between Apple computers. To enable or disable AppleTalk, use the

serversetup tool.

To enable AppleTalk on a port:

$ serversetup -EnableAT [(

If you don’t provide an interface, en0 is assumed.

To disable AppleTalk on a port:

$ serversetup -DisableAT [(

If you don’t provide an interface, en0 is assumed.

devicename|"portname

")]

74 Chapter 6 Setting Network Preferences

To enable AppleTalk on en0:

$ serversetup -EnableDefaultAT

To disable AppleTalk on en0:

$ serversetup -DisableDefaultAT

To make AppleTalk active or inactive for a configuration:

$ sudo networksetup -setappletalk "

configuration

" (on|off)

To verify the AppleTalk state on en0:

$ serversetup -getDefaultATActive

To see if AppleTalk is active for a configuration:

$ sudo networksetup -getappletalk

Managing SNMP Settings

Simple Network Management Protocol (SNMP) is a set of standard protocols used to manage and monitor multiplatform computer network devices.

SNMP relies on a manager/agent design where the agent provides the interface between the manager and the physical device being managed. SNMP uses five basic messages (GET, GET-NEXT, GET-RESPONSE, SET, and TRAP) to communicate between manager and agent.

Mac OS X Server v10.5 includes NET-SNMP v5.4.1.

Setting Up SNMP

To set up SNMP beyond the default configuration:

$ snmpconf -g basic_setup

This command shows you a set of configuration questions and stores the configuration information in a set of configuration files in /etc/snmp/.

You can download additional documentation from the NET-SNMP Project Home Page (www.net-snmp.org) to learn how to further customize the SNMP configuration files for your site.

WARNING: When SNMP is active, anyone with a route to the SNMP host can collect

SNMP data from it.

The default configuration of the SNMP agent ( reason and others, you must run the agent with root privileges or by using

You should use setuid with root privileges only if you understand the ramifications. If you do not, seek assistance or additional information.

snmpd) uses privileged port 161. For this

setuid.

Chapter 6 Setting Network Preferences 75

Starting SNMP

You can start SNMP in one of the following ways:

Â Using Server Admin Â Using the launchctl command

Both methods modify Net-SNMP’s launchd property list (/System/Library/ LaunchDaemons/org.net-snmp.snmpd.plist) and start the daemon (snmpd) immediately and for the next reboot.

To start SNMP using Server Admin:

1 In Server Admin, select your server.

2 Click General.

3 Enable SNMP by selecting Network Management Server (SNMP).

To start SNMP using the launchctl command:

$ sudo launchctl load -w /System/Library/LaunchDaemons/org.net-

snmp.snmpd.plist

Configuring SNMP

The configuration (conf) file for snmpd is typically in the /etc/snmp/ folder and the default configuration file is /etc/snmp/snmpd.conf.

You can customize the configuration file while the daemon is running. After the configuration is complete, restart the daemon.

To customize the /etc/snmp/snmpd.conf file, use the /usr/bin/snmpconf command. For more information about this command, see its man page.

To customize snmpd data:

1 Add an snmpd.conf file by entering:

$ sudo /usr/bin/snmpconf -i

This command asks you a series of questions.

2 Provide the appropriate answers.

3 Restart snmpd.

Because snmpd reads its configuration files at startup, you must restart snmpd for your configuration changes to take effect.

To restart snmpd:

$ sudo killall snmpd

The launchd daemon restarts snmpd.

76 Chapter 6 Setting Network Preferences

Collecting SNMP Information from the Host

To get the SNMP information you just added, enter this command from a host that has the SNMP tools installed:

$ snmpget -c

community_string hostname

system.sysLocation.0

Replace community string (or password) is public. Also, replace

community_string

with the string provided during basic setup. The default

hostname

with the name of the

target host, which could be localhost.

After running the command, you should the location you provided during basic setup, for example:

system.sysLocation.0 = server_room

The other options defined during basic setup include:

$ snmpget -c

community_string hostname

system.sysContact.0

system.sysServices.0

The final .0 indicates you are looking for the index object.

For more information, see the tutorials at net-snmp.sourceforge.net.

Another way to retrieve SNMP information is by retrieving a subtree of management values using the snmpwalk tool.

To gather SNMP information in bulk:

$ snmpwalk -c

community_string

localhost system

This lists multiple entries of SNMP data similar to the following output, where system name and location are defined in the snmp.conf file.

SNMPv2-MIB::sysName.0 - system name

SNMPv2-MIB::sysLocation.0 - system location

SNMPv2-MIB::sysUpTime.0 - time in 1/100ths of a second since the last system

start

To display all management values:

$ snmpwalk -c

community_string

localhost .1

Note: This command generates several thousand lines of output.

To view the system name:

$ snmpget -c

SNMPv2-MIB::sysName.0 = STRING: xlabxs06.example.com

community_string

localhost system.sysName.0

To view the system location:

$ snmpget -c

SNMPv2-MIB::sysLocation.0 = STRING: "server_room"

Chapter 6 Setting Network Preferences 77

community_string

localhost system.sysLocation.0

To view the system uptime:

$ snmpget -c

SNMPv2-MIB::sysUpTime.0 = Timeticks: (72239) 0:12:02.39

community_string

localhost system.sysUptime.0

To view a list of snmp man pages:

$ man -k snmp

Managing Proxy Settings

The proxy server is a component of Mac OS X Server that functions as a relay between a client and the server. This proxy server protects the network from unauthorized users and provides a more secure environment. To view or change the proxy settings, use the

networksetup tool.

Viewing or Changing FTP Proxy Settings

To view FTP proxy information for a configuration:

$ sudo networksetup -getftpproxy "

To set FTP proxy information for a configuration:

$ sudo networksetup -setftpproxy "

To view the FTP passive setting for a configuration:

$ sudo networksetup -getpassiveftp "

configuration

configuration" domain portnumber

configuration

To enable or disable FTP passive mode for a configuration:

$ sudo networksetup -setpassiveftp "

configuration

" (on|off)

To enable or disable the FTP proxy for a configuration:

$ sudo networksetup -setftpproxystate "

configuration

Viewing or Changing Web Proxy Settings

To view web proxy information for a configuration:

$ sudo networksetup -getwebproxy "

configuration

To set web proxy information for a configuration:

$ sudo networksetup -setwebproxy "

configuration" domain portnumber

To enable or disable the web proxy for a configuration:

$ sudo networksetup -setwebproxystate "

configuration

Viewing or Changing Secure Web Proxy Settings

To view secure web proxy information for a configuration:

$ sudo networksetup -getsecurewebproxy "

To set secure web proxy information for a configuration:

$ sudo networksetup -setsecurewebproxy "

configuration

configuration" domain portnumber

" (on|off)

78 Chapter 6 Setting Network Preferences

To enable or disable the secure web proxy for a configuration:

$ sudo networksetup -setsecurewebproxystate "

configuration

" (on|off)

Viewing or Changing Streaming Proxy Settings

To view streaming proxy information for a configuration:

$ sudo networksetup -getstreamingproxy "

configuration

To set streaming proxy information for a configuration:

$ sudo networksetup -setstreamingproxy "

configuration" domain portnumber

To enable or disable the streaming proxy for a configuration:

$ sudo networksetup -setstreamingproxystate "

configuration

" (on|off)

Viewing or Changing Gopher Proxy Setting

To view gopher proxy information for a configuration:

$ sudo networksetup -getgopherproxy "

To set gopher proxy information for a configuration:

$ sudo networksetup -setgopherproxy "

To enable or disable the gopher proxy for a configuration:

$ sudo networksetup -setgopherproxystate "

configuration

configuration" domain portnumber

configuration

" (on|off)

Viewing or Changing SOCKS Firewall Proxy Settings

To view SOCKS firewall proxy information for a configuration:

$ sudo networksetup -getsocksfirewallproxy "

configuration

To set SOCKS firewall proxy information for a configuration:

$ sudo networksetup -setsocksfirewallproxy "

configuration" domain portnumber

To enable or disable the SOCKS firewall proxy for a configuration:

$ sudo networksetup -setsocksfirewallproxystate "

configuration

Viewing or Changing Proxy Bypass Domains

To list proxy bypass domains for a configuration:

$ sudo networksetup -getproxybypassdomains "

To set proxy bypass domains for a configuration:

$ sudo networksetup -setproxybypassdomains "

[...]

configuration

" [

" (on|off)

domain1] domain2

Chapter 6 Setting Network Preferences 79

Managing AirPort Settings

AirPort uses wireless local area network (WLAN) technology to provide wireless communication between computers. To view or change AirPort settings, use the

networksetup tool.

To see if AirPort power is on or off:

$ sudo networksetup -getairportpower

To turn AirPort power on or off:

$ sudo networksetup -setairportpower (on|off)

To display the name of the AirPort network:

$ sudo networksetup -getairportnetwork

To join an AirPort network:

$ sudo networksetup -setairportnetwork

network [password

]

Managing Computer, Host, and Bonjour Names

These names are used by networking applications to identify a computer and are explained in the following sections.

Computer Name

The computer name is the local name of a computer. This name is typically assigned to the computer when the operating system is installed. To view or modify the computer name, use the serversetup tool.

To display the computer name:

$ sudo systemsetup -getcomputername

$ sudo networksetup -getcomputername

$ serversetup -getComputername

To change the computer name:

$ sudo systemsetup -setcomputername

$ sudo networksetup -setcomputername

$ sudo serversetup -setComputername

To validate a computer name:

$ serversetup -verifyComputername

80 Chapter 6 Setting Network Preferences

computername

Hostname

The host name is a unique name that corresponds to a unique hardware MAC address. It is the name the network uses to identify a device attached to the network. To view or modify the host name, use the serversetup tool.

To display the server’s local host name:

$ serversetup -getHostname

To change the server’s local host name:

$ sudo serversetup -setHostname

hostname

Note: You can also set and get the host name using snmpd and scutil.

Bonjour Name

Bonjour, also known as zero-configuration networking, enables automatic discovery of computers, devices, and services on IP networks. Bonjour uses industry-standard IP protocols to allow devices to discover each other without the need to enter IP addresses or configure DNS servers.

Specifically, Bonjour enables automatic IP address assignment without a DHCP server, name-to-address translation without a DNS server, and service discovery without a directory server.

To view or change the Bonjour name, use the

serversetup tool.

To display the server’s Bonjour name

$ serversetup -getBonjourname

To change the server’s Bonjour name:

$ sudo serversetup -setBonjourname

bonjourname

If the name was changed, the command displays 0.

Note: If you use Server Admin to connect to a server using its Bonjour name and change the server’s Bonjour name, you must reconnect to the server the next time you open the Server Admin application.

Chapter 6 Setting Network Preferences 81

Managing Preference Files and the Configuration Daemon

The sets of configuration information a user creates at different locations, whether in System Preferences or through the command line, are stored in the preference.plist file located in /Library/Preferences/SystemConfiguration/.

Network configuration is handled by configd, the configuration daemon. configd reads the network configuration and stores it with the current state of the computer’s networking information.

Storage is in the form of key-value pairs. The key is a description of what is being stored, and the value is the value of the information being stored.

You can view the values stored by configd at run time and monitor them using the

scutil tool. This can be especially valuable when you are debugging your network

configuration from the command line.

Invoked with no options, scutil provides a command-line interface to the data that is maintained by configd. For a list of commands you can use with scutil, enter help at the scutil prompt.

To start a scutil session (interactive mode):

$ scutil

> open

This opens a session with configd. After the session is open, you can list all keys in the data store for configd:

> list

Each item on the list is a piece of information stored by configd, sorted by type. Setup indicates information that has been read from a configuration file. State indicates information that represents the state of the computer. File indicates stored information as of the last time the configuration file was updated.

To view data in the keys, use scutil. First you get the data; then you show the data. For example:

> get State:/Network/Interface/en0/IPv4

> d.show

stores the information from the get command in a local dictionary variable

scutil

called d. You can also watch or monitor a variable so that if its state changes scutil alerts you.

To quit the

> quit

scutil session, enter quit at the prompt.

82 Chapter 6 Setting Network Preferences

You can also manage system configuration parameters scutil using the

--get and --set options. These provide a means of reporting and updating a group of

persistent system preferences, including ComputerName, LocalHostName, or HostName.

To set the hostname of a system:

$ sudo scutil --set HostName

Parameter Description

mycomputer.mac.com

The new hostname value you want to set

To get the hostname of a system:

$ scutil --get HostName

mycomputer.mac.com

For more information, see the scutil man page or enter help at the scutil prompt.

Changing Network Locations

A network location contains all network configuration settings for a specific network, such as Ethernet, AirPort, FireWire, or Bluetooth®. Each location has a separate set of network settings.

Mobile users who switch between networks have multiple locations set up on their computer and might need to switch between locations quickly. scselect allows you to access these configuration sets or locations.

To view locations:

$ scselect

The computer responds with output similar to the following:

Defined sets include: (* == current set)

* 0 (Automatic)

1 (AirPort)

2 (Home Office)

To change the location, enter the number of the location to switch to:

$ scselect 1

In this example, the network location switches to AirPort.

Chapter 6 Setting Network Preferences 83

84 Chapter 6 Setting Network Preferences

7 Working with Disks and Volumes

Use this chapter to learn the commands to initialize and test disks and volumes.

This chapter covers the commands used to manage, configure, initialize, and test disks and volumes.

Understanding Disks, Partitions, and the File System

Like UNIX, Mac OS X uses special files called device files, located in /dev, to keep track of the devices (disks, keyboards, monitors, network connections, and so on) attached to the computer.

Device files for a disk are named /dev/diskn, where n is the number of the disk. For example, a computer with one drive would have a device file called /dev/disk0. If the computer has a second drive, the computer creates a second device file called /dev/disk1, and so on.

Each drive that is divided into multiple partitions has a device file for each partition. The first partition on disk 0 is called /dev/disk0s1, the second partition is /dev/disk0s2, and so on.

Although Mac OS X Server assigns a device name to each device, the files on a device are not accessed in this way. A virtual file system is created where all files on all devices appear to exist in a single hierarchy. This sets one root folder, and every file existing on the computer is under that folder. This is known as the Hierarchical File System (HFS+). The root folder can exist anywhere on a network as a shared resource.

Mounting and Unmounting Volumes

To gain access to files on a different device, you must first mount the device. This process informs the operating system where in the folder tree you want those files to appear. The folder identified to the operating system is the mount point. Different volumes on a computer can have different file systems.

Mounting Volumes

You can use the mount tool with parameters appropriate to the type of file system you want to mount, or use one of these file-system–specific mount commands:

Â For Apple File Protocol (AppleShare) volumes: mount_afp Â For ISO 9660 volumes: mount_cd9660 Â For CD Digital Audio format (CDDA) volumes: mount_cddafs Â For Apple Hierarchical File System (HFS) volumes: mount_hfs Â For PC MS-DOS volumes: mount_msdos Â For Network File System (NFS) volumes: mount_nfs Â For Server Message Block (SMB) volumes: mount_smbfs Â For Universal Disk Format (UDF) volumes: mount_udf Â For Web-based Distributed Authoring and Versioning (WebDAV) volumes:

mount_webdav

prepares and grafts a special device or the remote node (rhost:path) to the file

mount

system tree at the point node. For more information, see the related man pages.

To view a list of mounted file systems:

$ sudo mount

To mount a network folder:

$ mount /dev/

If the mount succeeded, mount returns the value 0.

Unmounting Volumes

You can use the umount tool to unmount a volume. umount removes a special device or the remote node (rhost:path) from the file system tree at the point node.

To unmount a volume:

$ umount

If the umount succeeded, umount returns the value 0. For more information, see the

umount man page.

Displaying Disk Information

Use the df tool in /bin to view free disk space and to identify:

Â What your current disk partitions are Â How much space each partition uses Â Which block each partition starts on Â Which device file is associated with each partition Â Where each partition is mounted

86 Chapter 7 Working with Disks and Volumes

To view disk information:

$ df

The computer responds with output similar to the following:

Filesystem 512-blocks Used Avail Capacity Mounted on /dev/disk0s3 156039264 26138984 129388280 17% / devfs 193 193 0 100% /dev fdesc 2 2 0 100% /dev <volfs> 1024 1024 0 100% /.vol automount -nsl [170] 0 0 0 100% /Network automount -fstab [174] 0 0 0 100% /automount/

Servers

automount -static [174] 0 0 0 100% /automount/

static

The -l option restricts reporting to local drives only. The -k option displays sizes in kilobyte format.

Each line in the output refers to a different partition:

Â The first column tells you the device file associated with that partition. Â The second column displays the capacity of the partition followed by used and

available space on the volume.

Â The last column tells you where the partition is mounted.

Monitoring Disk Space

You can monitor the amount of free space on disks and take predefined actions when thresholds are exceeded.

When you need more vigilant monitoring of disk space than the log rolling scripts provide, you can use the diskspacemonitor tool. It lets you monitor disk space and take action more frequently than once a day when disk space is critically low, and gives you the opportunity to provide your own action scripts. By default, diskspacemonitor is disabled.

To enable diskspacemonitor:

$ sudo diskspacemonitor on.

You might be prompted for your password.

For more information, see the diskspacemonitor man page.

When enabled, when to execute alert and recovery scripts for reclaiming disk space.

Chapter 7 Working with Disks and Volumes 87

diskspacemonitor uses information in a configuration file to determine

The configuration file is /etc/diskspacemonitor/diskspacemonitor.conf. You can specify how often you want to monitor disk space, and the thresholds to use for determining when to take the actions in the scripts.

By default, disks are checked every 10 minutes, an alert script is executed when disks are 75% full, and a recovery script is executed when disks are 85% full.

To edit the configuration file, log in to the server as an administrator and use a text editor to open the file. For additional information, see the comments in the file.

By default, two predefined action scripts are executed when the thresholds are reached.

The default alert script is /etc/diskspacemonitor/action/alert. It runs in accord with instructions in the configuration file /etc/diskspacemonitor/alert.conf. It sends mail to recipients you specify.

The default recovery script is /etc/diskspacemonitor/action/recover. It runs in accord with instructions in the configuration file /etc/diskspacemonitor/recover.conf.

For more information, see the comments in the script and configuration files.

To provide your own alert and recovery scripts, put your alert script in /etc/diskspacemonitor/action/alert.local and your recovery script in /etc/ diskspacemonitor/action/recovery.local. Your scripts are executed before the default scripts when the thresholds are reached.

To configure the scripts on a server from a remote Mac OS X computer, open a Terminal window and log in to the remote computer using SSH.

Reclaiming Disk Space Using Log-Rolling Scripts

The following scripts are executed to reclaim space used on your server: Â The script /etc/periodic/daily/600.daily.server runs daily. Its configuration file is

/etc/diskspacemonitor/daily.server.conf.

Â The script /etc/periodic/weekly/600.weekly.server runs weekly, but is empty.

Its configuration file is /etc/diskspacemonitor/weekly.server.conf.

Â The script /etc/periodic/monthly/600.monthly.server runs monthly, but is empty.

Its configuration file is /etc/diskspacemonitor/monthly.server.conf.

88 Chapter 7 Working with Disks and Volumes

These scripts reclaim space used by log files generated by the following services:

Â Apple file service Â Windows service Â Web service Â Web performance cache Â Mail service Â Print service

As configured, the scripts specify actions that complement the log file management performed by the services listed above, so don’t modify them. Log in as an administrator and use a text editor to define thresholds in the configuration files that determine when actions are taken. Thresholds include:

Â The number of megabytes a log file must contain before its space is reclaimed. Â The number of days since a log file’s last modification that need to pass before its

space is reclaimed.

Specify one or both thresholds. The actions are taken when either threshold is exceeded.

You can specify several additional parameters. For information about the parameters and how to set them, see comments in the configuration files.

The scripts ignore log files except those for which at least one threshold is present in the configuration file.

To configure the scripts on a server from a remote Mac OS X computer, open a Terminal window and log in to the remote server using SSH. Then, open a text editor and edit the scripts.

You can also use the diskspacemonitor tool to reclaim disk space.

Using the diskutil Tool

You can use diskutil to erase, modify, verify, and repair disks. This command provides functionality that overlaps the functionality of pdisk, newfs_hfs, and disktool.

For example, you can use diskutil and pdisk to partition a disk. However, unlike

pdisk, which lets you partition tables at their most basic level by setting the base

address and partition length in blocks, diskutil lets you partition a disk automatically by calculating the base address and the partition length in blocks based on the partition size you specify.

The

diskutil tool allows you to perform the following actions on a disk:

Chapter 7 Working with Disks and Volumes 89

To list the disks known and available on the computer:

$ diskutil list

If your system is an Xserve computer, you can use this command to determine which drive is in which bay.

To erase and repartition a disk:

$ diskutil partitionDisk

part1Size

Parameter Description

disk

numberOfPartitions

part1Format

part1Name

part1Size

> <

part2Format part2Name part2Size

disk numberOfPartitions <part1Format part1Name

> …

Device name (such as disk0).

Number of partitions.

The format of the volume. The valid formats or filesystem names available in Disk Utility are:

Â “Journaled HFS+”—corresponds to Mac OS Extended (Journaled)

and is the default and recommended startup volume format.

Â HFS+—corresponds to Mac OS Extended. Â “Case-sensitive Journaled HFS+”—corresponds to Mac OS

Extended (Case-sensitive, Journaled). This format is available for the “erase and install” option for local installations, is not available for remotely controlled installations, and might have issues with third-party applications.

Â “Case-sensitive HFS+”—corresponds to Mac OS Extended (Case-

sensitive).

Â “MS-DOS FAT32”—corresponds to MS-DOS (FAT). Â Swap—corresponds to Free Space. Â ZFS—corresponds to Zettabyte File System (ZFS).

Other valid formats are HFS, “MS-DOS FAT16”, MS-DOS, “MS-DOS FAT12”, Linux, and UFS. UFS is not a supported boot volume format.

The available formats for erasing, partitioning, and creating RAID sets are specified in a plist file for each filesystem (/System/Library/ Filesystems/fs_name.fs/Contents/Info.plist, where fs_name is an acronym in lower case representing the filesystem).

The name of the partition.

The size of the partition in bytes (such as 98187445B), kilobytes (such as 810240K), megabytes (such as 4024M), gigabytes (such as 4G), or terabytes (such as 1T).

Because HFS+ is case preserving but not case sensitive, there might be times when you would want to set the file system to be case sensitive. Use the diskutil tool to format a drive for case-sensitive HFS+.

To mount a volume:

$ diskutil mountDisk

Parameter Description

diskvol

90 Chapter 7 Working with Disks and Volumes

diskvol

Device name

To get mount info about a partition:

$ diskutil info

Parameter Description

diskvol

Device name (for example, disk0s9) for the partition

This command tells you the device file that corresponds to the mounted partition (or device name) you specify.

To format a Mac OS Extended volume as case-sensitive HFS+:

$ sudo diskutil eraseVolume "Case-sensitive HFS+"

Parameter Description

newvolname

volume

The name given to the reformatted, case-sensitive volume

The path to the existing volume to be reformatted For example:

/Volumes/HFSPlus

newvolname volume

For more options and information about repairing and modifying disks, see the

diskutil man page.

Using the pdisk, disklabel, and newfs Tools

Disk partitions are subdivisions of a disk that you apply operating-system-specific formatting to.

Partitioning a Disk

You can use pdisk, located in /usr/sbin, to initialize the disk, create partitions, and delete partitions. The pdisk tool is menu-driven, which means that when it is launched, you are prompted to enter a pdisk command. You can find the commands by entering

? at the pdisk prompt.

The following are some of the more useful commands:

Command Description

L Lists the partition maps of all drives. pdisk lists all partitions for a disk—even the

unmountable partitions, such as the partition containing the partition map.

e Edits the partition map of the named device. To edit a partition map, use the raw

device file as the argument.

Chapter 7 Working with Disks and Volumes 91

When you start editing a device, the pdisk options change. Enter ? at the pdisk prompt to see the editing commands. The following are some of the more important ones:

Command Description

p Prints the partition map for the current device.

i Initializes the partition map for the current device.

C Creates a partition. There are two partition types: Apple_HFS and Apple_UFS.

w Writes the modifications to the partition map on-disk. Before that, edits and

modifications are only in memory and are not yet implemented.

pdisk does not support the Intel/DOS partitioning scheme supported by fdisk. For

more information about DOS partitions, see the fdisk man page.

After a partition is created on a device, the partition must be formatted before the computer can store data on the device. Formatting a disk partition creates the volume and sets the file system.

Labeling a Disk

After a disk is formatted, it must be labeled. The disklabel tool manipulates Apple Label partition metadata. Apple Label partitions allow for a disk device to have a consistent name, ownership, and permissions across reboots, even though it uses a dynamic pseudo file system for /dev.

The Apple Label partition uses a set of metadata (as a plist) in a reserved area of the partition. This metadata describes the owner, name, and so forth.

To create a disk label for a device with 1 MB of metadata area, owned by Anne, with a device name of Fred, and writable by Anne:

$ disklabel -create /dev/rdisk1s1 -msize=1M owner-uid=anne dev-devname=anne

name=anne owner-mode=0644

The following example prints the key-value pairs from the previous example:

$ disklabel -properties /dev/rdisk1s1

For more information about creating disk labels, see the disklabel man page.

Formatting a Disk

To create a volume, use newfs, located in /sbin. newfs builds a file system on the specified special device, basing its defaults on the information in the disk label.

There are many parameters you can set when formatting disks, such as block and clump size, b-tree attribute, and catalog node sizes.

Important: Take extreme care to ensure a successful format when modifying the

settings beyond the default.

92 Chapter 7 Working with Disks and Volumes

Before running newfs, label the disk using the disklabel tool.

To format a disk:

$ newfs

For more information, see the newfs man page.

To format a disk to HFS+:

m Use the newfs_hfs tool in /sbin:

$ newfs_hfs

For more information, see the newfs_hfs man page.

Troubleshooting Disk Problems

To verify the physical condition and file system integrity of a volume, use the diskutil or fsck tool (fsck_hfs for HFS volumes). For more information, see the related man pages.

Managing Disk Journaling

A robust file system journaling feature is available to enhance the availability and fault tolerance of servers and server-attached storage devices.

Journaling protects the integrity of the Mac OS Extended (HFS+) file system in the event of an unplanned shutdown or power failure, and maximizes uptime by expediting repairs to the affected volumes when the computer restarts.

Determining if Journaling Is Enabled

To see if journaling is enabled on a volume, use the mount tool.

To see if journaling is enabled:

$ mount

Look for journaled in the attributes in parentheses following a volume. For example:

/dev/disk0s9 on / (local, journaled)

Enabling Journaling for a Volume

To enable journaling on a volume without affecting files on the volume, use the

diskutil tool.

Important: Always check the volume for disk errors using the fsck_hfs tool before you

enable journaling.

Chapter 7 Working with Disks and Volumes 93

To enable journaling:

$ diskutil enableJournal

Parameter Description

volume

The volume name or device name of the volume

The following example shows journaling being enabled on volume /dev/disk0s10.

$ mount

/dev/disk0s9 on / (local, journaled) /dev/disk0s10 on /Volumes/OS 9.2.2 (local) $ sudo fsck_hfs /dev/disk0s10/ ** /dev/rdisk0s10 ** Checking HFS plus volume. ** Checking extents overflow file. ** Checking Catalog file. ** Checking Catalog hierarchy. ** Checking volume bitmap. ** Checking volume information. ** The volume OS 9.2.2 appears to be OK. $ diskutil enableJournal /dev/disk0s10 Allocated 8192K for journal file. Journaling has been enabled on /dev/disk0s10 $ mount /dev/disk0s9 on / (local, journaled) /dev/disk0s10 on /Volumes/OS 9.2.2 (local, journaled)

Enabling Journaling When You Erase a Disk

To set up and enable journaling when you erase a disk, use the newfs_hfs tool.

To enable journaling when erasing a disk:

$ newfs_hfs -J -v

Parameter Description

volname

device

volname device

The name you want the new disk volume to have

The device name of the disk

Disabling Journaling

To disable journaling:

$ diskutil disableJournal

Parameter Description

volume

94 Chapter 7 Working with Disks and Volumes

volume

The volume name or device name of the volume

Understanding Spotlight Technology

Spotlight is a desktop search technology that combines metadata-indexing with content-indexing that’s optimized for Mac OS X.

When a file is added, moved, deleted, or modified, the file system notifies the Spotlight engine. The Spotlight engine then updates its index, known as the Spotlight store. The Spotlight engine then updates applications that use Spotlight, and changes are reflected dynamically to the user.

The Spotlight store retains information in two indexes, one for metadata and the other for content. Each index is created on a per-volume basis, which means each disk or partition carries its own set of indexes for the information about that volume.

Enabling and Disabling Spotlight

By default, the value of the spotlight parameter in the /etc/hostconfig file is set to

-YES-, which means Spotlight is enabled on your Mac OS X Server computer.

To disable Spotlight on your server:

1 Open the /etc/hostconfig file for editing with root privileges using your favorite editor.

For example:

$ sudo pico /etc/hostconfig

2 Change the value of the spotlight parameter to -NO-.

You can set the value of the spotlight parameter to -NO- as follows:

$ sudo /System/Library/ServerSetup/serversetup -setAutoStartSpotlight 0

3 Restart your server.

To enable Spotlight on your server:

1 Open /etc/hostconfig for editing with root privileges.

2 Change the value of the spotlight parameter to -YES-.

You can set the value of the SPOTLIGHT parameter to -YES- as follows:

$ sudo /System/Library/ServerSetup/serversetup -setAutoStartSpotlight 1

3 Restart your server.

Performing Spotlight Searches

Mac OS X provides the ability to view the metadata of a file and perform Spotlight searches from the command line.

To view a file’s Spotlight metadata, use the mdls tool. This tool, similar to the ls tool, lists metadata attributes for a file.

Chapter 7 Working with Disks and Volumes 95

To view the metadata of a file:

$ mdls

filename

The computer responds with something similar to the following output:

filename> ------------kMDItemAttributeChangeDate = 1970-01-01 00:43:07 -0600 kMDItemFSContentChangeDate = 2005-10-03 22:04:19 -0500 kMDItemFSCreationDate = 2005-10-03 22:04:19 -0500 kMDItemFSCreatorCode = 0 kMDItemFSFinderFlags = 16384 kMDItemFSInvisible = 1 kMDItemFSIsExtensionHidden = 0 kMDItemFSLabel = 0 kMDItemFSName = " kMDItemFSNodeCount = 0 kMDItemFSOwnerGroupID = 0 kMDItemFSOwnerUserID = 0 kMDItemFSSize = 4330232 kMDItemFSTypeCode = 0 kMDItemID = 634516 kMDItemLastUsedDate = 2005-10-03 21:04:19 -0500 kMDItemUsedDates = (2005-10-03 21:04:19 -0500)

filename

To perform a Spotlight search using the mdfind tool:

$ mdfind “kMDItemAcquisitionModel ==’Canon Powershot S45’” /Users/anne/Documents/vacation1.jpg /Users/anne/Documents/vacation2.jpg /Users/anne/Documents/vacation3.jpg /Users/anne/Documents/vacation4.jpg

Controlling Spotlight Indexing

By default, indexing of volumes in Mac OS X Server is disabled. However, you can use the mdutil tool to enable or disable indexing on a volume.

To enable indexing on a volume:

Run the mdutil tool with root privileges and set the indexing status to on.

$ sudo mdutil -i on

To disable indexing on a volume:

Run the mdutil tool with root privileges and set the indexing status to off.

$ sudo mdutil -i off

For more information, see the mdutil man page.

96 Chapter 7 Working with Disks and Volumes

volume

Managing RAID Volumes

In addition to standard drive management options, you can use diskutil to manage software RAID volumes.

To create a RAID set:

$ diskutil createRAID

Parameter Description

type

setName

volType

disks

To get a list of disks available to add to a RAID set:

$ diskutil list

Similarly, you can remove a RAID set with the diskutil destroyRAID command.

To view a list of available RAID sets:

$ diskutil checkRAID

Parameter Description

device

type setName volType disks

Mirror or stripe

Name of the new RAID volume

HFS, HFS+, UFS, or BootableHFS

List of device names for members of the RAID set

device

Device file

To create an unpaired mirrored RAID set from a single file system disk:

$ diskutil enableRAID

Parameter Description

mirror

device

mirror device

Name of the mirror RAID set

Device file

To repair a failed mirror:

$ diskutil repairMirror

Parameter Description

device

slicenumber

fromDisk

toDisk

device slicenumber fromDisk toDisk

Device file

The slice number to replace

The mirror source

The repaired mirror destination

Note: Xsan RAID volumes have their own commands, described in an appendix of the Xsan Administrators guide. For information about the

megaraid tool (used for

managing a PCI RAID card), see the appendix.

Chapter 7 Working with Disks and Volumes 97

Imaging and Cloning Volumes Using ASR

You can use Apple Software Restore (ASR) to copy a disk image onto a volume or to prepare disk images with checksum information for faster copies. ASR can perform file copies, in which individual files are restored to a volume unless an identical file exists there, and block copies, which restores entire disk images.

The asr tool doesn’t create the disk images. You use hdiutil to create disk images from volumes or folders.

You must run ASR with root privileges. You cannot use ASR on read or write disk images.

To image a boot volume:

1 Install and configure Mac OS X on the volume.

2 Restart from a different volume.

3 Make sure the volume you’re imaging has permissions enabled.

Use the following to verify permissions:

$ diskutil verifyPermissions [mount point|disk identifier|device node]

4 Use hditutil to make a read-write disk image of the volume.

See “Using hdiutil with System Images” on page 183.

5 Mount the disk image.

6 Remove cache files, host-specific preferences, and virtual memory files.

For examples of what files to remove, see the asr man page.

7 Unmount the volume and convert the read-write image to a read-only compressed

image:

$ hdiutil convert -format UDZO

8 Prepare the image for duplication by adding checksum information:

$ sudo asr -imagescan

compressedimage

pathtoimage

-o

compressedimage

To restore a volume from an image:

$ sudo asr -source

compressedimage

For more information, see the asr man page.

98 Chapter 7 Working with Disks and Volumes

-target

targetvolume

-erase

8 Managing User and Group

Accounts

Use this chapter to learn the commands to set up and manage user and group accounts.

With Mac OS X Server, you can quickly create and administer accounts for users and groups. Several command-line tools are available to facilitate working with the directory domains that hold these accounts.

User, Group, Computer, and Computer Group Accounts

You set up four kinds of accounts with Workgroup Manager: user accounts, group accounts, computer accounts, and computer group accounts.

When you define a user’s account, you specify the information needed to prove the user’s identity: user name, password, and user identification number (user ID). Other information in a user’s account is needed by various services to determine what the user is authorized to do and to personalize the user’s environment.

Along with accounts you create, Mac OS X Server has predefined user and group accounts, some of which are reserved for use by Mac OS X.

Most users have an individual account used to authenticate them and control their access to services. When you want to personalize a user’s environment, you define user, group, or computer preferences for that user.

The term managed client or managed user designates a user who has administratorcontrolled preferences associated with his or her account. When a managed user logs in, the preferences that take effect are a combination of the user’s preferences and preferences set up for any workgroup or computer list he or she belongs to.

Administering and Creating User Accounts

This section describes how to administer user accounts stored in directory domains.

A user account stores data that Mac OS X Server needs to validate the user’s identity and provide services for the user.

User and group accounts, as well as computer and computer group accounts, can be stored in any Open Directory domain accessible from any Mac OS X computer. A directory domain can reside on a Mac OS X computer (for example, the LDAP folder of an Open Directory master or another read/write directory domain) or it can reside on a non-Apple server (for example, a non-Apple LDAP or Active Directory server).

Creating a Local Administrator User Account for a Server

Users with server or directory domain administration privileges are known as administrators. An administrator can be a server administrator, domain administrator, or both. Server administrator privileges determine whether a user can view information about or change the settings of a specific server.

Domain administrator privileges determine the extent to which the user can view or change account settings for users, groups, computers, and computer groups in the directory domain.

To create local administrator users for a server, use the

serversetup tool is located in /System/Library/ServerSetup/ and is not in the local

serversetup tool. The

path, so you must provide the path to it. You must also run it with root privileges.

To create nonadministrator users, see “Creating a Nonadministrator User Account” on page 102.

To create administrator users in a network directory domain, see “Creating a Domain Administrator User Account” on page 101.

To create a local administrator user account:

$ sudo /System/Library/ServerSetup/serversetup -createUser

shortname password

fullname

Enter the name, short name, and password in the order shown. If the full name includes spaces, enter it in quotes.

The command displays a 0 if successful, or a 1 if the full name or short name is already in use.

100 Chapter 8 Managing User and Group Accounts

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

2 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

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

Viewing or Changing the Computer Name

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