Apple MAC OS X SERVER User Manual

Mac OS X Server

Command-Line Administration For Version 10.4 or Later Second Edition

K Apple Computer, Inc.

© 2006 Apple Computer, Inc. All rights reserved.

The owner or authorized user of a valid copy of Mac OS X Server software may reproduce this publication for the purpose of learning to use such

software. No part of this publication may be reproduced or transmitted for commercial purposes, such as selling copies of this publication or for providing paid-for support services.

Every effort has been made to ensure that the information in this manual is accurate. Apple 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

Contents

Preface	15	About This Guide
	16	Using This Guide
	16	Understanding Notation Conventions
	16	Summary
	16	Commands and Other Terminal Text
	16	Command Parameters and Options
	17	Default Settings
	17	Commands Requiring Root Privileges
	18	Getting Documentation Updates
	18	Getting Additional Information
Chapter 1	21	Executing Commands
	21	Opening Terminal
	22	Specifying Files and Folders
	23	Modifying Flow Control
	23	Redirecting Input and Output
	24	Using Environment Variables
	25	Executing Commands and Running Tools
	26	Correcting Typing Errors
	26	Repeating Commands
	26	Including Paths Using Drag and Drop
	26	Searching for Text Within a File
	26	Commands Requiring Root Privileges
	27	Terminating Commands
	27	Scheduling Tasks
	28	Sending Commands to a Remote Computer
	28	Viewing Command Information
Chapter 2	31	Connecting to Remote Computers
	31	Understanding Secure Shell
	31	How SSH Works
	32	Password-Less Logins Using SSH Keys
	33	Updating SSH Key Fingerprints

3

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

34Controlling Access to SSH Service

35Connecting to a Remote Computer

35Using SSH

36Using Telnet

Chapter 3	37	Installing Server Software and Finishing Basic Setup
	37	Installing Server Software
	38	Locating Computers for Installation
	39	Specifying the Target Computer Volume
	39	Preparing the Target Volume for a Clean Installation
	40	Installing from Multiple CDs
	40	Restarting After Installation
	40	Automating Server Setup
	41	Creating a Configuration File
	43	Working with an Encrypted Configuration File
	43	Customizing a Configuration File
	47	Storing a Configuration File in an Accessible Location
	47	Configuring the Server Remotely from the Command Line
	48	Changing Server Settings
	48	Using the serversetup Tool
	48	Using the serveradmin Tool
	49	General and Network Preferences
	49	Viewing, Validating, and Setting the Software Serial Number
	50	Updating Server Software
	51	Moving a Server
Chapter 4	53	Restarting or Shutting Down a Computer
	53	Restarting a Computer
	53	Automatic Restart
	54	Changing a Remote Computer’s Startup Disk
	54	Shutting Down a Computer
	54	Manipulating Open Firmware NVRAM Variables
	55	Monitoring and Restarting Critical Services
Chapter 5	57	Setting General System Preferences
	57	Viewing or Changing the Computer Name
	57	Viewing or Changing the Date and Time
	58	Viewing or Changing the System Date
	58	Viewing or Changing the System Time
	58	Viewing or Changing the System Time Zone
	58	Viewing or Changing Network Time Server Usage
	59	Viewing or Changing the Energy Saver Settings

4	Contents

59 Viewing or Changing Sleep Settings

59Viewing or Changing Automatic Restart Settings

60Changing the Power Management Settings

60Viewing or Changing the Startup Disk Settings

61Viewing or Changing the Sharing Settings

61Viewing or Changing Remote Login Settings

61Viewing or Changing Apple Event Response

61Viewing or Changing the International Settings

62Viewing and Changing the Login Settings

Chapter 6	63	Setting Network Preferences
	63	Configuring Network Interfaces
	64	Managing Network Interface Information
	64	Viewing Port Names and Hardware Addresses
	64	Viewing or Changing MTU Values
	65	Viewing or Changing Media Settings
	65	Managing Network Port Configurations
	65	Creating or Deleting Port Configurations
	65	Activating Port Configurations
	65	Changing Configuration Precedence
	66	Managing TCP/IP Settings
	66	Changing a Server’s IP Address
	67	Viewing or Changing IP Address, Subnet Mask, or Router Address
	69	Viewing or Changing DNS Servers
	70	Enabling TCP/IP
	70	Working with VLANs
	70	IEEE 802.3ad Ethernet Link Aggregation
	72	Managing AppleTalk Settings
	72	Managing SNMP Settings
	73	Installing SNMP
	73	Starting SNMP
	74	Configuring SNMP
	75	Collecting SNMP Information from the Host
	76	Managing Proxy Settings
	76	Viewing or Changing FTP Proxy Settings
	77	Viewing or Changing Web Proxy Settings
	77	Viewing or Changing Secure Web Proxy Settings
	77	Viewing or Changing Streaming Proxy Settings
	77	Viewing or Changing Gopher Proxy Settings
	78	Viewing or Changing SOCKS Firewall Proxy Settings
	78	Viewing or Changing Proxy Bypass Domains
	78	Managing AirPort Settings
	79	Managing the Computer, Host, and Bonjour Names

