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

+ 274 hidden pages

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