Introduction to Command-Line Administration, Mac Leopard v10.6

8/7/2019 Introduction to Command-Line Administration, Mac Leopard v10.6

1/58

Mac OS X Server

Introduction to Command-LineAdministration

Version 10.6 Snow Leopard


2/58

Apple Inc.K

2009 Apple Inc. All rights reserved.

Under the copyright laws, this manual may notbe copied, in whole or in part, without the written

consent of Apple.

The Apple logo is a trademark of Apple Inc., registered

in the U.S. and other countries. Use of the keyboard

Apple logo (Option-Shift-K) for commercial purposes

without the prior written consent of Apple may

constitute trademark infringement and unfair

competition in violation of federal and state laws.

Every eort has been made to ensure that the

information in this manual is accurate. Apple is not

responsible for printing or clerical errors.

Apple

1 Innite Loop

Cupertino, CA 95014

408-996-1010

www.apple.com

Apple, the Apple logo, AppleScript, FireWire, Keychain,Leopard, Mac, Mac OS, Quartz, Safari, Xcode, Xgrid, and

Xserve are trademarks of Apple Inc., registered in the

U.S. and other countries.

Apple Remote Desktop, Finder, and Snow Leopard are

trademarks of Apple Inc.

AIX is a trademark of IBM Corp., registered in the U.S.and other countries, and is being used under license.

The Bluetooth word mark and logos are registered

trademarks owned by Bluetooth SIG, Inc. and any use

of such marks by Apple is under license.

This product includes software developed by the

University of California, Berkeley, FreeBSD, Inc.,

The NetBSD Foundation, Inc., and their respective

contributors.

Java and all Java-based trademarks and logos

are trademarks or registered trademarks of Sun

Microsystems, Inc. in the U.S. and other countries.

PowerPC and the PowerPC logo are trademarks

of International Business Machines Corporation, used

under license therefrom.

UNIX is a registered trademark of The Open Group.

Other company and product names mentioned hereinare 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-1398/2009-08-01
http://www.apple.com/http://www.apple.com/


3/58

5 Preface: About This Guide5 Whats in This Guide

6 Using Onscreen Help

7 Documentation Map

7 Viewing PDF Guides Onscreen

8 Printing PDF Guides

8 Getting Documentation Updates

9 Getting Additional Information

10 Chapter 1: Introduction to the Command-Line Environment11 The Command-Line Environment

11 UNIX

11 The Shell

11 Accessing the Shell

11 Local Access

13 Remote Access

13 Closing the Shell

13 Executing Commands and Running Tools

14 Terminating Commands

15 Specifying Files and Folders

16 Commands Requiring Root or Administrator Privileges

16 Getting Help for Command-Line Tools

16 Using Help Built Into Command-Line Tools

17 Using Man Pages

18 Using Info Pages

19 Chapter 2: Using the Command-Line Shell Interactively19 Standard Pipes

20 Redirecting Input and Output

20 Correcting Typing Errors

21 Using Environment Variables

22 Repeating Commands22 Including Paths Using Drag and Drop

3

Contents


4/58

4 Contents

23 Chapter 3: Scripting the Command Line23 What is a Shell Script?

24 Monitoring and Restarting Critical Services with launchd

25 Scheduling a Shell Script to Run at Specic Times

26 Scheduling tasks with launchd

27 Chapter 4: Connecting to Remote Computers27 SSH

27 How SSH Works

28 Generating Key Pairs for Key-Based SSH Connections

30 Updating SSH Key Fingerprints

31 An SSH Man-in-the-Middle Attack

32 Controlling Access to SSH Service

32 Connecting to a Remote Computer Using SSH

33 Apple Remote Desktop

33 X11

34 Chapter 5: Common Command-Line Tasks34 Editing Conguration Files

34 Text Editors36 Saving Text Files for UNIX Execution

36 Editing Property Lists

39 Moving and Copying Files

40 Compressing and Uncompressing File Archives

40 Viewing File Contents

41 Searching for Text in a File

41 Backing Up and Restoring

42 Chapter 6: Accessing Apple Hardware from the Command Line42 Restarting a Computer

42 Automatic Restart

43 Changing a Remote Computers Startup Disk

43 Shutting Down a Computer

43 Shutting Down While Leaving the Computer On and Powered

44 Manipulating Open Firmware NVRAM Variables44 Remotely Controlling the Xserve Front Panel

45 Appendix: Command-Line Tools Specic to Mac OS X45 Section 1 Man Pages

50 Section 4 Man Pages




56 Index


5/58

5

This guide provides a starting point for administering

Mac OS X Server using command-line tools.Introduction to Command-Line Administration supplements the information in the other

advanced administration guides. It provides information useful to building workows

and remote administration practices beyond the use of Server Admin and Workgroup

Manager. The information in this guide isnt specic to any particular technology, but

is relevant to many server technologies.

Whats in This GuideThis guide includes the following sections:

Chapter 1, Introduction to the Command-Line Environment, provides an overview

of the command-line environment in Mac OS X Serverfor administrators who

are new to the command line or who are coming from the command line on other

platforms.

Chapter 2, Using the Command-Line Shell Interactively, explains how shells work

and provides information about the shells in Mac OS X Server.

Chapter 3, Scripting the Command Line, explains what shell scripts are and why

you would use them in Mac OS X Server.

Chapter 4, Connecting to Remote Computers, provides information about various

ways to access remote computers.

Chapter 5,Common Command-Line Tasks, provides examples of frequently usedcommand-line tasks.

P7-8Chapter 6, Accessing Apple Hardware from the Command Line, provides

information about accessing hardware-specic Mac attributes from the command line.

Appendix , Command-Line Tools Specic to Mac OS X, provides a list of the

command-line tools that are unique to Mac OS X and Mac OS X Server.

Note: Because Apple periodically releases new versions and updates to its software,

images shown in this book may be dierent from what you see on your screen.

PrefaceAbout This Guide


6/58

6 Preface About This Guide

Using Onscreen HelpYou can get task instructions onscreen in Help Viewer while youre managing

Snow Leopard Server. You can view help on a server, or on an administrator computer.

(An administrator computer is a Mac OS X computer with Snow Leopard Server

administrator software installed on it.)

To get the most recent onscreen help for Mac OS X Snow Leopard Server:

Open Server Admin or Workgroup Manager and then:m

Use the Help menu to search for a task you want to perform.

Choose Help > Server Admin Help or Help > Workgroup Manager Help to browse

and search the help topics.

The onscreen help contains instructions taken fromAdvanced Server Administrationand the other administration guides.

To see the most recent server help topics:

Make sure the server or administrator computer is connected to the Internet whilem

youre getting help.

Help Viewer automatically retrieves and caches the most recent server help topics

from the Internet. When not connected to the Internet, Help Viewer displays cachedhelp topics.


7/58

Preface About This Guide 7

Documentation MapSnow Leopard has a suite of guides that cover management of individual services.

Each service may be dependent on other services for maximum utility. The

documentation map below shows some related documentation that you may

need in order to fully congure your desired service to your specications. You canget these guides in PDF format from the Mac OS X Server Resources website:

http://www.apple.com/server/macosx/resources/

ServerAdministration Guides

Each guide coversusing Server Adminand command-linetools to configure

advanced settings for aparticular service.

Introduction toCommand-LineAdministration

Explains how to useUNIX shell commands toconfigure and manage

servers and services.

InformationTechnologies

Dictionary

Provides onscreendefinitions of

server terminology.

Viewing PDF Guides OnscreenWhile reading the PDF version of a guide onscreen:

Show bookmarks to see the guides outline, and click a bookmark to jump to the

corresponding section.

Search for a word or phrase to see a list of places where it appears in the document.

Click a listed place to see the page where it occurs.

Click a cross-reference to jump to the referenced section. Click a web link to visit the

website in your browser.
http://www.apple.com/server/macosx/resources/http://www.apple.com/server/macosx/resources/


8/58

8 Preface About This Guide

Printing PDF GuidesIf you want to print a guide, you can take these steps to save paper and ink:

Save ink or toner by not printing the cover page.

