Apple MAC OS X SERVER User Manual

Mac OS X Server

Command-Line Administration

For Version 10.4 or Later Second Edition

Apple Computer, 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 Computer, Inc., is not responsible for printing or clerical errors.

Apple 1 Infinite Loop Cupertino CA 95014-2084 www.apple.com

The Apple logo is a trademark of Apple Computer, 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, AppleShare, AppleTalk, Mac, Macintosh, QuickTime, Xgrid, and Xserve are trademarks of Apple Computer, Inc., registered in the U.S. and other countries. Finder is a trademark of Apple Computer, Inc.

Adobe and PostScript are trademarks of Adobe Systems Incorporated.

UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd. Apache is a registered trademark of the Apache Software Foundation, and is used with permission.

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 or use of these products.

019-0635/2-15-2006

Preface 15 About This Guide

Using This Guide

Understanding Notation Conventions

16 16 16 17 17 18 18

Summary Commands and Other Terminal Text Command Parameters and Options Default Settings

Commands Requiring Root Privileges Getting Documentation Updates Getting Additional Information

Chapter 1 21 Executing Commands

Opening Terminal

Specifying Files and Folders

Modifying Flow Control

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

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 Within 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 Secure Shell

31 32 33

How SSH Works Password-Less Logins Using SSH Keys Updating SSH Key Fingerprints

34 34

35 35 36

What is an SSH Man-in-the-Middle Attack? Controlling Access to SSH Service

Connecting to a Remote Computer

Using SSH Using Telnet

Chapter 3 37 Installing Server Software and Finishing Basic Setup

Installing Server Software

38 39 39

40 40 40

43 43 47 47 48 48 48 49 49 50

Locating Computers for Installation Specifying the Target Computer Volume Preparing the Target Volume for a Clean Installation Installing from Multiple CDs 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 53 Restarting or Shutting Down a Computer

Restarting a Computer

53 54 54 54

Automatic Restart Changing a Remote Computer’s Startup Disk Shutting Down a Computer Manipulating Open Firmware NVRAM Variables Monitoring and Restarting Critical Services

Chapter 5 57 Setting General System Preferences

Viewing or Changing the Computer Name

Viewing or Changing the Date and Time

58 58 58 58 59

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 the Energy Saver Settings

Contents

59 60 60

61 61 61 61

Viewing or Changing Sleep Settings

Viewing or Changing Automatic Restart Settings Changing the Power Management Settings Viewing or Changing the Startup Disk Settings Viewing or Changing the Sharing Settings

Viewing or Changing Remote Login Settings

Viewing or Changing Apple Event Response Viewing or Changing the International Settings Viewing and Changing the Login Settings

Chapter 6 63 Setting Network Preferences

Configuring Network Interfaces

Managing Network Interface Information

64 64

65 65 65 65

65 66 66

69 70 70 70

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 IP Address, Subnet Mask, or Router Address Viewing or Changing DNS Servers Enabling TCP/IP Working with VLANs

IEEE 802.3ad Ethernet Link Aggregation Managing AppleTalk Settings Managing SNMP Settings

Installing SNMP

Starting SNMP

Configuring SNMP

Collecting SNMP Information from the Host Managing Proxy Settings

Viewing or Changing FTP Proxy Settings

Viewing or Changing Web Proxy Settings

Viewing or Changing Secure Web Proxy Settings

Viewing or Changing Streaming Proxy Settings

Viewing or Changing Gopher Proxy Settings

Viewing or Changing SOCKS Firewall Proxy Settings

Viewing or Changing Proxy Bypass Domains Managing AirPort Settings Managing the Computer, Host, and Bonjour Names

Contents

79 80 80

Computer Name Hostname

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

Chapter 7 83 Working with Disks and Volumes

Understanding Disks, Partitions, and the File System

Mounting and Unmounting Volumes

84 84

Mounting Volumes

Unmounting Volumes

85 Displaying Disk Information 85 Monitoring Disk Space

86 Reclaiming Disk Space Using Log-Rolling Scripts

87 Erasing, Modifying, Verifying, and Repairing Disks 89 Partitioning and Formatting Disks 89 Partitioning a Disk 90 Labeling a Disk 90 Formatting a Disk 90 Checking for Disk Problems

91 Managing Disk Journaling 91 Checking to See If Journaling is Enabled

91 Enabling Journaling for an Existing Volume 92 Enabling Journaling When You Erase a Disk 92 Disabling Journaling 92 Understanding Spotlight Technology 92 Enabling and Disabling Spotlight 93 Performing Spotlight Searches

94 Controlling Spotlight Indexing 94 Managing RAID Volumes

95 Imaging and Cloning Volumes Using ASR

Chapter 8 97 Working with Users and Groups

97 Understanding Accounts

98 Administering and Creating Accounts 98 Creating a Local Administrator User Account for a Server

99 Creating a Domain Administrator User Account 10 0 Checking a User’s Administrator Privileges 10 0 Creating a Nonadministrator User Account 10 3 Retreiving a User’s GUID 10 3 Removing a User Account 10 4 Revoking a User’s Right to Access His or Her Account 10 6 Checking a Server User’s Name, UID, or Password

Contents

10 7 Modifying a User Account 10 8 Creating a Mobile 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 6 Creating and Deleting Nested Group 117 Editing Group Records 11 8 Creating a Group Folder 11 8 Viewing the Workgroup a User Selects at Login 11 9 Importing Users and Groups

12 0 Creating a Character-Delimited User Import File 12 3 Setting Permissions 12 3 Viewing Permissions 12 4 Setting the umask for Individual Users 12 5 Changing Permissions 12 6 Changing the Owner 12 6 Changing the Group 12 6 Securing System Accounts 12 6 Securing Initial System Accounts 12 7 Securing the Root Account 12 7 Restricting Use of the sudo Tool 12 8 Securing Single-User Boot 12 9 Setting Password Policy

131 Finding User Account Information

Chapter 9 133 Working with File Services

13 3 Managing Share Points 13 4 Listing Share Points 13 4 Creating a Share Point 13 5 Modifying a Share Point 13 6 Disabling a Share Point 13 6 Managing the AFP Service 13 6 Starting and Stopping AFP Service 13 6 Checking AFP Service Status 13 6 Viewing AFP Settings 13 7 Changing AFP Settings 13 7 List of AFP Settings 14 0 List of AFP serveradmin Commands

141 Listing Connected Users

14 2 Sending a Message to AFP Users

Contents 7

14 2 Disconnecting AFP Users 14 3 Canceling a User Disconnect 14 4 Listing AFP Service Statistics 14 5 Viewing AFP Log Files 14 6 Managing the NFS Service 14 6 Starting and Stopping NFS Service 14 6 Checking NFS Service Status 14 6 Viewing NFS Service Settings 14 6 Changing NFS Service Settings 14 7 Managing the FTP Service 14 7 Starting FTP Service 14 7 Stopping FTP Service 14 7 Checking FTP Service Status 14 7 Viewing FTP Service Settings 14 8 Changing FTP Service Settings 14 8 List of FTP Service Settings 15 0 List of FTP serveradmin Commands 15 0 Viewing the FTP Transfer Log 15 0 Checking for Connected FTP Users

151 Managing the SMB/CIFS Service 151 Starting and Stopping SMB/CIFS Service 151 Checking SMB/CIFS Service Status

151 Viewing SMB/CIFS Service Settings 15 2 Changing SMB/CIFS Service Settings 15 2 List of SMB/CIFS Service Settings 15 5 List of SMB/CIFS serveradmin Commands 15 5 Listing SMB/CIFS Users 15 6 Disconnecting SMB/CIFS Users 15 6 Listing SMB/CIFS Service Statistics 157 Updating Share Point Information 157 Viewing SMB/CIFS Service Logs 157 Managing ACLs 15 8 Using chmod to Modify ACLs

Chapter 10 161 Working with the Print Service

161 Understanding the Print Process 162 Performing Print Service Tasks 162 Starting and Stopping Print Service 163 Checking the Status of Print Service 163 Viewing Print Service Settings 163 Changing Print Service Settings 166 Managing the Print Service 167 Listing Queues

8 Contents

167 Pausing a Queue 167 Listing Jobs and Job Information 168 Holding a Job 169 Viewing Print Service Log Files 169 Viewing Cover Pages

Chapter 11 171 Working with NetBoot Service and System Images

171 Understanding the NetBoot Service

171 Starting and Stopping NetBoot Service 17 2 Checking NetBoot Service Status 17 2 Viewing NetBoot Settings 17 2 Changing NetBoot Settings 17 3 Changing General Netboot Service Settings 17 3 Storage Record Array

174 Filters Record Array

174 Image Record Array 17 5 Port Record Array 17 6 Working with System Images 17 6 Updating an Image 17 6 Booting from an Image 17 6 Using hdiutil to Work with System Images 17 7 Using asr to Restore System Images 17 7 Imaging Multiple Clients Using Multicast asr 17 8 Choosing a Boot Device Using systemsetup

Chapter 12 179 Working with the Mail Service

17 9 Understanding the Mail Service 17 9 Postfix Agent 18 0 Cyrus 18 0 Mailman

181 Managing the Mail Service

181 Starting and Stopping Mail Service

181 Checking the Status of Mail Service

181 Viewing Mail Service Settings

181 Changing Mail Service Settings 18 2 Mail Service Settings 19 4 Mail serveradmin Commands 19 4 Listing Mail Service Statistics 19 5 Viewing the Mail Service Logs 19 6 Backing Up the Mail Files 19 7 Reconstructing the Mail Database 19 8 Setting Up SSL for Mail Service 19 8 Generating a CSR and Creating a Keychain

Contents 9

200 Obtaining an SSL Certificate 200 Importing an SSL Certificate into the Keychain 200 Accessing the Server Certificates

201 Creating a Password File

202 Configuring Mailboxes 202 Enabling Sieve Scripting 203 Enabling Sieve Support