Contents	5

79 Computer Name

79Hostname

80Bonjour Name

80Managing Preference Files and the Configuration Daemon

81Changing Network Locations

Chapter 7	83	Working with Disks and Volumes
	83	Understanding Disks, Partitions, and the File System
	83	Mounting and Unmounting Volumes
	84	Mounting Volumes
	84	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

98Creating a Local Administrator User Account for a Server

99Creating a Domain Administrator User Account

100Checking a User’s Administrator Privileges

100 Creating a Nonadministrator User Account

103Retreiving a User’s GUID

103Removing a User Account

104Revoking a User’s Right to Access His or Her Account

106Checking a Server User’s Name, UID, or Password

6	Contents

107Modifying a User Account

108Creating a Mobile User Account

109Managing Home Folders

110Administering Group Accounts

111Creating a Group Account

112Removing a Group Account

113Adding a User to a Group

114Removing a User from a Group

116Creating and Deleting Nested Group

117Editing Group Records

118Creating a Group Folder

118Viewing the Workgroup a User Selects at Login

119Importing Users and Groups

120Creating a Character-Delimited User Import File

123Setting Permissions

123Viewing Permissions

124Setting the umask for Individual Users

125Changing Permissions

126Changing the Owner

126Changing the Group

126Securing System Accounts

126Securing Initial System Accounts

127Securing the Root Account

127Restricting Use of the sudo Tool

128Securing Single-User Boot

129Setting Password Policy

131Finding User Account Information

Chapter 9	133	Working with File Services
	133	Managing Share Points
	134	Listing Share Points
	134	Creating a Share Point
	135	Modifying a Share Point
	136	Disabling a Share Point
	136	Managing the AFP Service
	136	Starting and Stopping AFP Service
	136	Checking AFP Service Status
	136	Viewing AFP Settings
	137	Changing AFP Settings
	137	List of AFP Settings
	140	List of AFP serveradmin Commands
	141	Listing Connected Users
	142	Sending a Message to AFP Users

Contents	7

142Disconnecting AFP Users

143Canceling a User Disconnect

144Listing AFP Service Statistics

145Viewing AFP Log Files

146Managing the NFS Service

146Starting and Stopping NFS Service

146Checking NFS Service Status

146Viewing NFS Service Settings

146Changing NFS Service Settings

147Managing the FTP Service

147Starting FTP Service

147Stopping FTP Service

147Checking FTP Service Status

147Viewing FTP Service Settings

148Changing FTP Service Settings

148List of FTP Service Settings

150List of FTP serveradmin Commands

150Viewing the FTP Transfer Log

150Checking for Connected FTP Users

151Managing the SMB/CIFS Service

151Starting and Stopping SMB/CIFS Service

151Checking SMB/CIFS Service Status

151Viewing SMB/CIFS Service Settings

152Changing SMB/CIFS Service Settings

152List of SMB/CIFS Service Settings

155List of SMB/CIFS serveradmin Commands

155Listing SMB/CIFS Users

156Disconnecting SMB/CIFS Users

156Listing SMB/CIFS Service Statistics

157Updating Share Point Information

157Viewing SMB/CIFS Service Logs

157Managing ACLs

158Using 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
	172	Checking NetBoot Service Status
	172	Viewing NetBoot Settings
	172	Changing NetBoot Settings
	173	Changing General Netboot Service Settings
	173	Storage Record Array
	174	Filters Record Array
	174	Image Record Array
	175	Port Record Array
	176	Working with System Images
	176	Updating an Image
	176	Booting from an Image
	176	Using hdiutil to Work with System Images
	177	Using asr to Restore System Images
	177	Imaging Multiple Clients Using Multicast asr
	178	Choosing a Boot Device Using systemsetup