Save color ink on a color printer by looking in the panes of the Print dialog for

an option to print in grays or black and white.

Reduce the bulk of the printed document and save paper by printing more than

one page per sheet of paper. In the Print dialog, change Scale to 115% (155%

for Getting Started). Then choose Layout from the untitled pop-up menu. If your

printer supports two-sided (duplex) printing, select one of the Two-Sided options.

Otherwise, choose 2 from the Pages per Sheet pop-up menu, and optionally choose

Single Hairline from the Border menu. (If youre using Mac OS X v10.4 or earlier,

the Scale setting is in the Page Setup dialog and the Layout settings are in the

Print dialog.)

You may want to enlarge the printed pages even if you dont print double sided,

because the PDF page size is smaller than standard printer paper. In the Print dialog

or Page Setup dialog, try changing Scale to 115% (155% for Getting Started, which has

CD-size pages).

Getting Documentation UpdatesPeriodically, Apple posts revised help pages and new editions of guides. Some revised

help pages update the latest editions of the guides.

To view new onscreen help topics for a server application, make sure your server or

administrator computer is connected to the Internet and click Latest help topics

or Staying current in the main help page for the application.

To download the latest guides in PDF format, go to the Mac OS X Server Resources

website at:

www.apple.com/server/macosx/resources/

An RSS feed listing the latest updates to Mac OS X Server documentation and

onscreen help is available. To view the feed use an RSS reader application, such

as Safari or Mail:

feed://helposx.apple.com/rss/snowleopard/serverdocupdates.xml
http://www.apple.com/server/macosx/resources/http://feed//helposx.apple.com/rss/snowleopard/serverdocupdates.xmlhttp://feed//helposx.apple.com/rss/snowleopard/serverdocupdates.xmlhttp://www.apple.com/server/macosx/resources/


9/58

Preface About This Guide 9

Getting Additional InformationFor more information, consult these resources:

Read Me documentsget important updates and special information. Look for them

on the server discs.

Mac OS X Server website (www.apple.com/server/macosx/)enter the gateway to

extensive product and technology information.

Mac OS X Server Support website (www.apple.com/support/macosxserver/)access

hundreds of articles from Apples support organization.

Apple Discussions website (discussions.apple.com/)share questions, knowledge,

and advice with other administrators.

Apple Mailing Lists website (www.lists.apple.com/)subscribe to mailing lists so youcan communicate with other administrators using email.

Apple Training and Certifcation website (www.apple.com/training/ )hone

your server administration skills with instructor-led or self-paced training, and

dierentiate yourself with certication.
http://www.apple.com/server/macosx/http://www.apple.com/support/macosxserver/http://discussions.apple.com/http://www.lists.apple.com/http://www.apple.com/training/http://www.apple.com/training/http://www.lists.apple.com/http://discussions.apple.com/http://www.apple.com/support/macosxserver/http://www.apple.com/server/macosx/


10/58

10

Use this chapter to determine when to use command-linetools and to understand the fundamentals of how touse them.

A command-line interface (CLI) is an alternative to graphical applications for

interacting with and controlling your computer. Mac OS X Server provides graphical

applicationsprimarily, Server Admin and Workgroup Managerto address common

administration tasks. There are situations, though, where using a command-line

interface might be appropriate. These situations include:

Conguring advanced options that arent supported by the graphical applications.

Conguring remotely from a computer that doesnt have the Server Admin tools

installedfor example, a computer with Windows, Linux, or another UNIX-based

operating system.

Performing tasks that are repetitive or that need to be run at predened times.

Editing text les, usually in order to change advanced conguration settings and

preferences.

The primary way to access the CLI in Mac OS X is with the Terminal application. Other

ways to access the CLI are discussed in Accessing the Shell on page 11, and

in Chapter 4, Connecting to Remote Computers.

Each window in Terminal contains an execution context, called a shell, which is

separate from all other execution contexts. The shell is an interactive programming

language interpreter, with a specialized syntax for executing commands and writingstructured programs (shell scripts). Dierent shells have slightly dierent capabilities

and programming syntax. Although you can use any shell, the examples in this book

use bash, the startup shell for Mac OS X and the default user shell.

1Introduction to the Command-LineEnvironment


11/58

Chapter 1 Introduction to the Command-Line Environment 11

The Command-Line EnvironmentThis section gives some background information about UNIX and shells. Both are

important for understanding the command-line environment in Mac OSX Server.

UNIXMac OS X and Mac OS X Server are built on the foundation of the UNIX operatingsystem. UNIX-based operating systems include BSD, GNU/Linux, AIX, and Solaris.

The shared heritage of these operating systems means that many programs are

compatible across this larger family with minimal changes.

The unique underpinnings of each brand of UNIX are what distinguish them from

each other. To support programs and utilities that work across multiple avors of UNIX,

there are some standard specications set by various regulatory bodies. One suchspecication is The Open Groups Single UNIX Specication. Mac OS X versions 10.5

and later conform to version 3 of this specication, which implies conformance to the

SUSv3 and POSIX 1003.1 specications for the C API, shell utilities, and threads. Code

that complies with the UNIX-03 specication works not only on Mac OS X Server, but

on any other compliant system.

For more information about the The Single UNIX Specication, Version 3, see

http://www.unix.org/version3/.

The ShellIn UNIX-based operating systems, the shell is the fundamental user interface. The

shell is an environment that presents a simple textual prompt to the user and accepts

keyboard input from the user.

In Mac OS X, the shell is easily accessed through Terminal, but there are other optionsas well. The shell can be invoked interactively, or by a text le with commands to the

shell given in a standard format. There are several shells available in Mac OS X, each

with its own strengths and capabilities. Shells included in Mac OS X include bash, csh,

ksh, sh, tcsh, and zsh.

For information about these shells, see their man pages.

Accessing the ShellTo enter shell commands or run server command-line tools, you need access to the

UNIX shell prompt on the local server or on a remote server.

Local AccessThere are multiple ways to access the shell on your local computer. Under

normal circumstances you can use Terminal, but for advanced troubleshooting or

conguration, you may want to use a dierent way to access the command line.
http://www.unix.org/version3/http://www.unix.org/version3/


12/58

Logging In from Terminal

To open Terminal, click the Terminal icon in the dock or double-click the application

icon in the Finder (in /Applications/Utilities/). Each window in Terminal represents

another instance of a shell process.

Terminal presents a prompt when its ready to accept a command. The prompt yousee depends on your Terminal and shell preferences, but it often includes the name

of the host youre logged in to, your current working folder, your user name, and

a prompt symbol.

For example, if youre using the default bash shell, the prompt appears as:

server1:~ mariah$

This indicates that youre logged in to a computer named server1 as the user namedmariah, and your current folder is Mariahs home folder (~).

Logging In from the Console

You can log in to a command-line version of Mac OS X without running the window

manager. This mode is more advanced than single-user mode because the entire

system is running.

To log in without the window manager:

1 In the Accounts pane of System Preferences, select Login Options.

2 Make sure the settings for Display login window as: is set to Name and password.

3 Log out any logged in users.

4 In the login window, type >console and press Return. Dont enter a password.

Youll be prompted to log in with the user name and password of a user on

the system.

Logging in to the console at this level can help you troubleshoot issues that

are graphics-related or that are triggered by users logging in to the system

through the GUI.

Single-User Mode

To debug a computer problem, you can restart the computer and hold down

Command-S as the computer boots. The computer boots up verbosely from

the command line to a certain point, and wont continue booting without your

intervention. The window server wont be running, and many services wont be started.

Onscreen instructions guide you through mounting and verifying the attached

volumes. This is a useful way to boot if you want to troubleshoot hardware-related

issues or determine whats happening in software before higher-level processes and

applications are running. At this point, very few processes are running.

12 Chapter 1 Introduction to the Command-Line Environment


13/58


The following processes and services arent running if you boot into single-user mode:

Directory Services

Kerberos

syslogd

mDNSResponder

securityd (and many related security processes)

Spotlight

Any other server services (such as Mail Server, Web Server, or Wiki Server) you may