Chapter 13 207 Working with Web Technologies

207 Understanding Web Technology 208 Managing the Web Service 208 Starting and Stopping Web Service 208 Checking Web Service Status 208 Viewing Web Settings 209 Changing Web Settings 209 serveradmin and Apache Settings 209 Changing Settings Using serveradmin

210 Web serveradmin Commands

210 Listing Hosted Sites

210 Viewing Service Logs

210 Viewing Service Statistics

212 Example Script for Adding a Website

213 Tuning the Server Performance

214 Working with Application Servers and Java

214 Apache Tomcat

214 JBoss Server

215 MySQL Database

Chapter 14 217 Working with Network Services

217 Managing Network Services

218 Managing the DHCP Service

218 Starting and Stopping DHCP Service

218 Checking the Status of DHCP Service

218 Viewing DHCP Service Settings

219 Changing DHCP Service Settings

219 DHCP Service Settings

220 DHCP Subnet Settings Array 222 Adding a DHCP Subnet 223 Adding a DHCP Static Map 224 List of DHCP serveradmin Commands 224 Viewing the DHCP Service Log 225 Managing the DNS Service 225 Starting and Stopping the DNS Service

10 Contents

225 Checking the Status of DNS Service 225 Viewing DNS Service Settings 226 Changing DNS Service Settings 226 DNS Service Settings 226 List of DNS serveradmin Commands 226 Viewing the DNS Service Log 226 Listing DNS Service Statistics 227 Configuring IP Forwarding 227 Managing the Firewall Service 228 Firewall Startup 228 Starting and Stopping Firewall Service 228 Checking the Status of Firewall Service 228 Viewing Firewall Service Settings 229 Changing Firewall Service Settings 229 Firewall Service Settings 230 Defining Firewall Rules

233 ipfilter Rules Array 233 Firewall serveradmin Commands

234 Viewing Firewall Service Log 234 Using Firewall Service to Simulate Network Activity 234 Managing the NAT Service

235 Starting and Stopping NAT Service 235 Checking the Status of NAT Service 235 Viewing NAT Service Settings 235 Changing NAT Service Settings

236 NAT Service Settings 236 NAT serveradmin Commands

237 Port Mapping 237 Viewing the NAT Service Log

238 Managing the VPN Service 238 Starting and Stopping VPN Service 238 Checking the Status of VPN Service 238 Viewing VPN Service Settings 239 Changing VPN Service Settings 239 List of VPN Service Settings 242 List of VPN serveradmin Commands 242 Viewing the VPN Service Log 243 Site-to-Site VPN 243 Configuring Site-to-Site VPN 244 Adding a VPN Keyagent User 245 Setting Up IP Failover 245 IP Failover Prerequisites 245 IP Failover Operation

Contents 11

246 Enabling IP Failover 247 Configuring IP Failover 248 Enabling PPP Dial-In 248 Restoring the Default Configuration for Server Services

Chapter 15 251 Working with Open Directory

251 Understanding Open Directory 251 Using General Directory Tools 251 Testing Your Open Directory Configuration 252 Modifying a Directory Domain 252 Testing Open Directory Plug-ins 252 Registering URLs with SLP 252 Changing Open Directory Service Settings 253 Managing OpenLDAP 253 Configuring LDAP

254 Configuring slapd and slurpd Daemons

255 Idle Rebinding Options 255 Searching the LDAP Server

258 Using LDIF Files 259 Additional Information About LDAP 259 Managing NetInfo 259 Configuring NetInfo 260 Managing Open Directory Passwords 260 Open Directory Password Server

261 Kerberos and Apple Single Sign-On 263 Using Directory Service Tools 263 Operating on Directory Service Directory Domains

264 Finding Network Information 264 Manipulating a Single Named Group Record 265 Adding or Removing LDAP Server Configurations 265 Configuring the Active Directory Plug-In

Chapter 16 267 Working with QuickTime Streaming Server

267 Understanding QuickTime Streaming Server 267 Performing QTSS Service Tasks

268 Starting and Stopping the QTSS Service 268 Checking QTSS Service Status 268 Viewing QTSS Settings 268 Changing QTSS Settings

269 QTSS Settings 272 Managing QTSS 272 Listing Current Connections 273 Viewing QTSS Service Statistics

12 Contents

274 Viewing Service Logs 274 Forcing QTSS to Reread its Preferences 275 Preparing Older Home Folders for User Streaming 275 Configuring Streaming Security 275 Resetting the Streaming Server Admin User Name and Password 276 Controlling Access to Streamed Media 276 Creating an Access File 278 Accessing Protected Media 278 Adding User Accounts and Passwords 278 Adding or Deleting Groups 278 Making Changes to the User or Group File 279 Manipulating QuickTime and MP4 Movies 279 Creating Reference Movies

Chapter 17 281 Configuring System Logging

281 Logging System Events 281 Configuring the Log File

281 Configuring Your System Logging 282 Local Logging 283 Remote Logging

Appendix 285 PCI RAID Card Command Reference

Glossary 289

Index 299

Contents 13

14 Contents

About This Guide

This guide describes Mac OS X Servers command-line interface tools and commands, including the syntax, purpose, and parameters, as well as examples of usage and any output that they generate.

This guide 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 commonly 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.

Preface

Darwin maintains most of the functionality of 4.4BSD commands. While some commands are modified to function differently, most of the commands are either kept as is, or their functionality has been extended to support Apple-specific technologies.

This guide focuses on commands developed by Apple to allow administrators to perform funtions available in the graphical interface from the command line. The guide also highlights BSD commands that have been modified or extended to support Applespecific functionality. Finally, the guide describes important commands commonly used by UNIX system administrators.

Note: Because Apple frequently 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 (enter one or the other)

italicized

[...] A parameter that may 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 might enter, along with other text that normally 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 the Return key. (Terminal is found in /Applications/Utilities).

Command Parameters and Options

Most commands require one or more parameters to specify command options or the item to which the command is applied.

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 either doit or doit -w later. The result might vary, but the command will be performed 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 either 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

Getting Documentation Updates

Periodically, Apple posts revised guides and solution papers. To download the latest guides and solution papers in PDF format, go to the Mac OS X Server documentation webpage: 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.

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.

Mac OS X Server website (www.apple.com/macosx/server/)—Gateway to extensive product and technology information.

AppleCare Service & Support website (www.apple.com/support/)—Access to hundreds of articles from Apple’s support organization.

Apple customer training (train.apple.com)—Instructor-led and self-paced courses for honing your server administration skills.

Apple discussion groups (discussions.info.apple.com)—A way to share questions, knowledge, and advice with other administrators.

Apple mailing list folder (www.lists.apple.com)—Subscribe to mailing lists so you can communicate with other administrators using email.

The public source website (developer.apple.com/darwin/)—Access to Darwin source code, developer information, and FAQs.

Mac OS X Server suite documentation (www.apple.com/server/documentation/)—The Mac OS X Server documentation includes a suite of guides that explain the available services and provide instructions for configuring, managing, and troubleshooting those services.

This guide ... tells you how to:

Mac OS X Server Getting Started for Version 10.4 or Later

Mac OS X Server Upgrading and Migrating to Version 10.4 or Later

Mac OS X Server User Management for Version 10.4 or Later

18 Preface About This Guide

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

Use data and service settings that are currently being used on earlier versions of the server.

Create and manage users, groups, and computer lists. Set up managed preferences for Mac OS X clients.

This guide ... tells you how to:

Mac OS X Server File Services Administration for Version 10.4 or Later

Mac OS X Server Print Service Administration for Version 10.4 or Later

Mac OS X Server System Imaging and Software Update Administration for Version 10.4 or Later

Mac OS X Server Mail Service Administration for Version 10.4 or Later

Mac OS X Server Web Technologies Administration for Version 10.4 or Later

Mac OS X Server Network Services Administration for Version 10.4 or Later

Mac OS X Server Open Directory Administration for Version 10.4 or Later

Mac OS X Server QuickTime Streaming Server Administration for Version 10.4 or Later

Mac OS X Server Windows Services Administration for Version 10.4 or Later

Mac OS X Server Migrating from Windows NT for Version 10.4 or Later

Mac OS X Server Java Application Server Administration For Version

10.4 or Later

Mac OS X Server Command-Line Administration for Version 10.4 or Later

Mac OS X Server Collaboration Services Administration for Version 10.4 or Later

Mac OS X Server High Availability Administration for Version 10.4 or Later

Share selected server volumes or folders among server clients using these protocols: AFP, NFS, FTP, and SMB/CIFS.

Host shared printers and manage their associated queues and print jobs.

Use NetBoot and Network Install to create disk images from which Macintosh computers can start up over the network. Set up a software update server for updating client computers over the network.

Set up, configure, and administer mail services on the server.

Set up and manage a web server, including WebDAV, WebMail, and web modules.

Set up, configure, and administer DHCP, DNS, VPN, NTP, IP firewall, and NAT services on the server.

Manage directory and authentication services.

Set up and manage QuickTime streaming services.

Set up and manage services including PDC, BDC, file, and print for Windows computer users.

Move accounts, shared folders, and services from Windows NT servers to Mac OS X Server.

Configure and administer a JBoss application server on Mac OS X Server.

Use commands and configuration files to perform server administration tasks in a UNIX command shell.

Set up and manage weblog, chat, and other services that facilitate interactions among users.

Manage IP failover, link aggregation, load balancing, and other hardware and software configurations to ensure high availability of Mac OS X Server services.

Preface About This Guide 19

This guide ... tells you how to:

Mac OS X Server Xgrid Administration for Version 10.4 or Later

Mac OS X Server Glossary: Includes Terminology for Mac OS X Server, Xserve, Xserve RAID, and Xsan

Manage computational Xserve clusters using the Xgrid application.

Interpret terms used for server and storage products.

20 Preface About This Guide

1 Executing Commands