Chapter 12	179	Working with the Mail Service
	179	Understanding the Mail Service
	179	Postfix Agent
	180	Cyrus
	180	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
	182	Mail Service Settings
	194	Mail serveradmin Commands
	194	Listing Mail Service Statistics
	195	Viewing the Mail Service Logs
	196	Backing Up the Mail Files
	197	Reconstructing the Mail Database
	198	Setting Up SSL for Mail Service
	198	Generating a CSR and Creating a Keychain

Contents	9

200 Obtaining an SSL Certificate

200Importing an SSL Certificate into the Keychain

200Accessing the Server Certificates

201Creating a Password File

202Configuring Mailboxes

202Enabling Sieve Scripting

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

225Checking the Status of DNS Service

225Viewing DNS Service Settings

226Changing DNS Service Settings

226DNS Service Settings

226List of DNS serveradmin Commands

226Viewing the DNS Service Log

226Listing DNS Service Statistics

227Configuring IP Forwarding

227Managing the Firewall Service

228Firewall Startup

228Starting and Stopping Firewall Service

228Checking the Status of Firewall Service

228Viewing Firewall Service Settings

229Changing Firewall Service Settings

229Firewall Service Settings

230Defining Firewall Rules

233 ipfilter Rules Array

233Firewall serveradmin Commands

234Viewing Firewall Service Log

234Using Firewall Service to Simulate Network Activity

234Managing the NAT Service

235Starting and Stopping NAT Service

235Checking the Status of NAT Service

235Viewing NAT Service Settings

235Changing NAT Service Settings

236NAT Service Settings

236NAT serveradmin Commands

237Port Mapping

237Viewing the NAT Service Log

238Managing the VPN Service

238Starting and Stopping VPN Service

238Checking the Status of VPN Service

238Viewing VPN Service Settings

239Changing VPN Service Settings

239List of VPN Service Settings

242List of VPN serveradmin Commands

242Viewing the VPN Service Log

243Site-to-Site VPN

243Configuring Site-to-Site VPN

244Adding a VPN Keyagent User

245Setting Up IP Failover

245IP Failover Prerequisites

245IP Failover Operation

Contents	11

246Enabling IP Failover

247Configuring IP Failover

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

Preface

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.

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.

15

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 you must replace with a value
[...]	A parameter that may be repeated
<angle brackets>	A displayed value that depends on your server configuration

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

In this example, you replace hh with the hour and mm with the minute, as shown in the previous example.

Optional Parameters

If a parameter is not required, it appears in square brackets. For example:

$ doit [-w later]

To use the command in this example, enter 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	Install Mac OS X Server and set it up for the first time.
		for Version 10.4 or Later
		Mac OS X Server Upgrading and	Use data and service settings that are currently being used on
		Migrating to Version 10.4 or Later	earlier versions of the server.
		Mac OS X Server User	Create and manage users, groups, and computer lists. Set up
		Management for Version 10.4 or	managed preferences for Mac OS X clients.
		Later
18		Preface About This Guide

...This guide

tells you how to:

Mac OS X Server File Services 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.

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

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

Mac OS X Server System Imaging	Use NetBoot and Network Install to create disk images from which
and Software Update	Macintosh computers can start up over the network. Set up a
Administration for Version 10.4 or	software update server for updating client computers over the
Later	network.
Mac OS X Server Mail Service	Set up, configure, and administer mail services on the server.
Administration for Version 10.4 or
Later

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

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

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

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

Mac OS X Server Open Directory	Manage directory and authentication services.
Administration for Version 10.4 or
Later
Mac OS X Server QuickTime	Set up and manage QuickTime streaming services.
Streaming Server Administration
for Version 10.4 or Later

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

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

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

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

Mac OS X Server Java Application Server Administration For Version 10.4 or Later

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

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

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

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

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

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

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	Manage computational Xserve clusters using the Xgrid application.
Administration for Version 10.4 or
Later
Mac OS X Server	Interpret terms used for server and storage products.
Glossary: Includes Terminology for
Mac OS X Server, Xserve, Xserve
RAID, and Xsan

20	Preface About This Guide

Executing Commands	1

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.

21

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 PATH

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.

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

1

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 1

Built-in Ethernet

or

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

server:/ anne$ PATH="$PATH:/System/Library/ServerSetup" server:/ anne$ serversetup -getAllPort

1

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

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

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
45	8	*	*	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 is the topic you want to find information about. The man page contains detailed information about the command, its options, parameters, and proper use. For help using the man command, enter:

$ man man

If 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

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