have congured

X11

X11 is a window manager traditionally used in UNIX-based operating systems.

Although Mac OS X Server is a UNIX operating system, it doesnt use X Windows as

its window manager. X11 is available to provide compatibility with other UNIX-based

operating systems. All normal Mac OS X Server tasks are performed with tools that

dont rely on X11. To connect to the X11 server remotely, see Conguring and Running

X11 Applications on Mac OS X on the Apple Developer Connection website.

Serial ConsoleXserve hardware includes a 9-pin serial port. To access the Xserve, you can

connect a terminal or use terminal emulation software on a computer connected

by a serial-to-USB cable. No other Apple hardware includes a serial port.

Remote AccessVarious ways of accessing the command-line interface on remote computers are using

are discussed in Chapter 4, Connecting to Remote Computers.

Closing the ShellTo quit a shell session, enter the command exit. This ensures that any commands the

shell is actively running are closed. If anythings still in progress, the shell warns you.

Executing Commands and Running ToolsTo execute a command in the shell, enter the complete pathname of the tools

executable le, followed by arguments, and then press Return.

If a command is located in one of the shells known folders, you can omit path

information and enter just the command name.

The list of known folders is stored in the shells PATH environment variable and

includes the folders containing most command-line tools.
http://developer.apple.com/opensource/tools/runningX11.htmlhttp://developer.apple.com/opensource/tools/runningX11.htmlhttp://developer.apple.com/opensource/tools/runningX11.htmlhttp://developer.apple.com/opensource/tools/runningX11.html


14/58

For example, to run the ls command in the current users home folder, you could enter

the following at the command line and press Return:

host:~ mariah$ ls

The shell looks through the list of folders in the PATH variable until it nds a program

named ls; in this case, it nds ls in /bin, and runs /bin/ls.

To run a command in the current users home folder, precede it with the folder

specier. For example, to run MyCommandLineProg, use the following:

host:~ mariah$ ~/MyCommandLineProg

To open an application, use the open command:

open -a MyProg.app

When entering commands, if you get the message command not found, check your

spelling. Heres an example:

server:/ mariah$ opne -a TextEdit.app

-bash: opne: command not found

If this error recurs, the command youre trying to run might not be in your default

search path. You can add the path before the command name:

server:/ mariah$ sudo /System/Library/ServerSetup/serversetup

-getHostname

server.example.com

or change your working folder to the folder that contains the tool:

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

server:/System/Library/ServerSetup mariah$ sudo ./serversetup

-getHostname

server.example.com

or dene the path for this session and then run the command:

server:/ mariah$ PATH=$PATH:/System/Library/ServerSetup

server:/ mariah$ sudo serversetup -getHostname

server.example.com

Terminating CommandsTo terminate the currently running command, press Control-C. This keyboard shortcut

sends an abort signal to the command. In most cases this causes the command to

terminate, although commands can install signal handlers to trap this signal and

respond dierently.



15/58


Specifying Files and FoldersMost commands operate on les and folders, whose locations are identied by paths.

The folder names that make up a path are separated by slashes. For example, the path

to the Terminal application is /Applications/Utilities/Terminal.app.

Standard shortcuts used to represent specic folders are shown in the following

table. They are specied relative to the current folder, and can eliminate the need to

enter full paths.

Shortcut Description

. A single period represents the current folder.

For example, the string ./Test.c represents the

Test.c le in the current folder.

.. Two periods represent the parent folder of the

current folder. For example, the string ../Test

represents a sibling folder (named Test) of the

current folder.

~[username] The tilde character represents the home folder

of the logged-in user. For example, to specify the

Documents folder, of the current user, you would

specify ~/Documents. To specify another users

Document folder you would use their short name

preceded by the tilde (~) characterfor example,

~jsmith/Documents. In Mac OS X, this folder is

in the local /Users folder or on a network server.

For a list of all the short names on your system,

type dscl . -list /Users. Most of these

users arent traditional user accounts with home

directories, but you should be able to nd the

short name of known users on the computer.

File and folder names can include letters, numbers, a period, or the underscore

character. Avoid most other characters, including space characters. Although some

Mac OS X le systems permit the use of these other characters, including spaces,

you might need to add single or double quotation marks around pathnames that

contain them.

For individual characters, you can also escape the characterthat is, put a backslashcharacter immediately before the character in your string. For example, the pathname

My Disk is My Disk or My\ Disk.


16/58

Commands Requiring Root or Administrator PrivilegesMany commands used to manage a server must be executed by an administrator user

or the root user. For example, entering:

server:~ mariah$ shutdown

gives you the following error:

shutdown: NOT super-user

This is because the shutdown command can be run only by the root user or by an

administrative user with special privileges. To run commands in this "super user mode,

use the sudo command. sudo stands for super user do. The following command does

work, (so dont run it unless you really want to restart your computer):

server:~ mariah$ sudo shutdown

Youll be prompted for the password of the currently logged in user. Only users that

you have designated as admin users are able to execute commands with sudo. If youre

logged in as a user who isnt an admin user, you can change substitute users by

typing su adminUsername, where adminUsername is the name of a user in the Admin

group. After you enter that users password, a new shell is launched from the existing

shell, as that user. If a command requires it, you can use su to log in as the root user.

Under normal circumstances you dont need to use the root user account. If you do su

to the root user, be especially careful, as you have sucient privileges to make changes

that can cause your server to stop working.

For more information about the sudo and su commands, see their man pages.

Getting Help for Command-Line ToolsCommand-line tools provide multiple mechanism for getting help while using them.

This section describes three ways that you can get help from the command-line.

Using Help Built Into Command-Line ToolsMost command-line tools include a parameter to invoke onscreen help directly.

Command-line tools do not always follow the same conventions so if one parameter

doesnt work try another.

To access command help:

Enter the command followed by the -help,-h,--help, or help parameter:

$ hdiutil help

$ dig -h

$ diff --help



17/58


To view a list of options and parameters you can use with the command:

Enter the command without options or parameters:

$ sudo serveradmin

Some commands dont have onscreen help.

Using Man PagesMost command-line documentation comes in man pages. Man pages provide

reference information for shell commands, tools, and high-level concepts.

To access a man page entry:

$ man command

Replace commandwith the name of the command you want to nd information about.The man page contains detailed information about the command, its options and

parameters, and proper use.

For help using the man command itself, enter:

$ man man

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 forward one line at a time. Press the Q key to exit the man page.

You can search within the contents of a man page by pressing the / key followed by

the word youre looking for. If multiple instances are found, the P and N keys let you

access the previous and next instances of the term.

If you dont know the name of the particular man page, you can search the topics by

entering:

$ man -k topic

Replace topic with a word that would be contained in the description of the man

page you might be looking for. For example:

$ man -k "directory service"

Returns references to the dscacheutil, dscl, and whois man pages. You can

also nd links to related man pages at the bottom of a given man page in the SEE

ALSO section.

If you have the Xcode tools installed, you can view man pages from within Xcode by

selecting Open man page from the Help menu. There are also several third-party

graphical Mac OS X applications available for viewing man pages. You can nd one by

choosing Mac OS X Software from the Apple menu and then searching for man page.


18/58

Not all commands and tools have man pages. Some tools use info pages instead,

and some have no documentation at all. For more information about info pages, see

Using Info Pages on page 18.

You can also access command information using the help command, and sometimes

information is displayed if you enter the command without options or parameters.

Using Info PagesSome commands use info pages to display their documentation. Primarily these are

software packages that come from the GNU project. info is a tool for reading Texinfo

les from the command line. To use an info page, enter the info command followed

by the name of the tool:

server:/ mariah$ info emacs

You can navigate to nodes with the cursor and then press Return to go to them,

or type menu followed by the node name. The following commands provide basic

navigation between info nodes:

Key Command Results

n Navigates to the next page

p Returns to the previous page

u Navigates up one level of nodes

l Returns to the last node visited

q Quits the info program



19/58

19

Use this chapter to learn about using the command-line bytyping in commands.

You can use the command-line environment in Mac OS X and Mac OS X Server