In this chapter you will find out how to execute commands and 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 a complete execution context, called a shell, that is separate from all other execution contexts. The shell itself 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 of your choice, the examples in this book assume that you are using bash, the standard Mac OS X shell.

Opening Terminal

To enter shell commands or run server command-line tools, you need access to a UNIX shell prompt. Both Mac OS X and Mac OS X Server include Terminal, an application you can use to start a UNIX shell command-line session 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 (located 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 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 and the prompt displays 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, wherever a command is shown as you might enter it, 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.

Some of the standard shortcuts used to represent specific folders in the computer 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 represents 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 currently logged in.

In Mac OS X, this folder resides either 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 only letters, numbers, a period, or the underscore character. Most other characters, including space characters, should be avoided. Although some Mac OS X file systems permit the use of these other characters, including spaces, you may have to add single or double quotation marks around any 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 would become either “My Disk” or My\ Disk.

22 Chapter 1 Executing Commands

Modifying Flow Control

Many commands are capable of receiving text input from the user and printing text out to the console. They do so using standard pipes, which are created by the shell and passed to the command automatically.

The standard pipes include:

Â stdin—The standard input pipe is the means through which data enters a

command. By default, this is data entered by the user 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 back to the command line. You can also redirect the output from the command 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 may 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 having to enter that data.

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 any lines containing the word “commands.” The result is a listing of only those lines with the specified text, instead of the entire man page.

See the bash man page for more information about redirection.

Chapter 1 Executing Commands 23

Using Environment Variables

Some commands require the use of environment variables for their execution. Environment variables are variables inherited by all commands executed in the shell’s context. The shell itself 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 also create environment variables and use them to control the behavior of your command without modifying the command itself. For example, you might use an environment variable to tell your command to print debug information to the console.

To set the value of an environment variable, you 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 will modify the environment variable PATH with the value assigned. To view all of the environment variables, enter the following:

$ env

When you launch an application from a shell, the application inherits much of the shell’s environment, including any exported environment variables. This form of inheritance can be a useful way to configure the application dynamically. For example, your application can check for the presence (or value) of an environment variable and change its behavior accordingly. Different shells support different semantics for exporting environment variables, so see the man page for your preferred shell for further information.

PATH

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. Once you close a Terminal window, any 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, you must enter the complete pathname of the tool’s executable file, followed by any arguments, and then press the Return key. If a command is located in one of the shell’s known folders, you can omit any path information and just enter the command name. The list of known folders is stored in the shell’s PATH environment variable and includes the folders containing most of the command-line tools.

For example, to run the ls command in the current user’s home folder, you could simply enter it at the command line and press the Return key.

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 either use the open command (open MyProg.app) or launch the tool by typing 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.

server:/ anne$ serversetup -getAllPort

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$ /System/Library/ServerSetup/serversetup -getAllPort

Built-in Ethernet

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$ ./serversetup -getAllPort

Built-in Ethernet

server:/System/Library/ServerSetup anne$ cd /

server:/ anne$ PATH="$PATH:/System/Library/ServerSetup"

server:/ anne$ serversetup -getAllPort

Built-in Ethernet

Chapter 1 Executing Commands 25

Correcting Typing Errors

To correct a typing error before you press Return to execute the command, press Left Arrow or Right Arrow to skip over parts of the command you don’t want to change, press the Delete key to remove characters, enter regular characters to insert them, and finally press Return to execute the command.

To ignore what you have entered and start again, press Control–U.

Repeating Commands

To repeat a command, press Up Arrow until you see the command, make any modifications, and then 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 Within a File

To locate a unique 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

where filename is the name of the file you wish to search through and sunshine is the unique string.

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

To execute a single command as the root user, begin the command with sudo (short for super user do). For example:

$ sudo serveradmin list

You’re prompted for the root password if you haven’t used sudo recently. The root user password is set to the administrator user password when you install Mac OS X Server.

To switch to the root user so you don’t have to repeatedly enter sudo, use the su command:

$su root

You’re prompted for the root user password and then are logged in as the root user until you log out or use the su command to switch to another user.

26 Chapter 1 Executing Commands

Important: As the root user, you have sufficient privileges to do things that can cause

your server to stop working properly. Don’t execute commands as the root user unless you know what you’re doing. Logging in as an administrator user and using

sudo

selectively might prevent you from making unintended changes.

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 may install signal handlers to trap this signal and respond differently.

Scheduling Tasks

You can create scheduled tasks using the cron tool. cron is a daemon that executes scheduled commands from a crontab file. 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. cron also searches for crontab files in the /etc/crontab folder, which are in a different format. cron then cycles every minute, examining all stored crontab files and checking each command to see if it should be run in the current minute.

When commands execute, any 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 such exists. When a crontab file has been modified, cron needs to be restarted. crontab is the program used to install, deinstall, or list the tables used to drive the cron daemon. Each user 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 /usr/local/vscanx folder-name 50 23 * * 0 /usr/local/vscanx --summary folder-name 15 10 * * 6 /usr/local/vscanx --load /usr/local/conf1 /uz 458** 1 /usr/local/vscanx --f /usr/local/biglist

Listed below is an explanation of the crontab structure shown above.

The following crontab entry schedules a scan operation to run and produce a summary at 18:30 every day, Monday through Friday:

30 18 * * 1-5 /usr/local/vscanx folder-name

Chapter 1 Executing Commands 27

The following crontab entry schedules a scan operation to run and produce a summary at 23:50 every Sunday:

50 23 * * 0 /usr/local/vscanx --summary folder-name

The following crontab entry schedules a scan operation to run on the uz folder at 10:15 a.m. every Saturday in accordance with options specified in a configuration file conf1:

15 10 * * 6 /usr/local/vscanx --load /usr/local/conf1 /uz

The following crontab entry schedules a scan operation to run at 8:45 a.m. every Monday on the files specified in the file biglist:

45 8 * * 1 /usr/local/vscanx --f /usr/local/biglist

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.

See Chapter 2, “Connecting to Remote Computers,” on page 31 for information about sending commands to remote computers.

Viewing Command Information

Most command-line documentation comes in the form of man pages. These are formatted pages that 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 any 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 the man pages are so long that they do not fit on your screen, you can use the more or less command to automatically paginate the file. This allows you to view the file faster by loading full screens of the man page at a time, rather than the entire file.

$ man serveradmin | less

28 Chapter 1 Executing Commands

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

When you use more or less, an information bar appears at the bottom of the screen. When you see the bar, you can press the Space bar to go to the next page, the B key to go back a page, or the Return key to scroll the file forward one line at a time. When you get to the end of a file, more will return you to the prompt and less will wait 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 seraching for “man page.”

Note: Not all commands and tools have man pages. For a list of available man pages, look in /usr/share/man.

To access command help, enter the command followed by the -help, -h, --help, or help parameter:

$ hdiutil help

$ dig -h

$ diff --help

To view a pop-up list of options and parameters you can use with the command, enter the command without any options or parameters:

$ sudo serveradmin

Note: Not all techniques work for all commands, and some commands don’t have onscreen help.

Chapter 1 Executing Commands 29

30 Chapter 1 Executing Commands

2 Connecting to Remote Computers

In this chapter you will find commands you can use to connect to remote computers.

Connecting to remote computers helps you manage and configure resources efficiently. This chapter covers using SSH and Telnet to connect to remote computers.

Understanding Secure Shell

Secure Shell (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:

Â The local and remote computers exchange their public keys. If the local computer

has never encountered a given public key before, both SSH and a web browser will prompt you whether to accept the unknown key.

Â The two computers use the public keys to negotiate a session key that is used to

encrypt all subsequent session data.

Â 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 username/password combination. See “Password-Less Logins Using SSH Keys” on page 32 for information about setting up certificate authentication.

Â After successful authentication, the session begins. Either a remote shell, a secure file

transfer, a remote command, or so on, is begun through the encrypted tunnel.

You should be aware of the following SSH tools:

Â sshd—Daemon that acts as a server to all other commands

Â ssh—Primary user tool: remote shell, remote command, and port-forwarding

sessions

Â scp—Secure copy, a tool for automated file transfers

Â sftp—Secure FTP, a replacement for FTP

Password-Less Logins Using SSH Keys

The standard method of SSH authentication is supplying login credentials in the form of a user name and password. Identity key pair authentication enables you to log in to the server without having to supply a password. This process works by:

Â Generating a private and public key associated with a user name to establish that

user’s authenticity. When you attempt to log in as that user, the user name is sent to the remote computer.

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

Â A challenge is then sent to the user based on his or her public key.

Â The user verifies his or her identity by using the private portion of the key pair to

decode the challenge.

Â Once decoded, the user is logged in without the need for a password. This is

especially useful when automating remote scripts.

To generate the identity key pair, use the following command on the local computer:

$ ssh-keygen -t dsa

When prompted, enter a filename in which to save the keys in the user’s folder. 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: 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

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, is also displayed. This secures the public key, making it computationally infeasible for duplication.

32 Chapter 2 Connecting to Remote Computers

frog

.pub.

frog

Copy the resultant public file, which contains the local computer’s public key to the user’s home folder in .ssh/ on the remote computer. 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 already logged in using the account, you do not have to supply a pasword 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). See the Open Directory administration guide for more information.

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 compared against in later sessions. Be sure this is the correct key before accepting it. If at all possible, provide your users with the encryption key either through FTP, email, 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 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 either 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.

Â Are attempting to SSH in to a computer that has the same IP address as a computer

that you previously used SSH with on another network.

To connect again, delete the entries corresponding to the remote computer (which can be stored by both name and IP address) in the file ~/.ssh/known_hosts.

Chapter 2 Connecting to Remote Computers 33

What is an SSH Man-in-the-Middle Attack?

An attacker may be able to get access to your network and compromise proper routing information, such that packets intended for a remote computer are instead routed to the attacker who 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 the 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 the information that goes back and forth, and can modify it.

A sign that may indicate a man-in-the-middle attack is the following message when connecting to the remote computer using SSH.

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

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

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. Be sure you understand why the key on the remote computer has changed before you delete its entry from the known_hosts file.

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 are always allowed to open a connection using SSH. The ssh tool uses the SSH service. For information about controlling access to the SSH service, see the Open Directory administration guide.

34 Chapter 2 Connecting to Remote Computers

Connecting to a Remote Computer

You can connect to a remote computer using SSH (secure) or Telnet (non-secure).

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 Enter the following command to log in to the remote computer, and then press Return:

$ ssh -l

where username is the name of an administrator user on the remote computer and server is the name or IP address of the remote computer. For example:

$ ssh -l anne 10.0.1.2

3 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 is displayed. Enter

yes and press Return.

4 When prompted, enter the user’s password (the user’s password on the remote

computer) and press Return.

The command prompt changes to show that you’re now connected to the remote computer. In the case of the previous example, the prompt might look like:

10.0.1.2:~ anne$

5 To send a command to the remote computer, enter the command and press Return.

To close a remote connection, enter logout and press Return.

username server

To authenticate and send a command using a single line, append the command you want to execute to the basic ssh tool. For example, to delete a file:

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

Chapter 2 Connecting to Remote Computers 35

Using Telnet

Use the telnet tool to create a Telnet connection to a remote computer. Because it isn’t as secure as SSH, Telnet access is disabled by default.

To enable Telnet access:

$ service telnet start

To disable Telnet access:

$ service telnet stop

You are strongly advised not to enable Telnet. When you log in using Telnet, your login information, user name, and password are passed along the Internet in clear text. In fact, your entire Telnet session is also passed along the Internet in clear text. Any person on the network running tcpdump, ethereal, or similar applications can effortlessly 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 will be compromised as well.

To access a remote computer using telnet:

$ telnet -l

where username is the name of an administrator user on the remote computer and server is the name or IP address of the remote computer. For example:

$ telnet -l anne 10.0.1.2

username server

Once connected, the remote computer will prompt for a login name, and then the 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. You may see a series of messages on the screen, followed by the remote computer’s prompt. You are now completely logged in. When you are finished working, log out from the remote computer by typing logout or

exit at the remote computer’s prompt. The telnet client will automatically exit when

you log out from the remote computer.

See the telnet man page for more information.

36 Chapter 2 Connecting to Remote Computers

3 Installing Server Software and

Finishing Basic Setup

In this chapter you will find commands you can use to install, set up, and update Mac OS X Server software on local or remote computers.

Some computers come with Mac OS X Server software already installed. However, you might want to upgrade from a previous version, change a computer configuration, automate software installation, or completely refresh your server environment. This chapter covers the commands needed to perform a variety of software setup and installation tasks.

Installing Server Software

You can use the /usr/sbin/installer tool to install Mac OS X Server or other software on a computer. 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 out the details of the installation. It’s useful for monitoring progress.

See the installer man page for detailed information.

To use 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 the target computer’s actual IP address for <ip address>:

$ ssh root@<ip address>

If you don’t know the IP address, you can use the sa_srchr tool to identify computers on the local subnet on which 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.4#RDY4PkgInstall#2.0#512

You can also use Server Assistant to generate information for computers on the local subnet. Open Server Assistant, select “Install software on a remote computer,” and click Continue to access the Destination pane and generate a list of computers awaiting installation.

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

Locating Computers for Installation

If you are installing software on a remote computer from Terminal, you will first want to 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. You can use the to identify the IP address of each computer that’s ready for installation on your subnet.

38 Chapter 3 Installing Server Software and Finishing Basic Setup

sa_srchr tool

Note: To locate computers, you must have booted the computer from the installation CD.

To list 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 would come from sa_rspndr running on a computer started up from the Mac OS X Server installation CD. The computer will respond with output similar to the following:

localhost#unknown#<ip address>#<mac address>#Mac OS X Server

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

Use the installer tool to specify the target computer volume onto which you want to install the server software.

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.4/System/

Installation/Packages/OSInstall.mpkg

The list displayed reflects your particular environment, but here’s an example showing three available volumes:

/Volumes/Mount 01

/Volumes/Mount1

/Volumes/Mount02

Preparing the Target Volume for a Clean Installation

If the target volume has Mac OS X Server version 10.3 or version 10.2.8 installed, when you run installer, it will upgrade the server to version 10.4 and preserve user files.

If you’re not upgrading but 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"

Chapter 3 Installing Server Software and Finishing Basic Setup 39

You can also use diskutil to partition the volume and to set up mirroring. For more information, see the diskutil man page or Chapter 7, “Working with Disks and Volumes,” on page 83.

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 need to reinstall or upgrade system software.

Installing from Multiple CDs

If you’re using CDs for server installation, use the sa_srchr tool to install the remaining software from the remaining installation CDs. Server Assistant opens automatically when installation is complete.

1 To use the next installation disc, use the sa_srchr command to locate the computer

that’s waiting. For <ip address>, specify the address you used in step 2:

$ /System/Library/Serversetup/sa_srchr <ip address>

2 When the sa_srchr response includes the string “#InstallInProgress”, insert the next

installation disc:

$ mycomputer.example.com#PowerMac4,4#<ip address>#<mac address> #Mac OS X

Server 10.4#InstallInProgress#2.0#2080

Restarting After Installation

When installation from the disc is complete, restart the computer. Enter:

$ /sbin/reboot

$ /sbin/shutdown -r

Automating Server Setup

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 up and 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. You can automate this initial setup task by providing a configuration file that contains these settings.

Servers that have previously had Mac OS X Server version 10.4 installed automatically detect the presence of the saved setup information and use it to complete initial server setup without user interaction.

40 Chapter 3 Installing Server Software and Finishing Basic Setup

You can define generic setup data that can be used to set up any computer. For example, you might want to define generic setup data for a computer that’s on order, or to configure 50 Xserve computers you want to be identically configured. You can also save setup data that’s specifically tailored for a particular computer.

Important: When you perform an upgrade installation, 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 saved 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 any number of 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 more than one computer, don’t specify network names (computer name and local hostname), and make sure that 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 then 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; when searching for setup files, target computers search for names in the order listed:

Â MAC-address-of-server.plist (include any 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.

Chapter 3 Installing Server Software and Finishing Basic Setup 41

Â partial-IP-address-of-server.plist—For example, 10.0.plist (matches 10.0.0.4 and

10.0.1.2).

Â generic.plist—A 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 particular computer, it will use the file named generic.plist.

To create a configuration file at any time after initial setup:

1 Open Server Assistant (located in /Applications/Server/).

2 In the Welcome pane, select “Save setup information in a file or folder 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” 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; when searching for setup files, target computers search for names in the order listed here:

Â MAC-address-of-server.plist (include any 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—A file that any computer will recognize, used to set up computers that

need the same setup values.

42 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 the target computer or 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 new 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 any 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—A 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 the

passphrase. Click Send.

Customizing a Configuration File

After you create a configuration file, you can modify it directly using a text editor, or write a script to automatically 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 43

The following example shows the basic structure and contents of a configuration file for a computer with the following 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 Computer//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> <false/> <key>name</key> <string>admin</string> <key>password</key> <string>secret</string> <key>realname</key> <string>Administrator</string> <key>uid</key>

<string>501</string> </dict> <key>ComputerName</key> <string>server1.example.com</string> <key>DS</key> <dict>

<key>DSClientInfo</key>

<string>2 - NetInfo client - broadcast dhcp static -192.168.42.250

network</string>

<key>DSClientType</key>

<key>DSType</key>

<string>2 - directory client</string> </dict> <key>HostName</key> <string>server1.example.com</string> <key>InstallLanguage</key> <string>English</string> <key>Keyboard</key> <dict>

<key>DefaultFormat</key>

44 Chapter 3 Installing Server Software and Finishing Basic Setup

<key>DefaultScript</key>

<key>ResID</key>

<key>ResName</key>

<key>ScriptID</key>

<integer>0</integer> </dict> <key>NetworkInterfaces</key> <array>

<dict>

<key>ActiveAT</key> <true/> <key>ActiveTCPIP</key> <true/> <key>DNSDomains</key> <array>

<string>example.com</string> </array> <key>DNSServers</key> <array>

<string>192.168.100.10</string> </array> <key>DeviceName</key> <string>en0</string> <key>EthernetAddress</key> <string>00:0a:93:bc:6d:1a</string> <key>PortName</key> <string>Built-in Ethernet</string> <key>Settings</key> <dict>

<key>DHCPClientID</key>

<string>DHCP Configuration</string> </dict>

</dict> </array> <key>PrimaryLanguage</key> <string>English</string> <key>Bonjour</key> <dict>

<key>BonjourEnabled</key>

<true/>

<key>BonjourName</key>

<string>beasbe3</string> </dict> <key>SerialNumber</key> <string>XSVR-123-456-A-BCD-7EF-GHI-89J-1KL-MNO-2</string>

Chapter 3 Installing Server Software and Finishing Basic Setup 45

<key>ServiceNTP</key> <dict>

<key>HostNTP</key>

<key>HostNTPServer</key>

<string>Local</string>

<key>UseNTP</key>

<false/> </dict> <key>ServicesAutoStart</key> <dict>

<key>Apache</key>

<key>IChat</key>

<key>NetBoot</key>

<key>SWUPD</key>

<key>WebDAV</key>

<key>Weblog</key>

<key>XgridA</key>

<key>XgridC</key>

<false/> </dict> <key>TimeZone</key> <string>US/Pacific</string> <key>VersionNumber</key> <integer>2</integer>

</dict> </plist>

Note: The actual contents of a configuration file depend on the hardware configuration of the computer on which it’s created, so you should customize a configuration file created on a computer similar to those you plan to set up.

46 Chapter 3 Installing Server Software and Finishing Basic Setup

Storing a Configuration File in an Accessible Location

Server Assistant looks for configuration files in the following location:

/Volumes/

vol

/Auto Server Setup/

where vol is any device volume mounted in /Volumes.

Devices you can use to provide configuration files include:

Â A partition on one of the computer’s hard disks

Â An iPod

Â An optical (CD or DVD) drive

Â A USB or FireWire drive

Â Any other portable storage device that mounts in the /Volumes folder

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—Directory service command line is a general purpose tool that allows you to

create, read, and manage directory service data. If invoked without any commands,

dscl runs interactively, reading commands from standard input. See Chapter 8,

“Working with Users and Groups,” for more information about the usage of this command.

Â systemsetup—Use systemsetup to set a number of system-wide preferences. If you

were going through Server Assistant, you would have to select the proper keyboard and time zone. The systemsetup tool can configure both these preferences, and more. See Chapter 5, “Setting General System Preferences,” for mor information on the usage of this command.

Â networksetup—Anything that you can configure in the Network pane of System

Preferences can also be configured using networksetup. See Chapter 6, “Setting Network Preferences,” for more information about the usage of this command.

See the man pages related to these tools for more information. The man pages for

systemsetup and networksetup are only available on Mac OS X Server.

Chapter 3 Installing Server Software and Finishing Basic Setup 47

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

If you want to use the tool to perform several commands, you can change your working folder and enter a shorter command:

$ cd /System/Library/ServerSetup

$ ./serversetup -getAllPort

$ ./serversetup -getDefaultInfo

Or, add the folder to your search path for this session and enter an even shorter command:

$ PATH="$PATH:/System/Library/ServerSetup"

$ serversetup -getAllPort

To permanently add the folder to your search path, add the path to the file /etc/profile.

Using the serveradmin Tool

The serveradmin tool is used for administering service-related tasks. Some services need to be restarted after you change certain 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 is displayed only if you use the

serveradmin

see it if you use the serveradmin settings command.

Other chapters in this guide have information about using the serveradmin tool 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.

Â servermgrd uses SSL for encryption and client authentication, 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. You can use the Certificate Manager in Server Admin to create and manage certificates. See the mail service administration guide for more information.

svc

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

48 Chapter 3 Installing Server Software and Finishing Basic Setup

Â 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

Â servermgrd checks the validity of the SSL certificate only 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 the Mail Service administration guide 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.

servermgrd SSL encryption options can be changed at any time by editing the

Â 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

See the following for information about changing general system preferences and network settings:

Â Chapter 5, “Setting General System Preferences,” on page 57

Â Chapter 6, “Setting Network Preferences,” on page 63

Viewing, Validating, and Setting the Software Serial Number

You can use the serversetup tool to view or set the server’s software serial number or to validate a server software serial number. The serversetup tool is located in /System/ Library/ServerSetup.

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

serialnumber watermarkinformation

Chapter 3 Installing Server Software and Finishing Basic Setup 49

To validate a server software serial number:

$ sudo serversetup -verifyServerSerialNumber

watermarkinformation

serialnumber

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

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

To check whether 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 will be 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 [recommmended] [restart] * J2SE50Release3-3.0 **PRERELEASE** J2SE 5.0 Release 3 (8M318) (3.0), 44020K [recommmended]

- 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

$ command_line_install=1 export command_line_install

50 Chapter 3 Installing Server Software and Finishing Basic Setup

softwareupdate:

This creates an environment variable named command_line_install that automates the update responses. See the softwareupdate man page for more information about the command.

Moving a Server

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

If you must move a server after initial setup, you need to 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 need

to 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 on which other computers depend.

Â 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 will need to change after the move.

Â After you move the server, use the

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

Â 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 the Open Directory administration guide.

changeip tool to change IP addresses, host names,

Chapter 3 Installing Server Software and Finishing Basic Setup 51

52 Chapter 3 Installing Server Software and Finishing Basic Setup

4 Restarting or Shutting Down a

Computer

In this chapter you will find commands you can use to shut down or restart a local or remote computer.

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

Restarting a Computer

You can use the reboot or shutdown -r command to restart a computer at a specific time. See the relevant man pages for more information.

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 automatically after a power failure or system freeze. See “Viewing or Changing Automatic Restart Settings” on page 59.

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

You can use the shutdown tool to shut down a computer at a specific time. See the

shutdown man page for more information.

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.

Manipulating Open Firmware NVRAM Variables

You can use the nvram tool to manipulate Open Firmware NVRAM variables. If you modify a value with nvram, the value is saved only if the computer cleanly restarts or shuts down. See the nvram man page for more information.

To view the different NVRAM variables:

$ nvram -p

54 Chapter 4 Restarting or Shutting Down a Computer

Monitoring and Restarting Critical Services

In earloier 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. The watchdog daemon relied on the configuration file watchdog.conf, located in /etc.

In Mac OS X Server version 10.4, watchdog has been replaced by launchd. The launchd daemon manages other daemons, both for the computer as a whole and for individual 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 rest of the computer. In Mac OS X Server, it is preferable to have your daemon started by

Note: Some system administrators need to 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 whatever changes they require, and avoid modifying rc or creating a SystemStarter Startup Item. The rc command script may be phased out in the future.

The configuration files are located in the following folders:

launchd.

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 55

56 Chapter 4 Restarting or Shutting Down a Computer

5 Setting General System

Preferences

In this chapter you will find commands you can use to set system preferences, usually set using the System Preferences graphical application.

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

Â A computer’s time zone

Â Whether a server uses a network time server

These settings can also be changed using the Date & Time pane of System Preferences.

Viewing or Changing the System Date

To view the current system date:

$ sudo systemsetup -getdate

$ serversetup -getDate

To set the current system date:

$ sudo systemsetup -setdate

mm:dd:yy

$ sudo serversetup -setDate

mm/dd/yy

Viewing or Changing the System Time

To view the current system time:

$ sudo systemsetup -gettime

$ serversetup -getTime

To change the current system time:

$ sudo systemsetup -settime

hh:mm:ss

$ sudo serversetup -setTime

hh:mm:ss

Viewing or Changing the System Time Zone

To view the current time zone:

$ sudo systemsetup -gettimezone

$ serversetup -getTimeZone

To view the available time zones:

$ sudo systemsetup -listtimezones

To change the system time zone:

$ sudo systemsetup -settimezone

timezone

$ sudo serversetup -setTimeZone

timezone

Viewing or Changing Network Time Server Usage

To see if a network time server is being used:

$ sudo systemsetup -getusingnetworktime

58 Chapter 5 Setting General System Preferences

To enable or disable use of a network time server:

$ sudo systemsetup -setusingnetworktime (on|off)

To view the current network time server:

$ sudo systemsetup -getnetworktimeserver

To specify a network time server:

$ sudo systemsetup -setnetworktimeserver

timeserver

Viewing or Changing the Energy Saver Settings

You can use the systemsetup tool to view or change a server’s energy saver settings. These can also be changed using 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

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

$ sudo systemsetup -getwakeonmodem

minutes

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

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

Chapter 5 Setting General System Preferences 59

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 the Power Management Settings

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

Â Display dim timer

Â Disk spindown 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 can configure different settings for the different power modes using pmset. There are four flags you can use: -a, -b, -c, and -u. -b applies the settings to battery operation, -c to charger (wall power), -u to UPS, and -a to all.

To set disk spindown timer for all modes of operation:

$ sudo pmset -u spindown

Parameter Description

minutes

Must be a multiple of 30 seconds.

To display the current settings:

$ sudo pmset -g

command

See the pmset man page for more information.

Viewing or Changing the Startup Disk Settings

You can use the systemsetup tool to view or change a computer’s startup disk. This can also be set using the Startup Disk pane of System Preferences.

To view the current startup disk:

$ sudo systemsetup -getstartupdisk

To view the available startup disks:

$ sudo systemsetup -liststartupdisks

60 Chapter 5 Setting General System Preferences

To change the current startup disk:

$ sudo systemsetup -setstartupdisk

path

Viewing or Changing the Sharing Settings

You can use the systemsetup tool to view or change Sharing settings. These can also be set using 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

Telnet access is disabled by default because it isn’t as secure as SSH. You can, however, 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)

Viewing or Changing the International Settings

You can use the serversetup tool to view or change language settings. These can also be set using the International pane of System Preferences.

To view the current primary language:

$ serversetup -getPrimaryLanguage

To view the installed primary language:

$ serversetup -getInstallLanguage

To change the installation language:

$ sudo serversetup -setInstallLanguage

To view the script setting:

$ serversetup -getPrimaryScriptCode

language

Chapter 5 Setting General System Preferences 61

Viewing and Changing the 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

62 Chapter 5 Setting General System Preferences

6 Setting Network Preferences

In this chapter you will find commands you can use to change the 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

Mac OS X Server includes ifconfig, the standard UNIX tool for configuring networks. Both ifconfig and networksetup make system calls to change the interface configuration. However, ifconfig and networksetup do not communicate with each other. ifconfig changes the network interface settings.

Warning: If you use ifconfig, your computer will be out of sync and will revert back

to the contents of preferences.plist after a restart.

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

It’s best to rely on networksetup and serversetup for your manual configuration. You are encouraged to view the man pages of both commands to see all the available configuration options.

Managing Network Interface Information

This section describes commands you address to a specific hardware device (for example,

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

Viewing Port Names and Hardware Addresses

To list all port names:

$ serversetup -getAllPort

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

en0) or port (for example, Built-in Ethernet).

To view the Ethernet (MAC) address of a particular 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 that is transmitted over a network travels in data packets. The size of the data packets is called maximum transmission units (MTU), which if too large or too small will affect performance. You can use the networksetup tool to change the MTU size for a port.

To view the MTU value for a hardware port:

$ sudo networksetup -getMTU (

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

64 Chapter 6 Setting Network Preferences

Viewing or Changing Media Settings

To view the media settings for a port:

$ sudo networksetup -getMedia (

devicename|"portname

To list valid media settings for a port:

$ sudo networksetup -listValidMedia (

devicename|"portname

To change the media settings for a port:

$ sudo networksetup -setMedia (

[option2] [...]

devicename|"portname

") subtype [option1]

Managing Network Port Configurations

Network port configurations are sets of network preferences that can be assigned to a particular 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 an existing port configuration:

$ sudo networksetup -listallnetworkservices

To create a port configuration:

$ sudo networksetup -createnetworkservice

configuration hardwareport

To duplicate a port configuration:

$ sudo networksetup -duplicatenetworkservice

configuration newconfig

To rename a port configuration:

$ sudo networksetup -renamenetworkservice

configuration newname

To delete a port configuration:

$ sudo networksetup -removenetworkservice

configuration

Activating Port Configurations

To see if a port configuration is on:

$ sudo networksetup -getnetworkserviceenabled

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.

Chapter 6 Setting Network Preferences 65

To change the order of the port configurations:

$ sudo networksetup -ordernetworkservices

config1 config2 [config3

] [...]

Managing TCP/IP Settings

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

Changing a Server’s IP Address

Changing a server’s IP address isn’t as simple as changing the TCP/IP settings. Address information is set throughout the system when you set up the server. To make sure that all the necessary changes are made, use the

changeip is a python script that runs tools out of the /usr/libexec/changeip folder.

There are currently three tools 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

changeip tool.

The changeip_ds tool also updates the following records in the local NetInfo 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.

66 Chapter 6 Setting Network Preferences

To change a server’s IP address:

1 Run the changeip tool:

$ changeip [(

Parameter Description

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

You can use the serversetup and networksetup tools to change a computer’s TCP/IP settings.

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

Chapter 6 Setting Network Preferences 67

To list TCP/IP settings for a configuration:

$ sudo networksetup -getinfo "configuration"

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

$ serversetup -getDefaultinfo (

devicename|"portname

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

$ serversetup -getInfo (

devicename|"portname

To change TCP/IP settings for a particular 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

]

68 Chapter 6 Setting Network Preferences

Viewing or Changing DNS Servers

You can use the serversetup tool to view and modify the Domain Name Server (DNS) settings.

To view the DNS servers for port en0:

$ serversetup -getDefaultDNSServer (

To change the DNS servers for port en0:

$ sudo serversetup -setDefaultDNSServer (

server2

[

] [...]

To view the DNS servers for a particular port or device:

$ serversetup -getDNSServer (

devicename|"portname

To change the DNS servers for a particular port or device:

$ sudo serversetup -setDNSServer (

[...]

To list the DNS servers for a configuration:

$ sudo networksetup -getdnsservers "

To view the DNS search domains for port en0:

$ serversetup -getDefaultDNSDomain (

devicename|"portname

configuration

devicename|"portname

server1

server1 [server2

]

To change the DNS search domains for port en0:

$ sudo serversetup -setDefaultDNSDomain (

domain2

[

] [...]

devicename|"portname

To view the DNS search domains for a particular port or device:

$ serversetup -getDNSDomain (

devicename|"portname

To change the DNS search domains for a particular port or device:

$ sudo serversetup -setDNSDomain (

[...]

devicename|"portname

domain1 [domain2

To list the DNS search domains for a configuration:

$ sudo networksetup -getsearchdomains "

configuration

To set the DNS servers for a configuration:

$ sudo networksetup -setdnsservers "

configuration" dns1 [dns2

To set the 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

] [...]

domain1

] [...]

]

Chapter 6 Setting Network Preferences 69

Enabling TCP/IP

Use the serversetup tool to enable or disable TCP/IP on a computer.

To enable TCP/IP on a particular port:

$ serversetup -EnableTCPIP [(

devicename|"portname

")]

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

To disable TCP/IP on a particular port:

$ serversetup -DisableTCPIP [(

devicename|"portname

")]

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

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

name parentdevice tag

To list available VLANs:

$ networksetup -listVLANs

To list the devices that support VLANs:

$ networksetup -listdevicesthatsupportVLAN

IEEE 802.3ad Ethernet Link Aggregation

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 any modifications. The advantage of aggregation is that the virtual interface provides increased bandwidth by merging the bandwidth of the 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 any port or cable fails. All traffic that was being routed over the failed port is automatically rerouted to use one of the remaining ports. This failover is completely transparent to the software using the connection. This feature provides increased bandwidth and automatic failover for the server environment.

70 Chapter 6 Setting Network Preferences

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

is the name of the pseudo device and the

is the actual 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 have their Ethernet address reprogrammed so that all 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 all interfaces are reprogrammed with the new Ethernet address. If no remaining interfaces exist, the bond interface’s Ethernet address is cleared.

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 will remain inactive. To monitor the IEEE 802.3ad Link Aggregation state, use the -b option.

See the ifconfig man page for more information.

Configuring Ethernet Link Aggregation

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

To display if the 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

Chapter 6 Setting Network Preferences 71

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. Use the serversetup tool to enable or disable AppleTalk.

To enable AppleTalk on a particular port:

$ serversetup -EnableAT [(

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

To disable AppleTalk on a particular port:

$ serversetup -DisableAT [(

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

To enable AppleTalk on en0:

$ serversetup -EnableDefaultAT

To disable AppleTalk on en0:

$ serversetup -DisableDefaultAT

devicename|"portname

")]

To make AppleTalk active or inactive for a configuration:

$ sudo networksetup -setappletalk "

configuration

" (on|off)

To check 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 uses a manager/ agent design.

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 the manager and the agent.

72 Chapter 6 Setting Network Preferences

Installing SNMP

To use SNMP for monitoring or data collection, an SNMP agent (snmpd) must be running on the monitored Mac OS X Server host computer. Mac OS X Server version

10.1.5 or later includes a version of SNMP (UCD-SNMP v. 4.2.3 or later).

If you do not have the file /usr/sbin/snmpd, then SNMP is not installed. Mac OS X Server version 10.1.4 or earlier require that SNMP be built and installed. Mac OS X Server v10.1.5 or later Admin CDs include the SNMP package on the CD used to install UCDSNMP 4.2.3 on these older systems. If you do not have access to the CD, you may download current SNMP source from the NET-SNMP Project Home Page (www.netsnmp.org/).

Warning: Once SNMP is active, anyone with a route to the SNMP host will be able to

collect SNMP data from it. To learn more, consult the various SNMP information sources listed below.

The default configuration of snmpd uses privileged port 161. For this reason and others, it must be executed by root or by using setuid. You should only use setuid as root if you understand the ramifications. If you do not, seek assistance or additional information. There are flags available for snmpd that will change the UID and GID of the process after it starts. See the snmpd man page for more information.

Starting SNMP

To start SNMP you have three options:

Â Click the checkbox to enable SNMP in the Server Admin application. This modifies

the hostconfig file for you.

Â Modify the hostconfig file to start SNMP automatically at system startup.

Â Start the SNMP agent manually.

To start SNMP on Mac OS X Server version 10.4 or later by modifying the hostconfig file:

1 Open the /etc/hostconfig file.

2 Locate the line:

SPOTLIGHT=-YES-

3 Immediately above it, add this line:

SNMPSERVER=-YES-

4 Save the file.

Chapter 6 Setting Network Preferences 73

To start SNMP on Mac OS X 10.4 client computers by modifying the hostconfig file:

Mac OS X 10.4 client systems already have the SNMPSERVER:=-NO- line in their hostconfig file by default.

1 Open the /etc/hostconfig file.

2 Locate the line:

SNMPSERVER=-NO-

3 Change NO to YES.

4 Save the file.

Note: Systems running Mac OS X Server version 10.3 or earlier will need to have the line added.

Changing the SNMPSERVER line in the hostconfig file, causes snmpd to be executed during system startup, with no options, as dictated by the /System/Library/ StartupItems/SNMP/SNMP file. For further instruction on editing configuration files, including important precautionary statements, see technical document 106619, “Mac OS X Server: How to Edit Configuration Files”.

To start the snmp agent manually:

$ /usr/sbin/snmpd

Configuring SNMP

The configuration (conf) file for snmpd is typically in the /usr/share/snmp/ folder, and is named snmpd.conf or snmpd.local.conf. If you have an environment variable SNMPCONF, snmpd will read any files named snmpd.conf and snmpd.local.conf in these folders. The SNMP agent can be started with a -c flag to indicate other conf files. See the snmpd man page for more information about which conf files can be used.

Configuration files can be created and installed more easily using the included script /usr/bin/snmpconf. As root, use this script with the -i flag to install the file in the /usr/share/snmp/ folder. Otherwise, the default location for the file to be written is the user's home directory (~/). Only root has write permission for /usr/share/snmp/.

Because snmpd reads its conf files at startup, changes to the conf files require that the process be stopped and restarted. To do this, you must identify the process id.

To identify the process id:

$ ps aux |grep snmpd

To stop snmpd :

$ kill <pid>

Once snmpd is stopped, you can customize the snmpd.conf file as needed.

74 Chapter 6 Setting Network Preferences

To customize the data provided by snmpd, you may add an snmpd.conf file using /usr/bin/snmpconf:

$ sudo /usr/bin/snmpconf -i

You will then see a series of text menus. Make these choices in this order:

1 Select File: 1 (snmpd.conf )

2 Select section: 5 (System Information Setup)

3 Select section: 1 (The [typically physical] location of the system)

4 The location of the system: type text string here—such as server_room

5 Select section: f (finish)

6 Select section: f (finish)

7 Select File: q (quit)

This creates an snmpd.conf file with a creation date of today.

To view the snmp.conf file:

$ ls -l /usr/share/snmpd.conf

Once the configuration file is created, restart the snmpd process.

To start snmpd, execute this as root:

$ sudo /usr/sbin/snmpd

Collecting SNMP Information from the Host

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

$ snmpget -v 1 -c public

hostname

You should see the location you provided. In this example, you would see:

system.sysLocation.0 = server_room

The other options in the menu you were working in are:

$ snmpget -v 1 -c

hostname

The final .0 indicates you are looking for the index object. The word public is the name of the SNMP community, which you did not alter. If you need information about either of these, or explanations of SNMP syntax, there are tutorials available at www.netsnmp.sourceforge.net.

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

Chapter 6 Setting Network Preferences 75

hostname

system.sysLocation.0

public system.sysContact.0

public system.sysServices.0

is replaced with the actual name of the

To gather SNMP information in bulk:

$ sudo snmpwalk -v 1 -c public

localhost

This will list 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 retrieve specific SNMP management values, use the snmpget tool as shown in the following examples.

To view the system name:

$ snmpget -v 1 -c public localhost system.sysName.0

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

To view the system location:

$ snmpget -v 1 -c public localhost system.sysLocation.0

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

To view the system uptime:

$ snmpget -v 1 -c public localhost system.sysUptime.0

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

For a list of snmp man pages, enter the following:

$ 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 allows for a more secure environment. Use the networksetup tool to view or change the proxy settings.

Viewing or Changing FTP Proxy Settings

To view the FTP proxy information for a configuration:

$ sudo networksetup -getftpproxy "

To set the FTP proxy information for a configuration:

$ sudo networksetup -setftpproxy "

To view the FTP passive setting for a configuration:

$ sudo networksetup -getpassiveftp "

To enable or disable FTP passive mode for a configuration:

$ sudo networksetup -setpassiveftp "

configuration

configuration" domain portnumber

configuration

" (on|off)

76 Chapter 6 Setting Network Preferences

To enable or disable the FTP proxy for a configuration:

$ sudo networksetup -setftpproxystate "

configuration

" (on|off)

Viewing or Changing Web Proxy Settings

To view the web proxy information for a configuration:

$ sudo networksetup -getwebproxy "

configuration

To set the 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

" (on|off)

Viewing or Changing Secure Web Proxy Settings

To view the secure web proxy information for a configuration:

$ sudo networksetup -getsecurewebproxy "

To set the secure web proxy information for a configuration:

$ sudo networksetup -setsecurewebproxy "

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

$ sudo networksetup -setsecurewebproxystate "

configuration

configuration" domain portnumber

configuration

" (on|off)

Viewing or Changing Streaming Proxy Settings

To view the streaming proxy information for a configuration:

$ sudo networksetup -getstreamingproxy "

configuration

To set the 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

Viewing or Changing Gopher Proxy Settings

To view the gopher proxy information for a configuration:

$ sudo networksetup -getgopherproxy "

To set the 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)

Chapter 6 Setting Network Preferences 77

Viewing or Changing SOCKS Firewall Proxy Settings

To view the SOCKS firewall proxy information for a configuration:

$ sudo networksetup -getsocksfirewallproxy "

configuration

To set the 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

" (on|off)

Viewing or Changing Proxy Bypass Domains

To list the proxy bypass domains for a configuration:

$ sudo networksetup -getproxybypassdomains "

configuration

To set the proxy bypass domains for a configuration:

$ sudo networksetup -setproxybypassdomains "

[...]

configuration

" [

domain1] domain2

Managing AirPort Settings

AirPort uses wireless local area network (WLAN) technology to provide wireless communication between computers. Use the networksetup tool to view or change the AirPort settings.

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 current AirPort network:

$ sudo networksetup -getairportnetwork

To join an AirPort network:

$ sudo networksetup -setairportnetwork

network [password

]

78 Chapter 6 Setting Network Preferences

Managing the Computer, Host, and Bonjour Names

These names are used by networking applications to identify a computer.

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. Use the serversetup tool to view or modify the computer name.

To display the computer name:

$ sudo systemsetup -getcomputername

$ sudo networksetup -getcomputername

$ serversetup -getComputername

To change the computer name:

$ sudo systemsetup -setcomputername

$ sudo networksetup -setcomputername

computername

$ sudo serversetup -setComputername

computername

To validate a computer name:

$ serversetup -verifyComputername

computername

Hostname

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

To display the server’s local host name:

$ serversetup -getHostname

To change the server’s local host name:

$ sudo serversetup -setHostname

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

hostname

Chapter 6 Setting Network Preferences 79

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 automatically 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. Use the serversetup tool to view or change the Bonjour name.

To display the server’s Bonjour name:

$ serversetup -getBonjourname

To change the server’s Bonjour name:

$ sudo serversetup -setBonjourname

bonjourname

The command displays 0 if the name was changed.

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

Managing Preference Files and the Configuration Daemon

The various sets of configuration information that 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. This storage is in the form of key-value pairs. The key is a description of what is being stored, and the value is the actual 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 trying to debug 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), perform the following:

$ scutil

> open

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

> list

80 Chapter 6 Setting Network Preferences

configd:

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 actual state of the computer. File indicates stored information as of the last time the configuration file was updated.

Using scutil, you can view data in the keys. First you must get the data, and then you can 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, such that if its state changes, scutil will alert you. To quit the scutil session, enter quit at the prompt.

> quit

You can also manage system configuration parameters from within scutil using the

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

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

To set the hostname of a system:

$ sudo scutil --set HostName

mycomputer.mac.com

Parameter Description

mycomputer.mac.com

This is the new hostname value you wish to set.

To get the hostname of a system:

$ scutil --get HostName

mycomputer.mac.com

See the scutil man page for more information or enter help at the scutil prompt.

Changing Network Locations

A network location contains all of the 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 may need to switch between locations quickly. scselect allows you to access these configuration sets or locations.

Chapter 6 Setting Network Preferences 81

To view the current locations:

$ scselect

The computer will respond 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 listed that you want to switch to:

$ scselect 1

In this example, the network location will switch to AirPort.

82 Chapter 6 Setting Network Preferences

7 Working with Disks and Volumes

In this chapter you will find commands that are used to initialize and test disks and volumes.

Computers use disks and partitions to store and organize data. This chapter covers the commands that are 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 would be called /dev/disk0s1, the second partition would be /dev/disk0s2, and so on.

Although Mac OS X Server assigns a device name to each device, the files on a particular device are not accessed in this way. A virtual file system is created where all files on all devices appear to exist under a single hierarchy. This sets one root folder and every file exisiting 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 would like those files to appear. The folder given to the operating system is the mount point. Different volumes on a computer may 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:

Â mount_afp for Apple File Protocol (AppleShare) volumes

Â mount_cd9660 for ISO 9660 volumes

Â mount_cddafs for CD Digital Audio format (CDDA) volumes

Â mount_hfs for Apple Hierarchical File System (HFS) volumes

Â mount_msdos for PC MS-DOS volumes

Â mount_nfs for Network File System (NFS) volumes

Â mount_smbfs for Server Message Block (SMB/CIFS) volumes

Â mount_udf for Universal Disk Format (UDF) volumes

Â mount_webdav for Web-based Distributed Authoring and Versioning (WebDAV )

volumes

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

file system tree at the point node. See the related man pages for more information.

To view a list of currently mounted file systems:

$ sudo mount

To mount a network folder:

$ mount /dev/

returns the value 0 if the mount succeeded.

mount

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

returns the value 0 if the umount succeeded. See the umount man page for

umount

more information.

84 Chapter 7 Working with Disks and Volumes

Displaying Disk Information

The df tool located in /bin is designed to display free disk space. In addition, df is a useful way to find out what your current disk partitions are, how much space each one takes up, which block each partition starts on, which device file is associated with each partition, and where each partition is mounted.

To display disk information:

$ df

The computer will respond 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.

diskspacemonitor is disabled by default.

To enable diskspacemonitor:

$ sudo diskspacemonitor on.

You may be prompted for your password. See the diskspacemonitor man page for more information.

Chapter 7 Working with Disks and Volumes 85

When enabled, diskspacemonitor uses information in a configuration file to determine when to execute alert and recovery scripts for reclaiming disk space:

Â The configuration file is /etc/diskspacemonitor/diskspacemonitor.conf. It lets you

specify how often you want to monitor disk space, and specify 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. See the comments in the file for additional information.

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

See the comments in the script and configuration files for more information about these files.

Â If you want 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 will be 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

Three predefined scripts are executed automatically, in order to reclaim space used on your server for log files generated by:

Â Apple file service

Â Windows service

Â Web service

Â Web performance cache

Â Mail service

Â Print service

86 Chapter 7 Working with Disks and Volumes

The scripts use values in the following configuration files to determine whether and how to reclaim space:

Â 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 is intended to run weekly, but is

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

Â The script /etc/periodic/monthly/600.monthly.server is intended to run monthly, but

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

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

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

There are several additional parameters you can specify. See comments in the configuration files for information about all the parameters and how to set them. The scripts ignore all 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.

Erasing, Modifying, Verifying, and Repairing Disks

You can use diskutil to erase, modify, verify, and repair disks. This command provides functionality that overlaps with the functionality of pdisk, newfs_hfs, and disktool. For example, you can use both diskutil and pdisk to partition a disk. However, unlike

pdisk, which lets you partition tables at their most basic level by setting the exact 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 87

To list the disks currently 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 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 mount a drive:

$ diskutil mountDisk

Parameter Description

diskvol

Device name.

To erase and repartition a disk:

$ diskutil partitionDisk

part1Size

disk numberOfPartitions part1Format part1Name

Parameter Description

disk

numberOfPartitions

part1Format

part1Name

part1Size

Device name (such as disk0).

HFS+ or UFS.

Can be either 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 may be times when you would want to set the file system to be case sensitive. You can use the diskutil tool to format a drive for case-sensitive HFS+.

Note: Volumes you format as case-sensitive HFS+ are also journaled.

88 Chapter 7 Working with Disks and Volumes

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

See the diskutil man page for more options and information about repairing and modifying disks.

Partitioning and Formatting Disks

Disk partitions are subsdivisions of a disk to which you apply operating-system–specific formatting.

Partitioning a Disk

You can use pdisk, located in /usr/sbin, to edit the disk partition table. You can initialize the disk, create partitions, and delete partitions. The pdisk tool is menu-driven, which means that once it is launched, you are prompted to enter a pdisk command. You can find the commands by typing ? at the pdisk prompt. The following are some of the more useful commands:

Command Description

L Lists the partition maps of all the drives. pdisk lists all the

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, you have to use the raw device file as the argument.

Once 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 new partition. There are two partition types, Apple_HFS

and Apple_UFS.

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

all edits and modifications are only in memory and not yet implemented.

pdisk does not support the Intel/DOS partitioning scheme supported by fdisk. See the fdisk man page for more information about DOS partitions.

Chapter 7 Working with Disks and Volumes 89

After a partition has been created on a device, the partition needs to be formatted before the computer will be able to store data on the device. Formatting a disk partition creates the volume and sets the file system.

Labeling a Disk

Once a disk is formatted, it needs to 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 be writable by anne:

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

name=anne owner-mode=0644

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

$ disklabel -properties /dev/rdisk1s1

See the disklabel man page for more information about creating disk labels.

Formatting a Disk

You can use newfs, located in /sbin, to create a new volume. 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. Extreme care should be taken to ensure a successful format when modifying the settings beyond the default. Before running newfs, the disk must be labeled using the disklabel tool.

To fomat a disk:

$ newfs

See the newfs man page for options in detail.

To format a disk to HFS+, you would need to use the newfs_hfs tool located in /sbin:

$ newfs_hfs

See the newfs_hfs man page for more information.

Checking for Disk Problems

You can use the diskutil or fsck tool (fsck_hfs for HFS volumes) to check the physical condition and file system integrity of a volume. See the related man pages for more information.

90 Chapter 7 Working with Disks and Volumes

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.

Checking to See If Journaling is Enabled

You can use the mount tool to see if journaling is enabled on a volume.

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 an Existing Volume

You can use the diskutil tool to enable journaling on a volume without affecting existing files on the volume.

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

enable journaling.

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

Chapter 7 Working with Disks and Volumes 91

/dev/disk0s9 on / (local, journaled) /dev/disk0s10 on /Volumes/OS 9.2.2 (local, journaled)

Enabling Journaling When You Erase a Disk

You can use the newfs_hfs tool to set up and enable journaling when you erase a disk.

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

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. Whenever 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 all of the applications using Spotlight, and changes are reflected dynamically to the user.

The Spotlight store retains information that is extracted into two seperate 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 as root using your favorite editor. For example:

$ sudo pico /etc/hostconfig

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

You can also set the value of the spotlight parameter to

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

92 Chapter 7 Working with Disks and Volumes

-NO- as follows:

3 Restart your server.

To enable Spotlight on your server:

1 Open /etc/hostconfig for editing as root.

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

You can also 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, which is similar to the ls tool, lists all of the metadata attributes for a specific file.

To view the metadata of a file:

$ mdls

The computer will respond with something similar to the following output:

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

filename> -------------

filename

To perform a Spotlight search, use 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

Chapter 7 Working with Disks and Volumes 93

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

To enable indexing on a volume:

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

$ sudo mdutil -i on

volume

To disable indexing on a volume:

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

$ sudo mdutil -i off

volume

See the mdutil man page for more information.

Managing RAID Volumes

In addition to standard drive management options, diskutil has the ability to manage software RAID volumes.

To create a RAID set:

$ diskutil createRAID

Parameter Description

type

setName

volType

disks

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.

To get a list of 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

Device file.

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

$ diskutil enableRAID

Parameter Description

mirror

device

94 Chapter 7 Working with Disks and Volumes

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.

Specifies the slice number to replace.

Specifies the mirror source.

Specifies the repaired mirror destination.

Note: Xsan RAID volumes have their own set of commands, which are described in an appendix of the Xsan administrators guide. See the appendix for informatian about the

megaraid tool, used for managing a PCI RAID card.

Imaging and Cloning Volumes Using ASR

You can use Apple Software Restore (ASR) to copy a disk image onto a volume or to prepare existing 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 is already there, and block copies, which restore entire disk images. The asr tool doesn’t create the disk images. You can use hdiutil to create disk images from volumes or folders.

You must run ASR as root. 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 “To create an image

from a folder:” on page 177.

5 Mount the disk image.

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

man page for examples of what files to remove.

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

image.

$ hdiutil convert -format UDZO

pathtoimage

-o

compressedimage

8 Prepare the image for duplication by adding checksum information:

$ sudo asr -imagescan

compressedimage

Chapter 7 Working with Disks and Volumes 95

To restore a volume from an image:

$ sudo asr -source

compressedimage

-target

targetvolume

-erase

See the asr man page for command syntax, limitations, and image preparation instructions.

96 Chapter 7 Working with Disks and Volumes

8 Working with Users and Groups

In this chapter you will find commands you can use 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. There are several command-line tools that facilitate working with the directory domains that hold these accounts.

Understanding Accounts

There are three kinds of accounts you can set up with Workgroup Manager: user accounts, group accounts, and computer lists. 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 perhaps to personalize the user’s environment. Along with accounts you create, Mac OS X Server has some 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 administrator-controlled 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 Accounts

A user account stores data that Mac OS X Server needs to validate the user’s identity and provide services for the user. This section provides an overview of user accounts.

User accounts, as well as group accounts and computer lists, 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, a NetInfo domain, or other read/write directory domain) or it can reside on a non-Apple server (for example, a non-Apple LDAP or Active Directory server). This section describes how to administer user accounts stored in various kinds of directory domains.

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 info about or change the settings of a particular server. Domain administrator privileges determine the extent to which the user can view or change the account settings for users, groups, and computer lists in the directory domain.

You can use the serversetup tool to create local administrator users for a server. The

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

path, so you have to provide the path to it. You also have to run it as root.

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

To create a local administrator user account:

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

shortname password

The name, short name, and password must be entered 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.

To create an local administrator user with a specific UID:

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

shortname password uid

The name, short name, password, and UID must be entered 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, short name, or UID is already in use or if the UID you specified is less than 100.

98 Chapter 8 Working with Users and Groups

fullname

To create an local administrator user with a specific UID and home folder:

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

shortname password uid homedirpath

fullname

The name, short name, password, and UID must be entered 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, short name, or UID is already in use or if the UID you specified is less than 100.

Creating a Domain Administrator User Account

In order to create a domain administrator user account for a networked directory, you need to already have a domain administrator user account.

Before starting, you should already have a nonadministrator user account that you want to give domain administrator privileges to. For instructions on creating nonadministrator user accounts, see “Creating a Nonadministrator User Account” on page 100.

To create a domain administrator user account:

1 Start the

source of directory service data. Use the dscl tool to create a domain administrator user account.

$ dscl localhost

In interactive mode, the dscl tool displays the current folder in the directory domain (not the current folder in the file system) and a “>” character as a prompt.

2 Once connected to the directory, choose the directory domain. Change the current

folder to LDAPv3/ipaddress/Groups.

> cd LDAPv3/

Replace directory domain, enter cd /NetInfo/root/Groups at the prompt.

3 Create an administrator user.

>append admin Member

This command creates an administrator user, but it doesn’t add the GUID (globally unique identifier) of the administrator user to the group account.

4 Add the administrator user to the group.

> append admin GroupMembers

Replace

5 Quit the

>quit

dscl tool in interactive mode, specifying the computer you are using as the

ipaddress

guid

with the globally unique identifier.

dscl tool.

/Groups

with the IP address of your directory server. If using a NetInfo

adminusername

guid

Chapter 8 Working with Users and Groups 99

To find the GUID of the administrator user:

> cd /Users/

> read

adminusername

GeneratedUID

Checking a User’s Administrator Privileges

Use the serversetup tool to verify the administrator privileges of a specific user.

To see if a user is a server administrator:

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

shortname

The command displays a 0 if the user is an administrator, or a 1 if the user is not an administrator.

Creating a Nonadministrator User Account

You can create new user accounts by using dscl and other tools. When you create a user account from the command line, you must also set values for basic attributes of the user account, such as the short name, long name, user ID, and home folder location.

To create a nonadministrator user account:

1 Identify an unused user ID. Each user on a server must have a unique user ID. Use the

dscl tool to display lists of assigned user IDs and group IDs.

$ dscl

Replace /LDAPv3/ipaddress with the location of your directory domain (the way it is displayed in the search path in Directory Access). If you connect to a NetInfo domain, replace UniqueID with uid.

After you enter the command, the dscl tool displays a list of assigned user ID numbers, similar to the following output. These user IDs are for computer accounts that are included with Mac OS X Server:

-2 0 1 99 25 26 27 70 71 75 76 77 78 79 501

/LDAPv3/ipaddress

-list /Users UniqueID| awk '{print $2}' | sort -n

100 Chapter 8 Working with Users and Groups

Apple MAC OS X SERVER User 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

Getting Documentation Updates

Getting Additional Information

1 Executing Commands

Opening Terminal

Specifying Files and Folders

Modifying Flow Control

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 Within 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 Secure Shell

How SSH Works

Password-Less Logins Using SSH Keys

Updating SSH Key Fingerprints

What is an SSH Man-in-the-Middle Attack?

Controlling Access to SSH Service

Connecting to a Remote Computer

Using SSH

Using Telnet

Installing Server Software

Locating Computers for Installation

Specifying the Target Computer Volume

Preparing the Target Volume for a Clean Installation

Installing from Multiple CDs

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

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 the Energy Saver Settings

Viewing or Changing Sleep Settings

Viewing or Changing Automatic Restart Settings

Changing the Power Management Settings

Viewing or Changing the Startup Disk Settings

Viewing or Changing the Sharing Settings

Viewing or Changing Remote Login Settings

Viewing or Changing Apple Event Response