interactively by typing a command and waiting for a result, or you can use the shell

to compose scripts that run without direct interaction. This chapter discusses using

the command-line environment interactively.

For more information about using a particular shell interactively, see the man page for

that shell.

Standard PipesMany commands can receive text input from the user and print text to the console.

They do so using standard pipes, which are automatically created by the shell and

passed to the command.

Standard pipes include: stdinThe standard input pipe is where command input enters a command.

By default, the user enters input from the command-line interface. You can redirect

the output from les or other commands to stdin.

stdoutThe standard output pipe is where command output is sent. By default,

command output is sent to the command line. You can redirect the output from the

command line to other commands and tools.

stderrThe standard error pipe is where error messages are sent. By default, errors

are displayed on the command line along with standard output.

2Using the Command-Line ShellInteractively


20/58

Redirecting Input and OutputFrom the command line, you can redirect input and output from a command to a le,

or to another command.

Redirect output from the command if you want to capture the results of running the

command and store it in a le for later use. Similarly, redirect input from a le to the

command if you want to provide the command with preset input data, instead of

needing to enter that data.

Use the following characters to redirect input and output:

Redirect Description

> Use a right angle bracket to redirect command

output to a le.

< Use a left angle bracket to use the contents of

a le as input to the command.

>> Use two right angle brackets to append output

from a command to a le.

In addition to using le redirection, you can also redirect the output of one command

to the input of another using the vertical bar character, orpipe. You can combine

commands in this manner to implement more sophisticated versions of the same

commands.

For example, the command man bash | grep commands passes the formatted

contents of the bash man page to the grep tool, which searches those contents for

lines containing the word commands. The result is a list of lines with the specied

text, instead of the entire man page.

For more information about redirection, see the bash man page.

Correcting Typing ErrorsYou can use the Left and Right Arrow keys to correct typing errors before you press

Return to execute a command.

To correct a typing error:

1 Press the Left or Right Arrow key to skip backward or forward over parts of the

command you dont want to change.

2 Press Delete to remove characters.

3 Type regular characters to insert them.

4 Press Return to execute the command.

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

20 Chapter 2 Using the Command-Line Shell Interactively


21/58

Chapter 2 Using the Command-Line Shell Interactively 21

Using Environment VariablesThe shell uses environment variables to store information, such as the name of the

current user, the name of the host computer, and the default paths to any commands.

Environment variables are inherited by all commands executed in the shells context,

and some commands depend on environment variables.

You can create environment variables and use them to control the behavior of

a command without modifying the command itself. For example, you can use an

environment variable to have a command print debug information to the console.

To set the value of an environment variable, use the appropriate shell command to

associate a variable name with a value. For example, to set the variable PATH to the

value /bin:/sbin:/user/bin:/user/sbin:/system/Library/, you would enter the

following command in a Terminal window:

$ PATH=/bin:/sbin:/user/bin:/user/sbin:/system/Library/ export PATH

This modies the environment variable PATH with the value assigned.

To view all environment variables, enter:

$ env

When you launch an application from a shell, the application inherits much of the

shells environment, including exported environment variables. This form of inheritance

can be a useful way to congure the application dynamically. For example, your

application can check for the presence (or value) of an environment variable and

change its behavior accordingly.

Dierent shells support dierent semantics for exporting environment variables.

For information, see the man page for your preferred shell.

Although child processes of a shell inherit the environment of that shell, shells are

separate execution contexts that dont share environment information with each other.

Variables you set in one Terminal window arent set in other Terminal windows.

After you close a Terminal window, variables you set in that window are gone. If you

want the value of a variable to persist across sessions and in all Terminal windows, you

must set it in a shell startup script. For information about modifying your bash shell

startup script (~bashrc) to keep variables and other settings across multiple sessions,

see the Invocation section of the bash man page.

Another way to set environment variables in Mac OS X is with a property list le in

your home folder. When you log in, the computer looks for a ~/.MacOSX/environment.

plist le. If the le is present, the computer registers the environment variables in the

property list le.


22/58

Repeating CommandsTo repeat a command, press the Up Arrow key until you see the command, then make

any modications and press Return.

Including Paths Using Drag and DropTo include a fully qualied lename or folder path in a command, you can drag the le

or folder from a Finder window to the Terminal window.

22 Chapter 2 Using the Command-Line Shell Interactively


23/58

23

Instead of entering commands and waiting for theirresponses, you can compose scripts that are run withoutdirect interaction.

This chapter discusses some basics of shell scripting on Mac OS X, including

automation and scheduling, as well as a brief overview of what a shell script is.

It does not provide information on writing shell scripts in general.

For information about how to write shell scripts, see the Shell Scripting Primeron

the Apple Developer Connection website.

What is a Shell Script?A shell script is a text le that contains one or more UNIX commands. You run a shell

script to perform commands you might otherwise run interactively at the command line.

Shell scripts are useful because you can combine many common tasks into one script,

saving you time and possible errors when running similar tasks over and over. Theycan also be easily automated using tools such as launchd or Apple Remote Desktop.

A shell script begins with a character combination that identies it as a shell script, the

characters # and ! (together called a shebang) followed by a reference to the specic

shell that the script should be run with. For example, heres the rst line of a shell script

that would be run with sh:

#!/bin/sh

You should document your shell scripts with comments. To make a comment, start

the line with the number sign (#). Every line of a comment needs to begin with the

number sign:

#This program returns the

#contents of my Home folder

You can put blank lines in a shell script to help visually distinguish dierent sections

of the script.

3Scripting the Command Line

d h l d h h h l


24/58

You need to use the chmod tool to indicate to the operating system that the text le

is executable (that is, its contents can be run as a program). To make a shell script

executable:

chmod 755 YourScriptName.sh

After making the shell script executable, you can run it by entering its pathname.For example:

~/Documents/Dev/YourScriptName.sh

or

cd ~/Documents/Dev/

./YourScriptName.sh

For more information about using chmod, see its man page. For more information

about running your shell scripts, see Executing Commands and Running Tools

on page 13.

Monitoring and Restarting Critical Services with launchdMac OS X includes a system for monitoring and running critical service, which you

may want to use to run various shell scripts. This system is uses a daemon namedlaunchd. During system startup, launchd is the rst process the kernel runs to set

up the computer. In Mac OS X Server, your daemon should be started by launchd.

Other mechanisms for starting daemons and services are subject to removal at

Apples discretion.

You can get an idea of the various processes run by launchd by looking at the

following conguration les:

Folder Usage

/System/Library/LaunchDaemons/ Apple-supplied system daemons

/System/Library/LaunchAgents/ Apple-supplied agents that apply to all users on

a per-user basis

/Library/LaunchDaemons/ Third-party system daemons

/Library/LaunchAgents/ Third-party agents that apply to all users on

a per-user basis

~/Library/LaunchAgents/ Third-party agents that apply to the logged-in

user only

You do not interact with launchd directlyinstead you use launchctl to load or

unload launchd daemons and agents.

24 Chapter 3 Scripting the Command Line

N t I li i f M OS X d M OS X S t d i i t t d


25/58

Chapter 3 Scripting the Command Line 25

Note: In earlier versions of Mac OS X and Mac OS X Server, system administrators used

the watchdog daemon to monitor critical services or modied the rc scripts. These are

no longer supported and should be replaced with calls using launchd.

In earlier versions of Mac OS X and Mac OS X Server, system administrators used the

watchdog daemon to monitor critical services or modied the rc scripts. These are nolonger supported and should be replaced with calls using launchd.

For more information about launchd, see the launchd and launchctl man pages. Also

seeTechnical Note TN2083: Daemons and Agents on the Apple Developer Connection.

Scheduling a Shell Script to Run at Specifc TimesTo schedule a shell script to run at predened times, use either launchd or the crontool. cron is a daemon that executes scheduled commands dened in crontab les.

Using cron to schedule a task

The cron tool searches the /var/cron/tabs/ folder for crontab les named after

accounts in /etc/passwd, and loads the les into memory. The cron tool also searches

for crontab les in the /etc/crontab/ folder, which are in a dierent format. cron then

cycles every minute, examining stored crontab les and checking each command to

see if it should be run in the current minute.

When commands execute, output is mailed to the owner of the crontab le or to the

user named in the optional MAILTO environment variable in the crontab le.

If you modify a crontab le, you must restart cron.

You use crontab to install, deinstall, or list the tables used to drive the cron daemon.

Users can have their own crontab le.

To congure your crontab le, use the crontab -e command. This displays an empty

crontab le.

Heres an example of a congured crontab le:

SHELL=/bin/sh

PATH=/bin:/sbin:/usr/bin:/usr/sbin

HOME=/var/log

#min hour mday month wday command

30 18 * * 1-5 diskutil repairPermissions /Volumes/MacHD

50 23 * * 0 diskutil repairVolume /Volumes/MacHD

The rst crontab entry repairs disk permissions for the MacHD volume at 18:30 every
http://developer.apple.com/technotes/tn2005/tn2083.htmlhttp://developer.apple.com/technotes/tn2005/tn2083.html


26/58

The rst crontab entry repairs disk permissions for the MacHD volume at 18:30 every

day, Monday through Friday:

30 18 * * 1-5 diskutil repairPermissions /Volumes/MacHD

The second crontab entry schedules a repair volume operation to run at 23:50 every

Sunday:

50 23 * * 0 diskutil repairVolume /Volumes/MacHD

Scheduling tasks with launchdYou can use launchd instead ofcron to schedule tasks. With launchd, if a task is

skipped because the computer is shut o or asleep, the task is added to the queue

when the computer comes back online. To use launchd to schedule timer-based jobs,use the StartCalendarInterval or StartInterval key.

For more information about launchd, see the launchd man page.

26 Chapter 3 Scripting the Command Line

4Connecting to Remote Computers


27/58

27

Learn about using the command-line on computersremotely.

If you need to run command-line tools on remote computers, there are tools to help

you. This chapter discusses some of the most commonly used tools and provides

some tips for getting started. It also describes three methods for connecting to the

command-line environment of a remote computer:

SSH

Apple Remote Desktop

X11

SSHSSH (Secure Shell) 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, and while the connection

is open, you enter commands to be performed on the remote computer.

You can also use any other application that supports SSH to connect to a computer

running Mac OS X or Mac OS X Server.

How SSH WorksSSH works by setting up encrypted tunnels using public and private keys. Heres

a description of an SSH session:

The local and remote computers exchange public keys.

If the local computer has never encountered a given public key, SSH and your web

browser prompt you to accept the unknown key.

The two computers use the public keys to negotiate a session key used to encrypt

subsequent session data.

4Connecting to Remote Computers

The remote computer attempts to authenticate the local computer using RSA or


28/58

The remote computer attempts to authenticate the local computer using RSA or

DSA certicates. If this isnt possible, the local computer is prompted for a local

username and password.

After successful authentication, the session begins. A remote shell, a secure le

transfer, a remote command, or other action can take place through the encrypted

tunnel.

The following are SSH tools:

sshdA daemon that acts as a server to all other commands

sshThe primary user tool, which includes a remote shell, remote command, and

port-forwarding sessions

scpSecure copy, a tool for automated le transfers

sftpSecure FTP, a replacement for FTP

Generating Key Pairs for Key-Based SSH ConnectionsBy default, SSH supports the use of password, key, and Kerberos authentication.

The standard method of SSH authentication is to supply a user name and password

as login credentials. Identity key-based authentication lets you log in to the server

without supplying a password.

Key-based authentication is more secure than password authentication, because it

requires that you have the private key le and know the password that lets you access

that key le. A key must be generated for each user account that needs to use ssh.

How SSH key-based authentication works:

1 A private and a public key are generated, each associated with a user name to

establish that users authenticity.

2 When you attempt to log in as that user, the user name is sent to the remote

computer.

3 The remote computer looks in the users .ssh/ folder for the users public key.

This folder is created when using SSH the rst time.

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

5 The user veries his or her identity by using the private portion of the key pair todecode the challenge.

6 After the key is decoded, the user is logged in without a password.

This is especially useful when automating remote scripts.

Note: If the server uses FileVault to encrypt the home folder of the user you want to

use SSH to connect as, you must be logged in on the server to use SSH. Alternatively,

you can store the keys for the user in a location that isnt protected by FileVault, but

this isnt secure.

28 Chapter 4 Connecting to Remote Computers

To generate the identity key pair:


29/58

Chapter 4 Connecting to Remote Computers 29

g y y p

1 Enter the following command on the local computer:

$ ssh-keygen -t dsa

2 When prompted, enter a lename in the users home folder to save the keys in; then

enter a password and password verication. For no password, dont enter anythingwhen prompted. Just press Return.

For example:

Generating public/private dsa key pair.

Enter file in which to save the key (/Users/mariah/.ssh/id_dsa): frog

Enter passphrase (empty for no passphrase):

Enter same passphrase again:

Your identification has been saved in frog.

Your public key has been saved in frog.pub.

The key fingerprint is:

4a:5c:6e:9f:3e:35:8b:e5:c9:5a:ac:00:e6:b8:d7:96 [email protected]

This creates two les. Your identication or private key is saved in one le (frog in our

example) and your public key is saved in the other (frog.pub in our example).

The key ngerprint, which is derived cryptographically from the public key value,also appears. This secures the public key, making it computationally infeasible for

duplication.

3 Copy the resulting public le, which contains the local computers public key, to the

.ssh/authorized_keys le in the users home folder on the remote computer (~/.ssh/

authorized_keys).

The next time you log in to the remote computer from the local computer, you wont

need to enter a password.

If you need to establish two-way communication between servers, repeat this process

on the second computer.

This process must be repeated for each user who needs to be able to open a key-

based SSH session. This includes the root user, whose home folder on Mac OS X Server

is at /var/root/.

Note: If youre using an Open Directory user account and have logged in using theaccount, you dont need to supply a password for SSH login. On computers with

Mac OS X Server, SSH uses Kerberos for single sign-on authentication with any user

account that has an Open Directory password. (Kerberos must be running on the

Open Directory server.) For more information, see Open Directory Administration.

A Key-Based SSH Scripting Example


30/58

A cluster of servers is an ideal environment for using key-based SSH. The following Perl

script is a trivial scripting example, and it shouldnt be implemented. It demonstrates

connecting over an SSH tunnel to each server dened in the variable serverList,

running softwareupdate, installing available updates, and restarting each server if

necessary. The script assumes that key-based SSH has been properly set up for the root

user on all servers to be updated.

#!/usr/bin/perl

# \@ is the escape sequence for the @ symbol.

my @serverList = ('root\@exampleserver1.example.com',

'root\@exampleserver2.example.com');

foreach $server (@serverList) {

open SBUFF, ssh $server -x -o batchmode=yes softwareupdate -i -a |;

while() {

my $flag = 0;

chop($_);

#check for restart text in $_

my $match = Please restart immediately;

$count = @{[$_ =~ /$match/g]};if($count > 0) {

$flag = 1;

}

}

close SBUFF;

if($flag == 1) {

\Qssh $server -x -o batchmode=yes shutdown -r now\Q

}

}

Updating SSH Key FingerprintsThe rst time you connect to a remote computer using SSH, the local computer

prompts for permission to add the remote computers ngerprint (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 rst 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 le so it can be veried in later sessions.


Be sure this is the correct key before accepting it. If possible, provide users with the


31/58


encryption key through FTP, mail, or a download from the web, so they can be sure of

the identity of the server.

If you later see a warning message about a man-in-the-middle attack (see below) when

you try to connect, it might be because the key on the remote computer no longermatches the key stored on the local computer. This can happen if you:

Change your SSH conguration on the local or remote computer

Perform a clean installation of the server software on the computer youre

attempting to log in to using SSH

Start up from a Mac OS X Server disc on the computer youre attempting to log in to

using SSH

Attempt to use SSH to access a computer that has the same IP address as a computer

that you used SSH with on another network

To connect again, delete the entries corresponding to the remote computer (which are

stored by name and IP address) in the le ~/.ssh/known_hosts.

An SSH Man-in-the-Middle Attack

Sometimes an attacker can access your network and compromise routing information,so that packets intended for a remote computer are routed to the attacker, who then

impersonates the remote computer to the local computer and the local computer to

the remote computer.

Heres a typical scenario: A user connects to the remote computer using SSH. By

using spoong techniques, the attacker poses as the remote computer and receives

information from the local computer. The attacker then relays the information to

the remote computer, receives a response, and then relays the remote computersresponse to the local computer.

Throughout the process, the attacker is privy to all information that goes back and

forth, and can modify it.

If you see the following message when connecting to the remote computer using SSH,

it may indicate a man-in-the-middle attack.

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

@ 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 youre trying to reach. Be watchful for the warning

message, and alert your users to its meaning.

Important: Removing a host key from the known_hosts le bypasses a security

h h ld h l d d h ddl k


32/58

mechanism that would help you avoid imposters and man-in-the-middle attacks.

Before you delete a host key from the known_hosts le, be sure you understand why

the key on the remote computer has changed.

Controlling Access to SSH ServiceYou can use Server Admin to control which users can open a command-line

connection using the ssh tool in Terminal. Users with administrator privileges can

always open a connection using SSH.

For information about controlling access to the SSH service, see Open Directory

Administration.

Connecting to a Remote Computer Using SSHUse the ssh tool to create a secure shell connection to a remote computer.

To access a remote computer using ssh:

1 Open Terminal.

2 Log in to the remote computer by entering:

$ ssh -l username server

Replace username with the name of an administrator user on the remote computer.

Replace serverwith the name or IP address of the remote computer. For example:

$ ssh -l mariah 10.0.1.2

If this is the rst time youre connecting to the remote computer, youre prompted to

continue connecting after the remote computers RSA ngerprint appears.

Enter yes.

3 When prompted, enter the users password for the remote computer.

The command prompt changes to show that youre connected to the remote

computer. In the previous example, the prompt might look like this:

10.0.1.2:~ mariah$

4 To send a command to the remote computer, enter the command.

5 To close the remote connection, enter logout.

You can authenticate and send a command using a single line, by appending the

command to the basic ssh tool. For example, to delete a le you could enter:

$ ssh -l mariah server1.example.com rm /Users/mariah/Documents/report

or

$ ssh -l [email protected] rm /Users/mariah/Documents/report

Youre prompted for the users password.


Apple Remote Desktop


33/58


Apple Remote Desktop is a software package thats available separately from

Mac OS X Server. Apple Remote Desktop provides a command for sending a shell

script or command to client computers, which lets you easily distribute and automate

shell scripts. For more information, see the UNIX Shell Commands section of the

Apple Remote Desktop Administrator Guide.

X11X11 is the traditional windowing system of UNIX systems. If youre working in

an environment where you need to support X11-based applications, you can use

them with Mac OS X Server, but you rst need to install the X11 package. The

X11 server and an application to access X windows from the Finder are availableas an optional installation in the Optional Installs folder of your installation disc

(X11 is in the Applications package). Once the package is installed, you can access

an X-based terminal by launching the X11 application in /Applications/Utilities/.

The X11 implementation in Mac OS X Server is based on the X.org foundation release,

and is X11R7 compatible.

X11 uses a dierent security model than the default model in Mac OS X Server.For more information, see the X11 Preferences Security pane and this article on the

Apple Developer Connection website:

Conguring and Running X11 Applications on Mac OS X

5Common Command-Line Tasks
http://x.org/http://developer.apple.com/opensource/tools/runningx11.htmlhttp://developer.apple.com/opensource/tools/runningx11.htmlhttp://developer.apple.com/opensource/tools/runningx11.htmlhttp://x.org/


34/58

34

This chapter discusses some of the most frequently usedcommand-line task.

If youre new to the command-line environment, it helps to understand some

common scenarios in which people frequently use the shell. This section explores

some of those areas and provides some guidance on getting started using the

shell in these situations.

Editing Confguration FilesA common use of the command line is to manually edit conguration les to enablefunctionality that isnt exposed in Server Admin or Workgroup Manager. In server

documentation, for example, you may be instructed to modify Property Lists (plists)

or other regular text les to incorporate additional functionality or enforce enhanced

security settings. If youre unfamiliar with using the command line to edit text les,

there are a few things to understand:

How to choose an appropriate text editor

How to edit property list (plist) les

How to save text les so they can be used by the UNIX subsystem of Mac OS X

These topics are discussed below.

Text EditorsTo edit a plain text le, use a text editor. Text editors are among the oldest programs

available on any operating system, and come in a wide varietyfrom completely

automatic text editors, where you essentially write a recipe for what actions should be

taken on text and then let the computer do the work, to much more interactive text

editors that can edit (and save) text in a wide variety of formats.

5

For general-purpose work, its easiest to deal with one of the text editors included

with Mac OS X If you want to use a graphical text editor use TextEdit (in /Applications/);


35/58

Chapter 5 Common Command-Line Tasks 35

with Mac OS X. If you want to use a graphical text editor, use TextEdit (in /Applications/);

otherwise, use one of the many command-line editors provided. The three most

full-featured command-line text editors included with Mac OS X are:

nano Nano is a simple command-line based editor. Its a replacement for thePico editor, so instructions for using the Pico editor can be used with nano. If you

invoke the pico editor, you actually run nano. Nano is a good introduction to using

a command-line based editor as it includes easy-to-follow on-screen help.

vim Vim is a vi-compatible text editor. It has many powerful enhancements for

moving around, searching, and editing documents. Basic editing is simple to learn and

there is much additional functionality to explore. Most functionality is accessed by

typing combinations of keystrokes that trigger certain behavior. Vim, or the editor itsmodeled after, vi, is found in most UNIX-based operating systems. If youll be doing

lots of editing from the command line, its a good editor to learn to use, but if you only

use a command-line based editor occasionally, you can get by without learning it.

Emacs Like vim, Emacs is an extremely full-featured editor found on most UNIX-

based systems. In addition to its editing power, Emacs is extremely customizable, with

additional functionality available in modules that let the Emacs interface do much

more than just text editing. Its relatively easy to do basic editing with, and has an

incredible depth of functionality for the dedicated user to explore. Like vim, Emacs

uses keystroke combinations to access its many dierent functional behaviors. These

require memorization to be most useful, so Emacs is most useful for people who use

the command line very often.

If youre new to using the command line and dont anticipate using it much for editing,

nano is probably your best choice. If you expect to spend a lot of time using thecommand-line environment, its probably worth learning either vim or Emacs. They

have very dierent design philosophies, so spend some time with each of them to

determine which works best for you. For more information about using nano, vim, or

Emacs, see their man pages.

You invoke a command-line editor by typing the name of the editor, followed by a

space and then the name of the le you want to open. If you want to create a new le,

type a name for the le. Designate where the le is located, as described in SpecifyingFiles and Folders on page 15. Heres an example of using nano to open a new le

named myFile.conf in your Documents folder:

$ nano ~/Documents/myFile.conf

Saving Text Files for UNIX ExecutionWhen you edit text les for execution by UNIX utilities you need to save the les


36/58

When you edit text les for execution by UNIX utilities, you need to save the les

properly so that they can be used (or executed) by their calling program. Its especially

important to use plain text and ensure that the privileges are correct.

Using plain textMany graphical text editors, including TextEdit, save text les in a more complex

format than most UNIX programs expect. If youre using TextEdit to edit text-based

conguration les, save them as Plain Text, not the default Rich Text Format. To change

the default format of text documents in TextEdit you have two options:

To save all documents as plain text, select Plain text under Format in the Newm

Document pane of TextEdit preferences.

To change the format of an individual document, choose Make Plain Text from themFormat menu.

Although Rich Text Format may appear to be simple text in an editor, its actually a full

specication that describes formatting, colors, fonts, and other information that isnt

contained in the plain text les that most UNIX programs expect. To see whats actually

contained in a Rich Text Format document, save one in TextEdit, and then open the

same le in a command-line text editor.

Editing Property ListsMany preference and conguration les in Mac OS X use property lists (plists) to

specify the attributes, or properties, of an application or process. An example is the

Finders preferences plist in the Library/Preferences/ folder of a users home folder. The

le is named com.apple.Finder.plist. The default naming convention for a plist includes

the distributors reverse DNS name prepended to the application or process name,followed by a.plist extension.

Property lists are binary les that you can edit using the following tools:

Property List Editor is a graphical application thats a part of the Xcode developer

tools. You can get the Xcode tools from developer.apple.com. Property List Editor is

most useful if you already understand property lists and their conventions.

PlistBuddyPlistBuddy is a command-line tool for directly reading and modifyingvalues inside a property list without the need to convert the property list to an

intermediary format.

defaults is a command-line tool that you can use to edit property lists.

The defaults command is a powerful tool, with functionality beyond simple editing

of property lists. When you know the specic key and value in a property list that

you need to change, its very ecient.

36 Chapter 5 Common Command-Line Tasks

plutil is a command-line tool that you can use to change a property list into

a format you can edit with a text editor, and then change back to its binary format.
http://developer.apple.com/http://developer.apple.com/


37/58


y g y

Using PlistBuddy to edit property lists

The PlistBuddy command is designed to easily read and modify values in a property

list. If you know the values to set or read, you can quickly make changes withPlistBuddy. PlistBuddy works on specic property list les.

This example shows how to use the PlistBuddy command interactively to change the

orientation of the Dock for a local user:

1 Determine the names of the appropriate property list, key, and values. In this case,

the name for the Docks property list is com.apple.Dock.plist. If you were editing

the Dock property list for the user alecjones, the path would be:

/Users/alecjones/Library/Preferences/com.apple.Dock.plist

2 Enter in the following command to enter the PlistBuddy interactive mode:

PlistBuddy /Users/alecjones/Library/Preferences/com.apple.Dock.plist

If the path to PlistBuddy isnt in your default paths, you need to add it or explicitly

call it as follows:

/usr/libexec/PlistBuddy ~/Library/Preferences/com.apple.Dock.plist

See Executing Commands and Running Tools on page 13.

If the le youre trying to edit doesnt exist,PlistBuddy creates the le in the

designated location.

3 In interactive mode, you can choose from many commands. To set or change the

orientation of the Dock to the left side of the screen, enter:

Set :orientation left

4 Save and exit:

Save

Exit

PlistBuddy can also be run non-interactively. To make the same change without

invoking interactive mode:

/usr/libexec/PlistBuddy -c "Set :orientation left" ~/Library/Preferences/

com.apple.Dock.plist

Both examples above assume the orientation key already exists. This isnt necessarily

true for a new user in Mac OS X version 10.6. Dont assume that a value exists. First,

conrm it with the Print command. Otherwise, you need to use the Add command,

which also requires designating a type.

There are many other options for PlistBuddy that are invoked in a similar manner.

For information about PlistBuddy, see its man page.


38/58

Using the defaults command to edit property lists

The defaults tools works directly with the Mac OS X preferences subsystem and is

used by many applications in Mac OS X to manage preferences and other settings.It can be built into shell scripts and allows you to access preferences in the multiple

domains that exist on a given computer.

1 Determine the names of the appropriate property list, key, and values. For example,

the name for the Docks property list is com.apple.Dock.plist. (When invoking the

defaults command, omit the .plist extension.)

2 Using the values you have determined or been given, enter their values following the

defaults command:

defaults write com.apple.dock orientation left

3 In most cases, you need to restart the application or process. A simple way to do this is

to use Activity Monitor to select the appropriate process, and then click Quit Process.

For this example, you would choose the process named Dock.

For information about defaults, see its man page.

Using plutil and a text editor to edit property lists

In Mac OS X v10.6, plist les are stored in a binary format. If you want to edit them with

a text editor, you must rst convert them to plain text. To convert a plist le to plain

text, use the plutil command:

plutil -convert xml1 com.apple.dock.plist

This results in an XML text le that you can edit. When youre done, convert the le

back to binary format:plutil -convert binary1 com.apple.dock.plist

Before making any changes to plist les using plutil, make a backup copy of the les.

Do this in the Finder, or use the cp command:

cp com.apple.finder.plist com.apple.dock.plist.bak

For information about Property Lists, see the plist man page. For the basics of using

command-line tools, see Chapter 1, Introduction to the Command-Line Environment.


Moving and Copying FilesYou can move and copy les locally or remotely using the mv, cp, and scp commands.


39/58


py y y g

Moving a le or folder locally

To move les or folders from one location to another on the same computer, use the

mv command. The mv command moves the le or folder from its old location and putsit in the new location.

For example, to move a le from your Downloads folder to a Work folder in your

Documents folder:

mv ~/Downloads/MyFile.txt ~/Documents/Work/MyFile.txt

You can also change the name of the le as its moved:

mv ~/Downloads/MyFile.txt ~/Documents/Work/NewFileName.txt

For more information about the mv command, see its man page.

Copying a le or folder locally

To make a copy of a le, use the cp command.

For example, to copy a folder named Expenses in your Documents folder to another

volume named Data:

cp ~/Documents/Expenses /Volumes/Data/Expenses

You can also change the name of the folder as its being moved:

cp ~/Documents/Expenses /Volumes/Data/Current_Expenses

For more information about the cp command, see its man page.

Copying a le or folder remotely

To copy a le or folder to or from a remote computer, use the scp command. scp

uses the same underlying protocols as ssh. For more information about SSH, see

Controlling Access to SSH Service on page 22.

For example, to copy a compressed le from your home folder to the ladmin users

home folder on a remote server:

scp -E ~/ImportantPapers.tgz [email protected]:/Users/ladmin/

Desktop/ImportantPapers.tgz

Youre prompted for the ladmin users password.

The -E ag preserves extended attributes, resource forks, and ACL information.

For more information about the scp command, see its man page.

Compressing and Uncompressing File ArchivesMac OS X and Mac OS X Server use the GNU tarutility to compress and uncompress


40/58

les and folders. When sending folders and multiple les between computers, it's

helpful to compress them into a single archive. This saves space, allows you to transfer

just one item instead of many, and makes it easier to resume in case the task is

suspended for some reason.

The tar utility has many options, but for a basic compression of a folder named

LotsOfFiles, you could simply enter:

tar -czf LotsOfFiles.tgz LotsOfFiles

If its a large folder, you may want to monitor the process by adding the v ag:

tar -czvf LotsOfFiles.tgz LotsOfFiles

To open an archive, use the x ag. The v ag is useful to watch whats going on:

tar -xzvf LotsOfFiles.tgz

The z ag indicates that the archive is being compressed, as well as being combined

into one le. Usually youll use this option, but you arent required to. The traditional

le extension for a compressed archive is .tgz, although you might also see les

ending in .tar.gz. If the archive isnt compressed, it usually just ends in .tar.

Files created with tar can be opened in the Finder by double-clicking them. Also, if

you use the File > Compress menu command in the Finder to compress a folder or le,

the tar le can be opened using tar from the command line.

For more information about the tar command, see its man page.

Viewing File ContentsIf you want to look at the contents of a text-based conguration le, you can use cat

or less. Generally, youll use less because it has more options (like searching).

To use less, type the command name followed by the name of the le you want to

view. The rst page of text lls the window. To view the next page, press the Space bar.

less also lets you search in a le. Type / followed by the phrase youre searching for. If

the phrase has spaces in it, precede each space with \:

/I\ read\ the\ other\ day

The following table lists some other useful keys for navigating the output from less.


Key Command Action

J or Down Arrow Scroll down a line


41/58


K or Up Arrow Scroll up a line

N Find the next occurrence of a search term

P Find the previous occurrence of a search term

Q Quit less

For more information about the less command, see its man page.

Searching for Text in a FileTo locate a string within a le, use the grep tool. The grep tool searches the named

input les for lines containing a match to the given pattern. By default, grep prints the

matching lines.

To search for a unique string in a le:

$ grep search_string filename

Replace search_string with the the string to search for, and replace flename with the

name of the le whose contents you want to search.

Backing Up and RestoringTime Machine is extremely useful for user backups, but server administrators might

have dierent backup requirements. Mac OS X Server provides several command-line

tools for backing up and restoring data:

rsyncUse this command to keep a backup copy of your data in sync with the

original. rsync copies only the les that have changed.

dittoUse this command to perform full backups.

asrUse this command to back up and restore an entire volume.

For more information about these commands, see their man pages.

Note: You can use these commands with the launchctl command to automatedata backup.

6Accessing Apple Hardware fromthe Command Line


42/58

42

Learn how to access hardware-level controls like restarting,shutting down, powering up, and selecting boot options

from the command line.

This chapter introduces commands for shutting down or restarting a local or remote

computer. Computers need to be shut down or restarted, whether locally or remotely,

when installing tools or making computer repairs.

Restarting a ComputerTo restart a computer at a specic time, use the reboot or shutdown -r command.For more information, see their man pages.

To restart the local computer:

$ shutdown -r now

To restart a remote computer immediately:

$ ssh -l root computer shutdown -r now

To restart a remote computer at a specic time:

$ ssh -l root computer shutdown -r hhmm

Parameter Description

computer The IP address or DNS name of the computer

hhmm The hour and minute when the computer restarts

Automatic RestartYou can also use the systemsetup tool to set the computer to start up after a power

failure or system freeze, by specifying a number of seconds:

systemsetup -setwaitforstartupafterpowerfailure seconds

6the Command Line


seconds The number of seconds before the computer

starts after a power failure This value must be


43/58

Chapter 6 Accessing Apple Hardware from the Command Line 43

starts after a power failure. This value must be

a multiple of 30.

Changing a Remote Computers Startup DiskYou can change a remote computers startup disk using SSH.

To determine available startup volumes:

Log in to the remote computer using SSH, and enter:

systemsetup -liststartupdisks

To change the startup disk:

Log in to the remote computer using SSH, and enter:

CodeLinesystemsetup -setstartupdisks /Volumes/SnowLeopardServerHD/System/

Library/CoreServices

For information about using SSH to log in to a remote computer, see SSH on page 27.

Shutting Down a ComputerTo shut down a computer at a specic time, use the shutdown tool. For more

information, see the shutdown man page.

To shut down a remote computer immediately:

$ ssh -l root computer shutdown -h now

To shut down the local computer in 30 minutes:

$ shutdown -h +30


computer The IP address or DNS name of the computer

Shutting Down While Leaving the Computer On and PoweredTo support UPS restart after power failure, the shutdown tool provides the -u option.

This option halts system shutdown before the shutdown tool instructs the power

manager to turn o the power supply.

The -u option keeps the system halted and waits for 5 minutes before removing

power so an external UPS can forcibly remove power.

Using the -u option simulates a dirty shutdown, which allows a later automatic

power-on. The operating system uses the -u option with supported UPS devices in

emergency shutdowns.

Manipulating Open Firmware NVRAM VariablesTo manipulate Open Firmware NVRAM variables, use the nvram tool. If you change

a value with nvram the value is saved only if the computer cleanly restarts or


44/58

a value with nvram, the value is saved only if the computer cleanly restarts or

shuts down.

To view NVRAM variables:$ nvram -p

For more information, see the nvram man page.

Remotely Controlling the Xserve Front PanelYou can use the ipmitool command to remotely control the front panel of an Xserve.

To display the list of supported virtual front panel commands:

$ ipmitool chassis bootdev

bootdev [clear-cmos=yes|no]

none : Do not change boot device order

pxe : Force PXE boot (LOM: Force boot NetBoot server)

disk : Force boot from default Hard-drive

safe : Force boot from default Hard-drive, request Safe Mode (LOM: Notused)

diag : Force boot from Diagnostic Partition (LOM: Force boot diagnostic

mode from NetBoot server)

cdrom : Force boot from CD/DVD

bios : Force boot into BIOS Setup (LOM: Not used)

Lights-out Management additional options

nvram : Force reset of NVRAM

tdm : Force boot into Target Disk Mode

other : Skip current startup disk selection, and boot from other

Mac OS X Server v10.6 supports the following commands:none, pxe, disk, diag, cdrom,

nvram, tdm, and other.

For example, enter the following command and then restart the Xserve system to start

the system in Target Disk Mode:

$ ipmitool chassis bootdev tdm

After the system starts, the ipmitool command reverts to the default setting (none).

Restarting the Xserve system without running the ipmitool command doesnt change

the boot device order.

For more information about ipmitool, see its man page.

44 Chapter 6 Accessing Apple Hardware from the Command Line

Appendix

Command-Line Tools Specic toMac OS X


45/58

45

The following command line tools are unique to Mac OS X or substantially dierent

from implementations on other UNIX platforms. See their man pages for more details.

An online version of the man pages in Mac OS X and Mac OS X server is available at:

http://developer.apple.com/documentation/Darwin/Reference/ManPages/

Section 1 Man PagesMan pages in section 1 refer to general command-line tools and utilities.

See the intro(1) man page for more information about this section.

afconvert(1) Audio le converter

afinfo(1) Audio le information

afplay(1) Audio le player

afscexpand(1) Decompress les compressed with HFS+ compression

amlint(1) Check Automator actions for problems

applesingle(1) Encode and decode les

ar(1) Create and maintain library archives

arch(1) Print architecture type or run selected architecture of a universal

binary

authopen(1) Open le with authorization

automator(1) Runs Automator workow

auval(1) AudioUnit validation

auvaltool(1) AudioUnit validation

binhex(1) Encode and decode les

BuildStrings(1) Generate header (.h) or resource (.r) le from text les

compileHelp(1) Command-line utility to merge contextual help rtf snippets into

one resource

AMac OS X

configureLocalKDC(1) Generate a LocalKDC

CPlusTestRig(1) Runs CPlusTest unit test bundles
http://developer.apple.com/documentation/Darwin/Reference/ManPages/http://developer.apple.com/documentation/Darwin/Reference/ManPages/


46/58

46 Appendix Command-Line Tools Specifc to Mac OS X

CpMac(1) Copy les preserving metadata and forks

createhomedir(1) Create and populate home directories on the local computer

defaults(1) Access the Mac OS X user defaults system

desdp(1) Scripting denition generator

ditto(1) Copy directory hierarchies, create and extract archives

dns-sd(1) Multicast DNS (mDNS) & DNS Service Discovery (DNS-SD) Test Tool

drutil(1) Interact with CD/DVD burners

dscacheutil(1) Gather information, statistics and initiate queries to the Directory

Service cache

dsimport(1) Tool for importing records into an Open Directory source

dsmemberutil(1) Various operations for the membership APIs, including state

dump, check memberships, UUIDs, etc

dsymutil(1) Manipulate archived DWARF debug symbol les

dwarfdump(1) Dump DWARF debug information

dyldinfo(1) Displays information used by dyld in an executable

emacs-undumped(1) Basic emacs with no ELisp libraries loaded

FixupResourceForks(1) Join AppleDouble les into two-fork HFS resource les

fs_usage(1) Report system calls and page faults related to lesystem activity

in real-time

fwkdp(1) FireWire KDP Tool

fwkpfv(1) FireWire kprintf viewer

gatherheaderdoc(1) Header documentation processor

genstrings(1) Generate string table from source code

GetFileInfo(1) Get attributes of les and directories

hdiutil(1) Manipulate disk images (attach, verify, burn, etc)

hdxml2manxml(1) HeaderDoc XML to MPGL translator

headerdoc(1) Header documentation processor

headerdoc2html(1) Header documentation processor

hiutil(1) Utility for creating and examining Help Viewer indices

hwprefs(1) Inspect and control low-level system and processor parameters

javaconfig(1) Get Java conguration information

javatool(1) Tool used in building o

Introduction to Command-Line Administration, Mac Leopard v10.6

Documents

Transcript of Introduction to Command-Line Administration, Mac Leopard v10.6