Apple Mac Os X Server Users Manual Command Line
Mac OS X Server to the manual 7f6bcde7-3767-4468-8813-daa844f81ff0
2015-02-02
: Apple Apple-Mac-Os-X-Server-Users-Manual-418278 apple-mac-os-x-server-users-manual-418278 apple pdf
Open the PDF directly: View PDF 
.
Page Count: 304
| Download | |
| Open PDF In Browser | View PDF |
Mac OS X Server Command-Line Administration For Version 10.4 or Later Second Edition K Apple Computer, Inc. © 2006 Apple Computer, Inc. All rights reserved. The owner or authorized user of a valid copy of Mac OS X Server software may reproduce this publication for the purpose of learning to use such software. No part of this publication may be reproduced or transmitted for commercial purposes, such as selling copies of this publication or for providing paid-for support services. Every effort has been made to ensure that the information in this manual is accurate. Apple Computer, Inc., is not responsible for printing or clerical errors. Apple 1 Infinite Loop Cupertino CA 95014-2084 www.apple.com The Apple logo is a trademark of Apple Computer, Inc., registered in the U.S. and other countries. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. Apple, the Apple logo, AppleShare, AppleTalk, Mac, Macintosh, QuickTime, Xgrid, and Xserve are trademarks of Apple Computer, Inc., registered in the U.S. and other countries. Finder is a trademark of Apple Computer, Inc. Adobe and PostScript are trademarks of Adobe Systems Incorporated. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd. Apache is a registered trademark of the Apache Software Foundation, and is used with permission. Other company and product names mentioned herein are trademarks of their respective companies. Mention of third-party products is for informational purposes only and constitutes neither an endorsement nor a recommendation. Apple assumes no responsibility with regard to the performance or use of these products. 019-0635/2-15-2006 1 Contents Preface 15 16 16 16 16 16 17 17 18 18 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 Chapter 1 21 21 22 23 23 24 25 26 26 26 26 26 27 27 28 28 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 Chapter 2 31 31 31 32 33 Connecting to Remote Computers Understanding Secure Shell How SSH Works Password-Less Logins Using SSH Keys Updating SSH Key Fingerprints 3 4 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 37 38 39 39 40 40 40 41 43 43 47 47 48 48 48 49 49 50 51 Installing Server Software and Finishing Basic Setup Installing Server Software Locating Computers for Installation Specifying the Target Computer Volume Preparing the Target Volume for a Clean Installation Installing from Multiple CDs Restarting After Installation Automating Server Setup Creating a Configuration File Working with an Encrypted Configuration File Customizing a Configuration File Storing a Configuration File in an Accessible Location Configuring the Server Remotely from the Command Line Changing Server Settings Using the serversetup Tool Using the serveradmin Tool General and Network Preferences Viewing, Validating, and Setting the Software Serial Number Updating Server Software Moving a Server Chapter 4 53 53 53 54 54 54 55 Restarting or Shutting Down a Computer Restarting a Computer Automatic Restart Changing a Remote Computer’s Startup Disk Shutting Down a Computer Manipulating Open Firmware NVRAM Variables Monitoring and Restarting Critical Services Chapter 5 57 57 57 58 58 58 58 59 Setting General System Preferences Viewing or Changing the Computer Name Viewing or Changing the Date and Time Viewing or Changing the System Date Viewing or Changing the System Time Viewing or Changing the System Time Zone Viewing or Changing Network Time Server Usage Viewing or Changing the Energy Saver Settings Contents Chapter 6 59 59 60 60 61 61 61 61 62 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 63 63 64 64 64 65 65 65 65 65 66 66 67 69 70 70 70 72 72 73 73 74 75 76 76 77 77 77 77 78 78 78 79 Setting Network Preferences Configuring Network Interfaces Managing Network Interface Information 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 5 6 79 79 80 80 81 Computer Name Hostname Bonjour Name Managing Preference Files and the Configuration Daemon Changing Network Locations Chapter 7 83 83 83 84 84 85 85 86 87 89 89 90 90 90 91 91 91 92 92 92 92 93 94 94 95 Working with Disks and Volumes Understanding Disks, Partitions, and the File System Mounting and Unmounting Volumes Mounting Volumes Unmounting Volumes Displaying Disk Information Monitoring Disk Space Reclaiming Disk Space Using Log-Rolling Scripts Erasing, Modifying, Verifying, and Repairing Disks Partitioning and Formatting Disks Partitioning a Disk Labeling a Disk Formatting a Disk Checking for Disk Problems Managing Disk Journaling Checking to See If Journaling is Enabled Enabling Journaling for an Existing Volume Enabling Journaling When You Erase a Disk Disabling Journaling Understanding Spotlight Technology Enabling and Disabling Spotlight Performing Spotlight Searches Controlling Spotlight Indexing Managing RAID Volumes Imaging and Cloning Volumes Using ASR Chapter 8 97 97 98 98 99 100 100 103 103 104 106 Working with Users and Groups Understanding Accounts Administering and Creating Accounts Creating a Local Administrator User Account for a Server Creating a Domain Administrator User Account Checking a User’s Administrator Privileges Creating a Nonadministrator User Account Retreiving a User’s GUID Removing a User Account Revoking a User’s Right to Access His or Her Account Checking a Server User’s Name, UID, or Password Contents Chapter 9 107 108 109 110 111 112 113 114 116 117 118 118 119 120 123 123 124 125 126 126 126 126 127 127 128 129 131 Modifying a User Account Creating a Mobile User Account Managing Home Folders Administering Group Accounts Creating a Group Account Removing a Group Account Adding a User to a Group Removing a User from a Group Creating and Deleting Nested Group Editing Group Records Creating a Group Folder Viewing the Workgroup a User Selects at Login Importing Users and Groups Creating a Character-Delimited User Import File Setting Permissions Viewing Permissions Setting the umask for Individual Users Changing Permissions Changing the Owner Changing the Group Securing System Accounts Securing Initial System Accounts Securing the Root Account Restricting Use of the sudo Tool Securing Single-User Boot Setting Password Policy Finding User Account Information 133 133 134 134 135 136 136 136 136 136 137 137 140 141 142 Working with File Services Managing Share Points Listing Share Points Creating a Share Point Modifying a Share Point Disabling a Share Point Managing the AFP Service Starting and Stopping AFP Service Checking AFP Service Status Viewing AFP Settings Changing AFP Settings List of AFP Settings List of AFP serveradmin Commands Listing Connected Users Sending a Message to AFP Users Contents 7 Chapter 10 8 142 143 144 145 146 146 146 146 146 147 147 147 147 147 148 148 150 150 150 151 151 151 151 152 152 155 155 156 156 157 157 157 158 Disconnecting AFP Users Canceling a User Disconnect Listing AFP Service Statistics Viewing AFP Log Files Managing the NFS Service Starting and Stopping NFS Service Checking NFS Service Status Viewing NFS Service Settings Changing NFS Service Settings Managing the FTP Service Starting FTP Service Stopping FTP Service Checking FTP Service Status Viewing FTP Service Settings Changing FTP Service Settings List of FTP Service Settings List of FTP serveradmin Commands Viewing the FTP Transfer Log Checking for Connected FTP Users Managing the SMB/CIFS Service Starting and Stopping SMB/CIFS Service Checking SMB/CIFS Service Status Viewing SMB/CIFS Service Settings Changing SMB/CIFS Service Settings List of SMB/CIFS Service Settings List of SMB/CIFS serveradmin Commands Listing SMB/CIFS Users Disconnecting SMB/CIFS Users Listing SMB/CIFS Service Statistics Updating Share Point Information Viewing SMB/CIFS Service Logs Managing ACLs Using chmod to Modify ACLs 161 161 162 162 163 163 163 166 167 Working with the Print Service Understanding the Print Process Performing Print Service Tasks Starting and Stopping Print Service Checking the Status of Print Service Viewing Print Service Settings Changing Print Service Settings Managing the Print Service Listing Queues Contents 167 167 168 169 169 Pausing a Queue Listing Jobs and Job Information Holding a Job Viewing Print Service Log Files Viewing Cover Pages Chapter 11 171 171 171 172 172 172 173 173 174 174 175 176 176 176 176 177 177 178 Working with NetBoot Service and System Images Understanding the NetBoot Service Starting and Stopping NetBoot Service Checking NetBoot Service Status Viewing NetBoot Settings Changing NetBoot Settings Changing General Netboot Service Settings Storage Record Array Filters Record Array Image Record Array Port Record Array Working with System Images Updating an Image Booting from an Image Using hdiutil to Work with System Images Using asr to Restore System Images Imaging Multiple Clients Using Multicast asr Choosing a Boot Device Using systemsetup Chapter 12 179 179 179 180 180 181 181 181 181 181 182 194 194 195 196 197 198 198 Working with the Mail Service Understanding the Mail Service Postfix Agent Cyrus Mailman Managing the Mail Service Starting and Stopping Mail Service Checking the Status of Mail Service Viewing Mail Service Settings Changing Mail Service Settings Mail Service Settings Mail serveradmin Commands Listing Mail Service Statistics Viewing the Mail Service Logs Backing Up the Mail Files Reconstructing the Mail Database Setting Up SSL for Mail Service Generating a CSR and Creating a Keychain Contents 9 10 200 200 200 201 202 202 203 Obtaining an SSL Certificate Importing an SSL Certificate into the Keychain Accessing the Server Certificates Creating a Password File Configuring Mailboxes Enabling Sieve Scripting Enabling Sieve Support Chapter 13 207 207 208 208 208 208 209 209 209 210 210 210 210 212 213 214 214 214 215 Working with Web Technologies Understanding Web Technology Managing the Web Service Starting and Stopping Web Service Checking Web Service Status Viewing Web Settings Changing Web Settings serveradmin and Apache Settings Changing Settings Using serveradmin Web serveradmin Commands Listing Hosted Sites Viewing Service Logs Viewing Service Statistics Example Script for Adding a Website Tuning the Server Performance Working with Application Servers and Java Apache Tomcat JBoss Server MySQL Database Chapter 14 217 217 218 218 218 218 219 219 220 222 223 224 224 225 225 Working with Network Services Managing Network Services Managing the DHCP Service Starting and Stopping DHCP Service Checking the Status of DHCP Service Viewing DHCP Service Settings Changing DHCP Service Settings DHCP Service Settings DHCP Subnet Settings Array Adding a DHCP Subnet Adding a DHCP Static Map List of DHCP serveradmin Commands Viewing the DHCP Service Log Managing the DNS Service Starting and Stopping the DNS Service Contents 225 225 226 226 226 226 226 227 227 228 228 228 228 229 229 230 233 233 234 234 234 235 235 235 235 236 236 237 237 238 238 238 238 239 239 242 242 243 243 244 245 245 245 Checking the Status of DNS Service Viewing DNS Service Settings Changing DNS Service Settings DNS Service Settings List of DNS serveradmin Commands Viewing the DNS Service Log Listing DNS Service Statistics Configuring IP Forwarding Managing the Firewall Service Firewall Startup Starting and Stopping Firewall Service Checking the Status of Firewall Service Viewing Firewall Service Settings Changing Firewall Service Settings Firewall Service Settings Defining Firewall Rules ipfilter Rules Array Firewall serveradmin Commands Viewing Firewall Service Log Using Firewall Service to Simulate Network Activity Managing the NAT Service Starting and Stopping NAT Service Checking the Status of NAT Service Viewing NAT Service Settings Changing NAT Service Settings NAT Service Settings NAT serveradmin Commands Port Mapping Viewing the NAT Service Log Managing the VPN Service Starting and Stopping VPN Service Checking the Status of VPN Service Viewing VPN Service Settings Changing VPN Service Settings List of VPN Service Settings List of VPN serveradmin Commands Viewing the VPN Service Log Site-to-Site VPN Configuring Site-to-Site VPN Adding a VPN Keyagent User Setting Up IP Failover IP Failover Prerequisites IP Failover Operation Contents 11 12 246 247 248 248 Enabling IP Failover Configuring IP Failover Enabling PPP Dial-In Restoring the Default Configuration for Server Services Chapter 15 251 251 251 251 252 252 252 252 253 253 254 255 255 258 259 259 259 260 260 261 263 263 264 264 265 265 Working with Open Directory Understanding Open Directory Using General Directory Tools Testing Your Open Directory Configuration Modifying a Directory Domain Testing Open Directory Plug-ins Registering URLs with SLP Changing Open Directory Service Settings Managing OpenLDAP Configuring LDAP Configuring slapd and slurpd Daemons Idle Rebinding Options Searching the LDAP Server Using LDIF Files Additional Information About LDAP Managing NetInfo Configuring NetInfo Managing Open Directory Passwords Open Directory Password Server Kerberos and Apple Single Sign-On Using Directory Service Tools Operating on Directory Service Directory Domains Finding Network Information Manipulating a Single Named Group Record Adding or Removing LDAP Server Configurations Configuring the Active Directory Plug-In Chapter 16 267 267 267 268 268 268 268 269 272 272 273 Working with QuickTime Streaming Server Understanding QuickTime Streaming Server Performing QTSS Service Tasks Starting and Stopping the QTSS Service Checking QTSS Service Status Viewing QTSS Settings Changing QTSS Settings QTSS Settings Managing QTSS Listing Current Connections Viewing QTSS Service Statistics Contents 274 274 275 275 275 276 276 278 278 278 278 279 279 Viewing Service Logs Forcing QTSS to Reread its Preferences Preparing Older Home Folders for User Streaming Configuring Streaming Security Resetting the Streaming Server Admin User Name and Password Controlling Access to Streamed Media Creating an Access File Accessing Protected Media Adding User Accounts and Passwords Adding or Deleting Groups Making Changes to the User or Group File Manipulating QuickTime and MP4 Movies Creating Reference Movies Chapter 17 281 281 281 281 282 283 Configuring System Logging Logging System Events Configuring the Log File Configuring Your System Logging Local Logging Remote Logging Appendix 285 PCI RAID Card Command Reference Glossary 289 Index 299 Contents 13 14 Contents Preface 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. Darwin maintains most of the functionality of 4.4BSD commands. While some commands are modified to function differently, most of the commands are either kept as is, or their functionality has been extended to support Apple-specific technologies. This guide focuses on commands developed by Apple to allow administrators to perform funtions available in the graphical interface from the command line. The guide also highlights BSD commands that have been modified or extended to support Applespecific functionality. Finally, the guide describes important commands commonly used by UNIX system administrators. Note: Because Apple frequently releases new versions and updates to its software, images shown in this book may be different from what you see on your screen. 15 Using This Guide This guide describes commands that perform functions used to configure and manage Mac OS X computers. Chapters in this guide describe sets of commands that work for specific aspects of the operating system. Use this guide to:  Learn which commands are available for specific tasks  Learn how the commands work, and how to execute them  Review examples of command usage Understanding Notation Conventions The following conventions are used throughout this book. Summary Notation Indicates monospaced font A command or other text typed in a Terminal window $ A shell prompt [text_in_brackets] An optional parameter (one|other) Alternative parameters (enter one or the other) italicized A parameter you must replace with a value [...] A parameter that may be repeatedA displayed value that depends on your server configuration Commands and Other Terminal Text Commands or command parameters that you might enter, along with other text that normally appears in a Terminal window, are shown in this font. For example: You can use the doit command to get things done. When a command is shown on a line by itself in this manual, it is preceded by a dollar sign and a space that represent the shell prompt. For example: $ doit To use this command, enter it without the dollar sign and the space in a Terminal window, and then press the Return key. (Terminal is found in /Applications/Utilities). Command Parameters and Options Most commands require one or more parameters to specify command options or the item to which the command is applied. 16 Preface About This Guide Parameters You Must Enter as Shown If you must enter a parameter as shown, it appears following the command in the same font. For example: $ doit -w later -t 12:30 To use the command in this example, enter the entire line as shown (without the $ and space). Parameter Values You Provide If you must provide a value, its placeholder is italicized and has a name that indicates what you need to provide. For example: $ doit -w later -t hh:mm In this example, you replace hh with the hour and mm with the minute, as shown in the previous example. Optional Parameters If a parameter is not required, it appears in square brackets. For example: $ doit [-w later] To use the command in this example, enter either doit or doit might vary, but the command will be performed either way. -w later. The result 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 = " ". 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. 18 This guide ... tells you how to: Mac OS X Server Getting Started for Version 10.4 or Later Install Mac OS X Server and set it up for the first time. Mac OS X Server Upgrading and Migrating to Version 10.4 or Later Use data and service settings that are currently being used on earlier versions of the server. Mac OS X Server User Management for Version 10.4 or Later Create and manage users, groups, and computer lists. Set up managed preferences for Mac OS X clients. Preface About This Guide This guide ... tells you how to: Mac OS X Server File Services Administration for Version 10.4 or Later Share selected server volumes or folders among server clients using these protocols: AFP, NFS, FTP, and SMB/CIFS. Mac OS X Server Print Service Administration for Version 10.4 or Later Host shared printers and manage their associated queues and print jobs. Mac OS X Server System Imaging and Software Update Administration for Version 10.4 or Later 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. Mac OS X Server Mail Service Administration for Version 10.4 or Later Set up, configure, and administer mail services on the server. Mac OS X Server Web Technologies Administration for Version 10.4 or Later Set up and manage a web server, including WebDAV, WebMail, and web modules. Mac OS X Server Network Services Set up, configure, and administer DHCP, DNS, VPN, NTP, IP firewall, Administration for Version 10.4 or and NAT services on the server. Later Mac OS X Server Open Directory Administration for Version 10.4 or Later Manage directory and authentication services. Mac OS X Server QuickTime Streaming Server Administration for Version 10.4 or Later Set up and manage QuickTime streaming services. Mac OS X Server Windows Services Administration for Version 10.4 or Later Set up and manage services including PDC, BDC, file, and print for Windows computer users. Mac OS X Server Migrating from Windows NT for Version 10.4 or Later Move accounts, shared folders, and services from Windows NT servers to Mac OS X Server. Mac OS X Server Java Application Server Administration For Version 10.4 or Later Configure and administer a JBoss application server on Mac OS X Server. Mac OS X Server Command-Line Administration for Version 10.4 or Later Use commands and configuration files to perform server administration tasks in a UNIX command shell. Mac OS X Server Collaboration Services Administration for Version 10.4 or Later Set up and manage weblog, chat, and other services that facilitate interactions among users. Mac OS X Server High Availability Administration for Version 10.4 or Later Manage IP failover, link aggregation, load balancing, and other hardware and software configurations to ensure high availability of Mac OS X Server services. Preface About This Guide 19 This guide ... tells you how to: Mac OS X Server Xgrid Administration for Version 10.4 or Later Manage computational Xserve clusters using the Xgrid application. Mac OS X Server Interpret terms used for server and storage products. Glossary: Includes Terminology for Mac OS X Server, Xserve, Xserve RAID, and Xsan 20 Preface About This Guide 1 Executing Commands 1 In this chapter you will find out how to execute commands and view online information about commands and tools. A command-line interface is a way for you to manipulate your computer in situations where a graphical approach is not available. The Terminal application is the Mac OS X gateway to the BSD command-line interface (UNIX shell command prompt). Each window in Terminal contains a complete execution context, called a shell, that is separate from all other execution contexts. The shell itself is an interactive programming language interpreter, with a specialized syntax for executing commands and writing structured programs, called shell scripts. Different shells feature slightly different capabilities and programming syntax. Although you can use any shell of your choice, the examples in this book assume that you are using bash, the standard Mac OS X shell. Opening Terminal To enter shell commands or run server command-line tools, you need access to a UNIX shell prompt. Both Mac OS X and Mac OS X Server include Terminal, an application you can use to start a UNIX shell command-line session on the local server or on a remote server. To open Terminal, click the Terminal icon in the dock or double-click the application icon in the Finder (located in /Applications/Utilities/). Terminal presents a prompt when it is ready to accept a command. The prompt you see depends on your Terminal and shell preferences, but often includes the name of the host you’re logged in to, your current working folder, your user name, and a prompt symbol. 21 For example, if you’re using the default bash shell and the prompt displays as: server1:~ anne$ Where you are logged in to a computer named “server1” as the user named “anne,” and your current folder is anne’s home folder (~). Throughout this manual, wherever a command is shown as you might enter it, the prompt is abbreviated as $. Specifying Files and Folders Most commands operate on files and folders, the locations of which are identified by paths. The folder names that make up a path are separated by slash characters. For example, the path to the Terminal application is /Applications/Utilities/Terminal.app. Some of the standard shortcuts used to represent specific folders in the computer are shown in the following table. Because they are relative to the current folder, these shortcuts eliminate the need to enter full paths in many situations. Path string Description . A single period represents the current folder. This value is often used as a shortcut to eliminate the need to enter in a full path. For example, the string “./Test.c” represents the Test.c file in the current folder. .. Two periods represents the parent folder of the current folder. This string is used for navigating up one level from the current folder through the folder hierarchy. For example, the string “../Test” represents a sibling folder (named Test) of the current folder. ~ The tilde character represents the home folder of the user currently logged in. In Mac OS X, this folder resides either in the local /Users folder or on a network server. For example, to specify the Documents folder of the current user, you would specify ~/ Documents. File and folder names traditionally include only letters, numbers, a period, or the underscore character. Most other characters, including space characters, should be avoided. Although some Mac OS X file systems permit the use of these other characters, including spaces, you may have to add single or double quotation marks around any pathnames that contain them. For individual characters, you can also “escape” the character—that is, put a backslash character immediately before the character in your string. For example, the pathname My Disk would become either “My Disk” or My\ Disk. 22 Chapter 1 Executing Commands Modifying Flow Control Many commands are capable of receiving text input from the user and printing text out to the console. They do so using standard pipes, which are created by the shell and passed to the command automatically. The standard pipes include:  stdin—The standard input pipe is the means through which data enters a command. By default, this is data entered by the user from the command-line interface. You can also redirect the output from files or other commands to stdin.  stdout—The standard output pipe is where the command output is sent. By default, command output is sent back to the command line. You can also redirect the output from the command to other commands and tools.  stderr—The standard error pipe is where error messages are sent. By default, errors are displayed on the command line like standard output. Redirecting Input and Output From the command line, you may redirect input and output from a command to a file or another command. Redirecting output lets you capture the results of running the command and store it in a file for later use. Similarly, providing an input file lets you provide a command with preset input data, instead of having to enter that data. Redirect Description > Use the greater-than character to redirect command output to a file. < Use the less-than character to use the contents of a file as input to the command. >> Use a double greater-than to append output from a command to a file. In addition to using file redirection, you can also redirect the output of one command to the input of another using the vertical bar character, or pipe. You can combine commands in this manner to implement more sophisticated versions of the same commands. For example, the command man bash | grep “commands” passes the formatted contents of the bash man page to the grep tool, which searches those contents for any lines containing the word “commands.” The result is a listing of only those lines with the specified text, instead of the entire man page. See the bash man page for more information about redirection. Chapter 1 Executing Commands 23 Using Environment Variables Some commands require the use of environment variables for their execution. Environment variables are variables inherited by all commands executed in the shell’s context. The shell itself uses environment variables to store information, such as the name of the current user, the name of the host computer, and the paths to any commands. You can also create environment variables and use them to control the behavior of your command without modifying the command itself. For example, you might use an environment variable to tell your command to print debug information to the console. To set the value of an environment variable, you use the appropriate shell command to associate a variable name with a value. For example, to set the variable PATH to the value /bin:/sbin:/user/bin:/user/sbin:/system/Library/, you would enter the following command in a Terminal window: $ PATH=/bin:/sbin:/user/bin:/user/sbin:/system/Library/ export PATH This will modify the environment variable PATH with the value assigned. To view all of the environment variables, enter the following: $ env When you launch an application from a shell, the application inherits much of the shell’s environment, including any exported environment variables. This form of inheritance can be a useful way to configure the application dynamically. For example, your application can check for the presence (or value) of an environment variable and change its behavior accordingly. Different shells support different semantics for exporting environment variables, so see the man page for your preferred shell for further information. Although child processes of a shell inherit the environment of that shell, shells are separate execution contexts that do not share environment information with one another. Thus, variables you set in one Terminal window are not set in other Terminal windows. Once you close a Terminal window, any variables you set in that window are gone. If you want the value of a variable to persist between sessions and in all Terminal windows, you must set it in a shell startup script. Another way to set environment variables in Mac OS X is with a special property list in your home folder. At login, the computer looks for the ~/.MacOSX/environment.plist file. If the file is present, the computer registers the environment variables in the property-list file. 24 Chapter 1 Executing Commands Executing Commands and Running Tools To execute a command in the shell, you must enter the complete pathname of the tool’s executable file, followed by any arguments, and then press the Return key. If a command is located in one of the shell’s known folders, you can omit any path information and just enter the command name. The list of known folders is stored in the shell’s PATH environment variable and includes the folders containing most of the command-line tools. For example, to run the ls command in the current user’s home folder, you could simply enter it at the command line and press the Return key. host:~ anne$ ls To run a command in the current user’s home folder, you would precede it with the folder specifier. For example, to run MyCommandLineProg, you would use something like the following: host:~ anne$ ./MyCommandLineProg To launch a tool package, you can either use the open command (open MyProg.app) or launch the tool by typing the pathname of the executable file inside the package, usually something like ./MyProg.app/Contents/MacOS/MyProg. When entering commands, if you get the message command spelling. not found, check your server:/ anne$ serversetup -getAllPort serversetup: Command not found. If the error recurs, the command you’re trying to run might not be in your default search path. You can add the path before the command name, for example: server:/ anne$ /System/Library/ServerSetup/serversetup -getAllPort 1 Built-in Ethernet or change your working folder to the folder that contains the tool. For example: server:/ anne$ cd /System/Library/ServerSetup server:/System/Library/ServerSetup anne$ ./serversetup -getAllPort 1 Built-in Ethernet or server:/System/Library/ServerSetup anne$ cd / server:/ anne$ PATH="$PATH:/System/Library/ServerSetup" server:/ anne$ serversetup -getAllPort 1 Built-in Ethernet Chapter 1 Executing Commands 25 Correcting Typing Errors To correct a typing error before you press Return to execute the command, press Left Arrow or Right Arrow to skip over parts of the command you don’t want to change, press the Delete key to remove characters, enter regular characters to insert them, and finally press Return to execute the command. To ignore what you have entered and start again, press Control–U. Repeating Commands To repeat a command, press Up Arrow until you see the command, make any modifications, and then press Return. Including Paths Using Drag and Drop To include a fully qualified filename or folder path in a command, you can drag and drop the folder or file from a Finder window into the Terminal window. Searching for Text Within a File To locate a unique string within a file, use the grep tool. The grep tool searches the named input files for lines containing a match to the given pattern. By default, grep prints the matching lines. To search for a unique string in a file: $ grep sunshine filename where filename is the name of the file you wish to search through and sunshine is the unique string. Commands Requiring Root Privileges Many commands used to manage a server must be executed by the root user. If you get a message such as permission denied, the command probably requires root privileges. To execute a single command as the root user, begin the command with sudo (short for super user do). For example: $ sudo serveradmin list You’re prompted for the root password if you haven’t used sudo recently. The root user password is set to the administrator user password when you install Mac OS X Server. To switch to the root user so you don’t have to repeatedly enter sudo, use the su command: $su root You’re prompted for the root user password and then are logged in as the root user until you log out or use the su command to switch to another user. 26 Chapter 1 Executing Commands Important: As the root user, you have sufficient privileges to do things that can cause your server to stop working properly. Don’t execute commands as the root user unless you know what you’re doing. Logging in as an administrator user and using sudo selectively might prevent you from making unintended changes. Terminating Commands To terminate the currently running command, enter Control-C. This keyboard shortcut sends an abort signal to the command. In most cases this causes the command to terminate, although commands may install signal handlers to trap this signal and respond differently. Scheduling Tasks You can create scheduled tasks using the cron tool. cron is a daemon that executes scheduled commands from a crontab file. The cron tool searches the /var/cron/tabs folder for crontab files that are named after accounts in /etc/passwd, and loads the files into memory. cron also searches for crontab files in the /etc/crontab folder, which are in a different format. cron then cycles every minute, examining all stored crontab files and checking each command to see if it should be run in the current minute. When commands execute, any output is mailed to the owner of the crontab file or to the user named in the MAILTO environment variable in the crontab file, if such exists. When a crontab file has been modified, cron needs to be restarted. crontab is the program used to install, deinstall, or list the tables used to drive the cron daemon. Each user can have their own crontab file. To configure your crontab file, use the crontab crontab file. -e command. This displays an empty An example of a configured crontab file: SHELL=/bin/sh PATH=/bin:/sbin:/usr/bin:/usr/sbin HOME=/var/log #min 30 50 15 45 hour 18 23 10 8 mday * * * * month * * * * wday 1-5 0 6 1 command /usr/local/vscanx /usr/local/vscanx /usr/local/vscanx /usr/local/vscanx folder-name --summary folder-name --load /usr/local/conf1 /uz --f /usr/local/biglist Listed below is an explanation of the crontab structure shown above. The following crontab entry schedules a scan operation to run and produce a summary at 18:30 every day, Monday through Friday: 30 18 * * 1-5 /usr/local/vscanx folder-name Chapter 1 Executing Commands 27 The following crontab entry schedules a scan operation to run and produce a summary at 23:50 every Sunday: 50 23 * * 0 /usr/local/vscanx --summary folder-name The following crontab entry schedules a scan operation to run on the uz folder at 10:15 a.m. every Saturday in accordance with options specified in a configuration file conf1: 15 10 * * 6 /usr/local/vscanx --load /usr/local/conf1 /uz The following crontab entry schedules a scan operation to run at 8:45 a.m. every Monday on the files specified in the file biglist: 45 8 * * 1 /usr/local/vscanx --f /usr/local/biglist Sending Commands to a Remote Computer You must connect to a remote computer before you can execute commands on it. You can send commands to a remote computer using:  Secure Shell (SSH), a tool for logging in to a remote computer and for executing commands on a remote computer.  Telnet, a tool for communicating with another computer using the TELNET protocol. See Chapter 2, “Connecting to Remote Computers,” on page 31 for information about sending commands to remote computers. Viewing Command Information Most command-line documentation comes in the form of man pages. These are formatted pages that provide reference information for shell commands, tools, and high-level concepts. You can also access command information using the help command, and sometimes information is displayed if you enter the command without any parameters or options. To access a man page: $ man command where command is the topic you want to find information about. The man page contains detailed information about the command, its options, parameters, and proper use. For help using the man command, enter: $ man man If the man pages are so long that they do not fit on your screen, you can use the more or less command to automatically paginate the file. This allows you to view the file faster by loading full screens of the man page at a time, rather than the entire file. $ man serveradmin | less 28 Chapter 1 Executing Commands When you use more or less, an information bar appears at the bottom of the screen. When you see the bar, you can press the Space bar to go to the next page, the B key to go back a page, or the Return key to scroll the file forward one line at a time. When you get to the end of a file, more will return you to the prompt and less will wait for you to press the Q key to quit. Several third-party Mac OS X applications are available for viewing formatted man pages in scrollable windows. You can find one by choosing Mac OS X Software from the Apple menu, and then seraching for “man page.” Note: Not all commands and tools have man pages. For a list of available man pages, look in /usr/share/man. To access command help, enter the command followed by the -help, -h, --help, or help parameter: $ hdiutil help $ dig -h $ diff --help To view a pop-up list of options and parameters you can use with the command, enter the command without any options or parameters: $ sudo serveradmin Note: Not all techniques work for all commands, and some commands don’t have onscreen help. Chapter 1 Executing Commands 29 30 Chapter 1 Executing Commands 2 Connecting to Remote Computers 2 In this chapter you will find commands you can use to connect to remote computers. Connecting to remote computers helps you manage and configure resources efficiently. This chapter covers using SSH and Telnet to connect to remote computers. Understanding Secure Shell Secure Shell (SSH) lets you send secure, encrypted commands to a computer remotely, as if you were sitting at the computer. You use the ssh tool in Terminal to open a command-line connection to a remote computer. While the connection is open, commands you enter are performed on the remote computer. Note: You can use any application that supports SSH to connect to a computer running Mac OS X or Mac OS X Server. How SSH Works SSH works by setting up encrypted tunnels using public and private keys. Here is a description of an SSH session:  The local and remote computers exchange their public keys. If the local computer has never encountered a given public key before, both SSH and a web browser will prompt you whether to accept the unknown key.  The two computers use the public keys to negotiate a session key that is used to encrypt all subsequent session data.  The remote computer attempts to authenticate the local computer using RSA or DSA certificates. If this is not possible, the local computer is prompted for a standard username/password combination. See “Password-Less Logins Using SSH Keys” on page 32 for information about setting up certificate authentication.  After successful authentication, the session begins. Either a remote shell, a secure file transfer, a remote command, or so on, is begun through the encrypted tunnel. 31 You should be aware of the following SSH tools:  sshd—Daemon that acts as a server to all other commands  ssh—Primary user tool: remote shell, remote command, and port-forwarding sessions  scp—Secure copy, a tool for automated file transfers  sftp—Secure FTP, a replacement for FTP Password-Less Logins Using SSH Keys The standard method of SSH authentication is supplying login credentials in the form of a user name and password. Identity key pair authentication enables you to log in to the server without having to supply a password. This process works by:  Generating a private and public key associated with a user name to establish that user’s authenticity. When you attempt to log in as that user, the user name is sent to the remote computer.  The remote computer looks in the user’s .ssh/ folder for the user’s public key. This folder is created after using SSH the first time.  A challenge is then sent to the user based on his or her public key.  The user verifies his or her identity by using the private portion of the key pair to decode the challenge.  Once decoded, the user is logged in without the need for a password. This is especially useful when automating remote scripts. To generate the identity key pair, use the following command on the local computer: $ ssh-keygen -t dsa When prompted, enter a filename in which to save the keys in the user’s folder. Then enter a password followed by password verification (empty for no password). For example: Generating public/private dsa key pair. Enter file in which to save the key (/Users/anne/.ssh/id_dsa): 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 annejohnson1@mac.com This creates two files. Your identification or private key is saved in one file (frog in our example) and your public key is saved in the other (frog.pub in our example). The key fingerprint, which is derived cryptographically from the public key value, is also displayed. This secures the public key, making it computationally infeasible for duplication. 32 Chapter 2 Connecting to Remote Computers Copy the resultant public file, which contains the local computer’s public key to the user’s home folder in .ssh/ on the remote computer. The next time you log in to the remote computer from the local computer you won’t need to enter a password. Note: If you are using an Open Directory user account and have already logged in using the account, you do not have to supply a pasword for SSH login. On Mac OS X Server computers, SSH uses Kerberos for single sign-on authentication with any user account that has an Open Directory password (Kerberos must be running on the Open Directory server). See the Open Directory administration guide for more information. Updating SSH Key Fingerprints The first time you connect to a remote computer using SSH, the local computer prompts for permission to add the remote computer’s fingerprint (or encrypted public key) to a list of known remote computers. You might see a message like this: The authenticity of host "server1.example.com" can’t be established. RSA key fingerprint is a8:0d:27:63:74:f1:ad:bd:6a:e4:0d:a3:47:a8:f7. Are you sure you want to continue connecting (yes/no)? The first time you connect, you have no way of knowing whether this is the correct host key. Most people respond “yes.” The host key is then inserted into the ~/.ssh/ known_hosts file so it can be compared against in later sessions. Be sure this is the correct key before accepting it. If at all possible, provide your users with the encryption key either through FTP, email, or a download from the web, so they can be sure of the identity of the server. If you later see a warning message about a man-in-the-middle attack when you try to connect, it might be because the key on the remote computer no longer matches the key stored on the local computer. This can happen if you:  Change your SSH configuration on either the local or remote computer.  Perform a clean installation of the server software on the computer you are attempting to log in to using SSH.  Start up from a Mac OS X Server CD on the computer you are attempting to log in to using SSH.  Are attempting to SSH in to a computer that has the same IP address as a computer that you previously used SSH with on another network. To connect again, delete the entries corresponding to the remote computer (which can be stored by both name and IP address) in the file ~/.ssh/known_hosts. Chapter 2 Connecting to Remote Computers 33 What is an SSH Man-in-the-Middle Attack? An attacker may be able to get access to your network and compromise proper routing information, such that packets intended for a remote computer are instead routed to the attacker who impersonates the remote computer to the local computer and the local computer to the remote computer. Here’s a typical scenario: A user connects to the remote computer using SSH. By means of spoofing techniques, the attacker poses as the remote computer and receives the information from the local computer. The attacker then relays the information to the intended remote computer, receives a response, and then relays the remote computer’s response to the local computer. Throughout the process, the attacker is privy to all the information that goes back and forth, and can modify it. A sign that may indicate a man-in-the-middle attack is the following message when connecting to the remote computer using SSH. @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ Protect against this type of attack by verifying that the host key sent back is the correct host key for the computer you are trying to reach. Be watchful for the warning message, and alert your users to its meaning. Important: Removing an entry from the known_hosts file bypasses a security mechanism that would help you avoid imposters and man-in-the-middle attacks. Be sure you understand why the key on the remote computer has changed before you delete its entry from the known_hosts file. Controlling Access to SSH Service You can use Server Admin to control which users can open a command-line connection using the ssh tool in Terminal. Users with administrator privileges are always allowed to open a connection using SSH. The ssh tool uses the SSH service. For information about controlling access to the SSH service, see the Open Directory administration guide. 34 Chapter 2 Connecting to Remote Computers Connecting to a Remote Computer You can connect to a remote computer using SSH (secure) or Telnet (non-secure). Using SSH Use the ssh tool to create a secure shell connection to a remote computer. To access a remote computer using ssh: 1 Open Terminal. 2 Enter the following command to log in to the remote computer, and then press Return: $ ssh -l username server where username is the name of an administrator user on the remote computer and server is the name or IP address of the remote computer. For example: $ ssh -l anne 10.0.1.2 3 If this is the first time you’ve connected to the remote computer, you’re prompted to continue connecting after the remote computer’s RSA fingerprint is displayed. Enter yes and press Return. 4 When prompted, enter the user’s password (the user’s password on the remote computer) and press Return. The command prompt changes to show that you’re now connected to the remote computer. In the case of the previous example, the prompt might look like: 10.0.1.2:~ anne$ 5 To send a command to the remote computer, enter the command and press Return. To close a remote connection, enter logout and press Return. To authenticate and send a command using a single line, append the command you want to execute to the basic ssh tool. For example, to delete a file: $ ssh -l anne server1.example.com rm /Users/anne/Documents/report or $ ssh -l anne@server1.example.com "rm /Users/anne/Documents/report" You’re prompted for the user’s password. Chapter 2 Connecting to Remote Computers 35 Using Telnet Use the telnet tool to create a Telnet connection to a remote computer. Because it isn’t as secure as SSH, Telnet access is disabled by default. To enable Telnet access: $ service telnet start To disable Telnet access: $ service telnet stop You are strongly advised not to enable Telnet. When you log in using Telnet, your login information, user name, and password are passed along the Internet in clear text. In fact, your entire Telnet session is also passed along the Internet in clear text. Any person on the network running tcpdump, ethereal, or similar applications can effortlessly sniff the network and take possession of your user name and password. If you run something as root during your Telnet session, your root user account will be compromised as well. To access a remote computer using telnet: $ telnet -l username server where username is the name of an administrator user on the remote computer and server is the name or IP address of the remote computer. For example: $ telnet -l anne 10.0.1.2 Once connected, the remote computer will prompt for a login name, and then the password. Depending on the type of computer you are accessing, you may see a message of the form: TERM = (vt100) Press Enter to accept this default setting. You may see a series of messages on the screen, followed by the remote computer’s prompt. You are now completely logged in. When you are finished working, log out from the remote computer by typing logout or exit at the remote computer’s prompt. The telnet client will automatically exit when you log out from the remote computer. See the telnet man page for more information. 36 Chapter 2 Connecting to Remote Computers 3 Installing Server Software and Finishing Basic Setup 3 In this chapter you will find commands you can use to install, set up, and update Mac OS X Server software on local or remote computers. Some computers come with Mac OS X Server software already installed. However, you might want to upgrade from a previous version, change a computer configuration, automate software installation, or completely refresh your server environment. This chapter covers the commands needed to perform a variety of software setup and installation tasks. Installing Server Software You can use the /usr/sbin/installer tool to install Mac OS X Server or other software on a computer. You can use the installer tool locally or remotely. The installer tool requires at least two arguments: the installation package, and the destination of the installation package. For a standard installation, your target would be the root drive. Here is an example installation command: $ installer -pkg OSInstall.mpkg -target / Other useful options include:  lang—The operating system package requires that you choose a language. This flag allows you to do so from the command line. The argument is a two-character ISO language code. For English, it’s en.  verbose—Prints out the details of the installation. It’s useful for monitoring progress. See the installer man page for detailed information. To use installer to install Mac OS X Server software: 1 Start the target computer from the first installation CD or the installation DVD. The procedure you use depends on the target computer hardware. If the target computer has a keyboard and an optical drive, insert the first installation disc into the optical drive. Then hold down the C key on the keyboard while restarting the computer. 37 If the target computer is an Xserve with a built-in optical drive, start the computer using the first installation disc by following the instructions for starting from a system disc in the Xserve User’s Guide. If the target computer is an Xserve with no built-in optical drive, you can start it in target disk mode and insert the installation disc into the optical drive on your administrator computer. You can also use an external FireWire optical drive or an optical drive from another Xserve system to start the computer from the installation disc. Instructions for using target disk mode and external optical drives are in the Quick Start guide or Xserve User’s Guide that came with your Xserve system. 2 If you’re installing on a local computer, when Installer opens choose Utilities > Open Terminal to open the Terminal application. If you’re installing on a remote computer, from Terminal on an administrator computer or from a UNIX workstation, establish an SSH session as the root user with the target computer, substituting the target computer’s actual IP address for : $ ssh root@ If you don’t know the IP address, you can use the sa_srchr tool to identify computers on the local subnet on which you can install server software: $ /System/Library/Serversetup/sa_srchr 224.0.0.1 mycomputer.example.com#PowerMac4,4# # #Mac OS X Server 10.4#RDY4PkgInstall#2.0#512 You can also use Server Assistant to generate information for computers on the local subnet. Open Server Assistant, select “Install software on a remote computer,” and click Continue to access the Destination pane and generate a list of computers awaiting installation. 3 When prompted for a password, enter the first eight digits of the computer’s built-in hardware serial number. To find a computer’s serial number, look for a label on the computer. If the target computer had been set up as a server, you’ll also find the hardware serial number in /System/Library/ServerSetup/SerialNumber. If you’re installing on an older computer that has no built-in hardware serial number, use 12345678 for the password. Locating Computers for Installation If you are installing software on a remote computer from Terminal, you will first want to establish an SSH session as the root user with the remote computer. To do so, you need the remote computer’s IP address and serial number. You can find the serial number on a label on the computer. Enter the serial number as the password when establishing the SSH session. If you are installing on an older computer that has no built-in hardware serial number, use 12345678 for the password. You can use the sa_srchr tool to identify the IP address of each computer that’s ready for installation on your subnet. 38 Chapter 3 Installing Server Software and Finishing Basic Setup Note: To locate computers, you must have booted the computer from the installation CD. To list computers on the local network: $ /System/Library/ServerSetup/sa_srchr 224.0.0.1 The sa_srchr tool uses the broadcast address 224.0.0.1 to request a response (via sa_rspndr) from all computers ready for installation or setup. The response from a ready computer would come from sa_rspndr running on a computer started up from the Mac OS X Server installation CD. The computer will respond with output similar to the following: localhost#unknown# # #Mac OS X Server 10.3#RDY4PkgInstall#2.0#512 where is the working IP address and is the unique MAC address of the network interface on a computer that is ready for installation. Specifying the Target Computer Volume Use the installer tool to specify the target computer volume onto which you want to install the server software. To list volumes available for server software: $ /usr/sbin/installer -volinfo -pkg /System/Installation/Packages/ OSInstall.mpkg To choose a network installation image you’ve created and mounted: $ /usr/sbin/installer -volinfo -pkg /Volumes/ServerNetworkImage10.4/System/ Installation/Packages/OSInstall.mpkg The list displayed reflects your particular environment, but here’s an example showing three available volumes: /Volumes/Mount 01 /Volumes/Mount1 /Volumes/Mount02 Preparing the Target Volume for a Clean Installation If the target volume has Mac OS X Server version 10.3 or version 10.2.8 installed, when you run installer, it will upgrade the server to version 10.4 and preserve user files. If you’re not upgrading but performing a clean installation, back up the user files you want to preserve, then use diskutil to erase the volume, format it, and enable journaling: $ /usr/sbin/diskutil eraseVolume HFS+ "Mount 01" "/Volumes/Mount 01" $ /usr/sbin/diskutil enableJournal "/Volumes/Mount 01" Chapter 3 Installing Server Software and Finishing Basic Setup 39 You can also use diskutil to partition the volume and to set up mirroring. For more information, see the diskutil man page or Chapter 7, “Working with Disks and Volumes,” on page 83. Important: Don’t store data on the hard disk partition where the operating system is installed. If you must store additional software or data on the system partition, consider mirroring the drive. With this approach, you won’t risk losing data if you need to reinstall or upgrade system software. Installing from Multiple CDs If you’re using CDs for server installation, use the sa_srchr tool to install the remaining software from the remaining installation CDs. Server Assistant opens automatically when installation is complete. 1 To use the next installation disc, use the sa_srchr command to locate the computer that’s waiting. For , specify the address you used in step 2: $ /System/Library/Serversetup/sa_srchr 2 When the sa_srchr response includes the string “#InstallInProgress”, insert the next installation disc: $ mycomputer.example.com#PowerMac4,4# # #Mac OS X Server 10.4#InstallInProgress#2.0#2080 Restarting After Installation When installation from the disc is complete, restart the computer. Enter: $ /sbin/reboot or $ /sbin/shutdown -r Automating Server Setup Normally when you install Mac OS X Server on a computer and restart, Server Assistant opens and prompts you for the basic information necessary to get the server up and running. This includes the user name and password of the administrator, the TCP/IP configuration information for the computer’s network interfaces, and how the computer uses directory services. You can automate this initial setup task by providing a configuration file that contains these settings. Servers that have previously had Mac OS X Server version 10.4 installed automatically detect the presence of the saved setup information and use it to complete initial server setup without user interaction. 40 Chapter 3 Installing Server Software and Finishing Basic Setup You can define generic setup data that can be used to set up any computer. For example, you might want to define generic setup data for a computer that’s on order, or to configure 50 Xserve computers you want to be identically configured. You can also save setup data that’s specifically tailored for a particular computer. Important: When you perform an upgrade installation, saved setup data is used and overwrites existing server settings. If you do not want saved server setup data to be used after an upgrade, rename the saved setup configuration file. Creating a Configuration File An easy way to prepare configuration files to automate the setup of a group of computers is to start with a file saved using Server Assistant. You can save the file as the last step when you use Server Assistant to set up the first computer, or you can run Server Assistant later to create the file. You can then use that configuration file as a template for creating configuration files for other computers. You can edit the file directly, or write scripts to create customized configuration files for any number of computers that use similar hardware. Note: If you intend to create a generic configuration file because you want to use the file to set up more than one computer, don’t specify network names (computer name and local hostname), and make sure that each network interface (port) is set to be configured using DHCP or using BootP. To save a configuration file during server setup: 1 In the final pane of Server Assistant, after you review the settings, click Save As. 2 In the dialog that appears, choose Configuration File next to “Save As” and click OK.  If encryption is not required, don’t select “Save in Encrypted Format.”  To encrypt the file, select “Save in Encrypted Format” and then enter and verify a passphrase. You must supply the passphrase before an encrypted setup file can be used by a target computer. 3 Navigate to the location where you want to save the configuration file, name the file using one of the following options, and click Save; when searching for setup files, target computers search for names in the order listed:  MAC-address-of-server.plist (include any leading zeros but omit colons)—For example, 0030654dbcef.plist.  IP-address-of-server.plist—For example, 10.0.0.4.plist.  partial-DNS-name-of-server.plist—For example, myserver.plist.  built-in-hardware-serial-number-of-server.plist (first 8 characters only)—For example, ABCD1234.plist.  fully-qualified-DNS-name-of-server.plist—For example, myserver.example.com.plist. Chapter 3 Installing Server Software and Finishing Basic Setup 41  partial-IP-address-of-server.plist—For example, 10.0.plist (matches 10.0.0.4 and 10.0.1.2).  generic.plist—A file that any server will recognize, used to set up servers that need the same setup values. Server Assistant uses the file to set up the computer with the matching address, name, or serial number. If Server Assistant cannot find a file named for a particular computer, it will use the file named generic.plist. To create a configuration file at any time after initial setup: 1 Open Server Assistant (located in /Applications/Server/). 2 In the Welcome pane, select “Save setup information in a file or folder record” and click Continue. 3 Enter settings in the remaining panes, then, after you review the settings in the final pane, click Save As. 4 In the dialog that appears, choose Configuration File next to “Save As” and click OK.  If encryption is not required, don’t select “Save in Encrypted Format.”  To encrypt the file, select “Save in Encrypted Format” then enter and verify a passphrase. You must supply the passphrase before an encrypted setup file can be used by a target computer. 5 Navigate to the location where you want to save the configuration file, name the file using one of the following options, and click Save; when searching for setup files, target computers search for names in the order listed here:  MAC-address-of-server.plist (include any leading zeros but omit colons)—For example, 0030654dbcef.plist.  IP-address-of-server.plist—For example, 10.0.0.4.plist.  partial-DNS-name-of-server.plist—For example, myserver.plist.  built-in-hardware-serial-number-of-server.plist (first 8 characters only)—For example, ABCD1234.plist.  fully-qualified-DNS-name-of-server.plist—For example, myserver.example.com.plist.  partial-IP-address-of-server.plist—For example, 10.0.plist (matches 10.0.0.4 and 10.0.1.2).  generic.plist—A file that any computer will recognize, used to set up computers that need the same setup values. Server Assistant uses the file to set up the computer with the matching address, name, or serial number. If Server Assistant cannot find a file named for a particular computer, it will use the file named generic.plist. 42 Chapter 3 Installing Server Software and Finishing Basic Setup Working with an Encrypted Configuration File If the setup data in the configuration file is encrypted, make the passphrase available to the target computer or computers. You can supply the passphrase interactively using Server Assistant, or you can provide it in a text file. To provide a passphrase in a file: 1 Create a new text file and enter the passphrase for the saved setup file on the first line. 2 Save the file using one of the following names. Target computers search for names in the order listed here:  MAC-address-of-server.pass (include any leading zeros but omit colons)—For example, 0030654dbcef.pass.  IP-address-of-server.pass—For example, 10.0.0.4.pass.  partial-DNS-name-of-server.pass—For example, myserver.pass.  built-in-hardware-serial-number-of-server.pass (first 8 characters only)—For example, ABCD1234.pass.  fully-qualified-DNS-name-of-server.pass—For example, myserver.example.com.pass.  partial-IP-address-of-server.pass—For example, 10.0.pass (matches 10.0.0.4 and 10.0.1.2).  generic.pass—A file that any computer will recognize. 3 Put the passphrase file on a volume mounted locally on the target computer in /Volumes/*/Auto Server Setup/ , where * is any device mounted under /Volumes. To provide a passphrase interactively: 1 Use Server Assistant on an administrator computer that can connect to the target computer. 2 In the Welcome or Destination pane, choose File > Supply Passphrase. 3 In the dialog box, enter the target computer’s IP address, password, and the passphrase. Click Send. Customizing a Configuration File After you create a configuration file, you can modify it directly using a text editor, or write a script to automatically generate custom configuration files for a group of computers. The file uses XML format to encode the setup information. The name of an XML key indicates the setup parameter it contains. Chapter 3 Installing Server Software and Finishing Basic Setup 43 The following example shows the basic structure and contents of a configuration file for a computer with the following configuration:  An administrator user named “Administrator” (short name “admin”) with a user ID of 501 and the password “secret”  A computer name and host name of “server1.example.com”  A single Ethernet network interface set to get its address from DHCP  No server services set to start automatically Note: Angle brackets used in XML format do not have the same usage as angle brackets used in Mac OS X Server commands. Sample Configuration File Note: The actual contents of a configuration file depend on the hardware configuration of the computer on which it’s created, so you should customize a configuration file created on a computer similar to those you plan to set up. 46 Chapter 3 Installing Server Software and Finishing Basic Setup Storing a Configuration File in an Accessible Location Server Assistant looks for configuration files in the following location: /Volumes/vol/Auto Server Setup/ where vol is any device volume mounted in /Volumes. Devices you can use to provide configuration files include:  A partition on one of the computer’s hard disks  An iPod  An optical (CD or DVD) drive  A USB or FireWire drive  Any other portable storage device that mounts in the /Volumes folder Configuring the Server Remotely from the Command Line It’s possible to configure the server remotely from the command line. Performing this task requires the following tools:  dscl—Directory service command line is a general purpose tool that allows you to create, read, and manage directory service data. If invoked without any commands, dscl runs interactively, reading commands from standard input. See Chapter 8, “Working with Users and Groups,” for more information about the usage of this command.  systemsetup—Use systemsetup to set a number of system-wide preferences. If you were going through Server Assistant, you would have to select the proper keyboard and time zone. The systemsetup tool can configure both these preferences, and more. See Chapter 5, “Setting General System Preferences,” for mor information on the usage of this command.  networksetup—Anything that you can configure in the Network pane of System Preferences can also be configured using networksetup. See Chapter 6, “Setting Network Preferences,” for more information about the usage of this command. See the man pages related to these tools for more information. The man pages for systemsetup and networksetup are only available on Mac OS X Server. Chapter 3 Installing Server Software and Finishing Basic Setup 47 Changing Server Settings After initial setup, you can use a variety of commands to view or change Mac OS X Server configuration settings and services. Using the serversetup Tool The serversetup tool is located in /System/Library/ServerSetup. To run it, you can enter the full path: $ /System/Library/ServerSetup/serversetup -getAllPort If you want to use the tool to perform several commands, you can change your working folder and enter a shorter command: $ cd /System/Library/ServerSetup $ ./serversetup -getAllPort $ ./serversetup -getDefaultInfo Or, add the folder to your search path for this session and enter an even shorter command: $ PATH="$PATH:/System/Library/ServerSetup" $ serversetup -getAllPort To permanently add the folder to your search path, add the path to the file /etc/profile. Using the serveradmin Tool The serveradmin tool is used for administering service-related tasks. Some services need to be restarted after you change certain settings. If you make a change using a service’s writeSettings tool that requires you to restart the service, the output from the command includes the setting AdminUser exists name admin password secret realname Administrator uid 501 ComputerName server1.example.com DS DSClientInfo 2 - NetInfo client - broadcast dhcp static -192.168.42.250 network DSClientType 2 DSType 2 - directory client HostName server1.example.com InstallLanguage English Keyboard DefaultFormat 44 Chapter 3 Installing Server Software and Finishing Basic Setup0 DefaultScript 0 ResID 0 ResName U.S. ScriptID 0 NetworkInterfaces ActiveAT ActiveTCPIP DNSDomains example.com DNSServers 192.168.100.10 DeviceName en0 EthernetAddress 00:0a:93:bc:6d:1a PortName Built-in Ethernet Settings DHCPClientID Type DHCP Configuration PrimaryLanguage English Bonjour BonjourEnabled BonjourName beasbe3 SerialNumber XSVR-123-456-A-BCD-7EF-GHI-89J-1KL-MNO-2 Chapter 3 Installing Server Software and Finishing Basic Setup 45ServiceNTP HostNTP HostNTPServer Local UseNTP ServicesAutoStart ARD Apache FTP File IChat NetBoot QTSS SMB SWUPD WebDAV Weblog XgridA XgridC TimeZone US/Pacific VersionNumber 2 :needsRecycleOrRestart with a value of yes. Important: The needsRecycleOrRestart setting is displayed only if you use the serveradmin svc:command = writeSettings command to change settings. You won’t see it if you use the serveradmin settings command. Other chapters in this guide have information about using the serveradmin tool to administer specific services. Notes on Communication Security and the servermgrd Tool When you run the serveradmin tool, you’re communicating with a local or remote servermgrd process.  servermgrd uses SSL for encryption and client authentication, but not for user authentication. User authentication uses Open Directory services.  servermgrd uses a self-signed (test) SSL certificate installed by default, located in /etc/servermgrd/ssl.crt/. You can replace this with an actual certificate. You can use the Certificate Manager in Server Admin to create and manage certificates. See the mail service administration guide for more information. 48 Chapter 3 Installing Server Software and Finishing Basic Setup  The default certificate format for SSLeay/OpenSSL is PEM. PEM format can contain private keys (RSA and DSA), public keys (RSA and DSA), and (x509) certificates. It stores data in Base64-encoded DER format with ASCII header and footer lines which makes it suitable for text-made transfers between computers. For some tools, you need the certificate in plain DER format. You can convert a PEM file (cert.pem) into the corresponding DER file (cert.der) with the following command: $ openssl x509 -in cert.pem -out cert.der -outform DER  checks the validity of the SSL certificate only if the “Require valid digital signature” option is selected in Server Admin preferences. This option uses an SSL certificate installed on a remote server to ensure that the remote server is a valid server. If this option is enabled, the certificate must be valid and not expired, or Server Admin will refuse to connect. Before enabling this option, use the instructions in the Mail Service administration guide for generating a Certificate Signing Request (CSR), obtaining an SSL certificate from an issuing authority, and installing the certificate on each remote server. Instead of placing files in /etc/httpd/, place them in /etc/servermgrd/. You can also generate a self-signed certificate and install it on the remote server.  The servermgrd SSL encryption options can be changed at any time by editing the com.apple.servermgrd.plist configuration file located in /Library/Preferences/. Your SSL certificate (ssl.crt/server.crt) and keyfile (ssl.key/server.key) are located in / private/etc/servermgrd/. servermgrd General and Network Preferences See the following for information about changing general system preferences and network settings:  Chapter 5, “Setting General System Preferences,” on page 57  Chapter 6, “Setting Network Preferences,” on page 63 Viewing, Validating, and Setting the Software Serial Number You can use the serversetup tool to view or set the server’s software serial number or to validate a server software serial number. The serversetup tool is located in /System/ Library/ServerSetup. To display the server’s software serial number: $ sudo serversetup -getServerSerialNumber To set the server software serial number: $ sudo serversetup -setserverSerialNumber serialnumber watermarkinformation where serialnumber is a valid Mac OS X Server software serial number, as found on the software packaging that comes with the software. Chapter 3 Installing Server Software and Finishing Basic Setup 49 To validate a server software serial number: $ sudo serversetup -verifyServerSerialNumber serialnumber watermarkinformation Displays 0 if the serial number is valid, or 1 if the serial number is invalid. Serial numbers generated for the server can be generated with watermarks so that they can be tracked to a specific company, group, or individual. If a serial number has watermarking strings associated with it, then it is necessary to supply the watermark information when setting or validating the serial number. To check whether a serial number is site licensed: $ sudo serversetup -issitelicensedserialnumber Updating Server Software You can use the softwareupdate tool to check for and install software updates over the Internet from Apple’s website. To check for available updates: $ sudo softwareupdate --list The output will be similar to the following: Software Update Tool Copyright 2002-2005 Apple Software Update found the following new or updated software: - WebObjects5.3.1ServerUpdate-5.3.1 WebObjects5.3.1 Server Update (5.3.1), 29110K [recommmended] [restart] * J2SE50Release3-3.0 **PRERELEASE** J2SE 5.0 Release 3 (8M318) (3.0), 44020K [recommmended] - AirPort-1.0 AirPort Update 2005-001 (1.0), 1440K [restart] To install an update: $ sudo softwareupdate --install update-version Parameter Description update-version The hyphenated product version string that appears in the list of updates when you use the --list option. Some updates require that you agree to a license agreement. To work around this in an automated command-line environment, execute the following command before running softwareupdate: $ command_line_install=1 export command_line_install 50 Chapter 3 Installing Server Software and Finishing Basic Setup This creates an environment variable named command_line_install that automates the update responses. See the softwareupdate man page for more information about the command. Moving a Server Try to place a server in its final network location (subnet) before setting it up for the first time. If you’re concerned about unauthorized or premature access, you can set up a firewall to protect the server while you’re finishing its configuration. If you must move a server after initial setup, you need to change settings that are sensitive to network location before the server can be used. For example, the server’s IP address and host name—stored in both folders and configuration files that reside on the server—must be updated. When you move a server, consider these guidelines:  Minimize the time the server is in its temporary location so the information you need to change is limited.  Don’t configure services that depend on network settings until the server is in its final location. Such services include Open Directory replication, Apache settings (such as virtual hosts), DHCP, and other network infrastructure settings on which other computers depend.  Wait to import final user accounts. Limit accounts to test accounts so you minimize the user-specific network information (such as home folder location) that will need to change after the move.  After you move the server, use the changeip tool to change IP addresses, host names, and other data stored in Open Directory, NetInfo, and LDAP folders on the server. See “Changing a Server’s IP Address” on page 66. You may need to manually adjust some network configurations, such as the local DNS database, after using the tool.  Reconfigure the search policy of computers (such as user computers and DHCP servers) that have been configured to use the server in its original location. For information about configuring a computer’s search policy, see the Open Directory administration guide. Chapter 3 Installing Server Software and Finishing Basic Setup 51 52 Chapter 3 Installing Server Software and Finishing Basic Setup 4 Restarting or Shutting Down a Computer 4 In this chapter you will find commands you can use to shut down or restart a local or remote computer. Computers often must be shut down or restarted, whether locally or remotely, when installing new tools or making computer repairs. This chapter covers the commands needed to shut down or restart a local or remote computer. Restarting a Computer You can use the reboot or shutdown -r command to restart a computer at a specific time. See the relevant man pages for more information. To restart the local computer: $ shutdown -r now To restart a remote computer immediately: $ ssh -l root computer shutdown -r now To restart a remote computer at a specific time: $ ssh -l root 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 Restart You can also use the systemsetup tool to set up the computer to start automatically after a power failure or system freeze. See “Viewing or Changing Automatic Restart Settings” on page 59. 53 Changing a Remote Computer’s Startup Disk You can change a remote computer’s startup disk using SSH. To change the startup disk: Log in to the remote computer using SSH and enter: $ bless -folder "/Volumes/disk/System/Library/CoreServices" -setBoot Parameter Description disk The name of the disk that contains the desired startup volume. For information about using SSH to log in to a remote computer, see “Sending Commands to a Remote Computer” on page 28. Shutting Down a Computer You can use the shutdown tool to shut down a computer at a specific time. See the shutdown man page for more information. To shut down a remote computer immediately: $ ssh -l root computer shutdown -h now To shut down the local computer in 30 minutes: $ shutdown -h +30 Parameter Description computer The IP address or DNS name of the computer. Manipulating Open Firmware NVRAM Variables You can use the nvram tool to manipulate Open Firmware NVRAM variables. If you modify a value with nvram, the value is saved only if the computer cleanly restarts or shuts down. See the nvram man page for more information. To view the different NVRAM variables: $ nvram -p 54 Chapter 4 Restarting or Shutting Down a Computer Monitoring and Restarting Critical Services In earloier versions of Mac OS X, a daemon called watchdog monitored critical services and restarted them if they failed or quit unexpectedly after a computer restarted. The watchdog daemon relied on the configuration file watchdog.conf, located in /etc. In Mac OS X Server version 10.4, watchdog has been replaced by launchd. The launchd daemon manages other daemons, both for the computer as a whole and for individual users. You can configure the launchd daemon to launch other daemons on demand, based on criteria specified in their respective XML property lists. During system startup, launchd is the first process invoked by the kernel to run and set up the rest of the computer. In Mac OS X Server, it is preferable to have your daemon started by launchd. Note: Some system administrators need to modify the boot process to insert a script or implement a change in the default system configuration. System administrators are encouraged to work with launchd to implement whatever changes they require, and avoid modifying rc or creating a SystemStarter Startup Item. The rc command script may be phased out in the future. The configuration files are located in the following folders: Folder Usage /System/Library/LaunchAgents Configuration for the system /System/Library/LaunchDaemons Configuration for the daemons ~/Library/LaunchAgents Configuration per user Chapter 4 Restarting or Shutting Down a Computer 55 56 Chapter 4 Restarting or Shutting Down a Computer 5 Setting General System Preferences 5 In this chapter you will find commands you can use to set system preferences, usually set using the System Preferences graphical application. You can use Mac OS X Server to manage the work environment of Mac OS X users by defining preferences. Preferences are settings that customize and control a user’s computer experience. Viewing or Changing the Computer Name You can use the systemsetup tool to view or change a computer name (the name used to browse for AFP share points on the server), which would otherwise be set using the Sharing pane of System Preferences. To display the computer name: $ sudo systemsetup -getcomputername or $ sudo networksetup -getcomputername To change the computer name: $ sudo systemsetup -setcomputername computername or $ sudo networksetup -setcomputername computername Viewing or Changing the Date and Time You can use the systemsetup or serversetup tool to view or change:  A computer’s system date or time  A computer’s time zone  Whether a server uses a network time server These settings can also be changed using the Date & Time pane of System Preferences. 57 Viewing or Changing the System Date To view the current system date: $ sudo systemsetup -getdate or $ serversetup -getDate To set the current system date: $ sudo systemsetup -setdate mm:dd:yy or $ sudo serversetup -setDate mm/dd/yy Viewing or Changing the System Time To view the current system time: $ sudo systemsetup -gettime or $ serversetup -getTime To change the current system time: $ sudo systemsetup -settime hh:mm:ss or $ sudo serversetup -setTime hh:mm:ss Viewing or Changing the System Time Zone To view the current time zone: $ sudo systemsetup -gettimezone or $ serversetup -getTimeZone To view the available time zones: $ sudo systemsetup -listtimezones To change the system time zone: $ sudo systemsetup -settimezone timezone or $ sudo serversetup -setTimeZone timezone Viewing or Changing Network Time Server Usage To see if a network time server is being used: $ sudo systemsetup -getusingnetworktime 58 Chapter 5 Setting General System Preferences To enable or disable use of a network time server: $ sudo systemsetup -setusingnetworktime (on|off) To view the current network time server: $ sudo systemsetup -getnetworktimeserver To specify a network time server: $ sudo systemsetup -setnetworktimeserver timeserver Viewing or Changing the Energy Saver Settings You can use the systemsetup tool to view or change a server’s energy saver settings. These can also be changed using the Energy Saver pane of System Preferences. Viewing or Changing Sleep Settings To view the idle time before sleep: $ sudo systemsetup -getsleep To set the idle time before sleep: $ sudo systemsetup -setsleep minutes To see if the system is set to wake for modem activity: $ sudo systemsetup -getwakeonmodem To set the system to wake for modem activity: $ sudo systemsetup -setwakeonmodem (on|off) To see if the system is set to wake for network access: $ sudo systemsetup -getwakeonnetworkaccess To set the system to wake for network access: $ sudo systemsetup -setwakeonnetworkaccess (on|off) Viewing or Changing Automatic Restart Settings To see if the system is set to restart after a power failure: $ sudo systemsetup -getrestartpowerfailure To set the system to restart after a power failure: $ sudo systemsetup -setrestartpowerfailure (on|off) To see how long the system waits to restart after a power failure: $ sudo systemsetup -getWaitForStartupAfterPowerFailure To set how long the system waits to restart after a power failure: $ sudo systemsetup -setWaitForStartupAfterPowerFailure seconds Parameter Description seconds Must be a multiple of 30 seconds. Chapter 5 Setting General System Preferences 59 To see if the system is set to restart after a system freeze: $ sudo systemsetup -getrestartfreeze To set the system to restart after a system freeze: $ sudo systemsetup -setrestartfreeze (on|off) Changing the Power Management Settings You can use the pmset tool to change a variety of power management settings, including:  Display dim timer  Disk spindown timer  System sleep timer  Wake on network activity  Wake on modem activity  Restart after power failure  Dynamic processor speed change  Reduce processor speed  Sleep computer on power button press You can configure different settings for the different power modes using pmset. There are four flags you can use: -a, -b, -c, and -u. -b applies the settings to battery operation, -c to charger (wall power), -u to UPS, and -a to all. To set disk spindown timer for all modes of operation: $ sudo pmset -u spindown minutes Parameter Description minutes Must be a multiple of 30 seconds. To display the current settings: $ sudo pmset -g command See the pmset man page for more information. Viewing or Changing the Startup Disk Settings You can use the systemsetup tool to view or change a computer’s startup disk. This can also be set using the Startup Disk pane of System Preferences. To view the current startup disk: $ sudo systemsetup -getstartupdisk To view the available startup disks: $ sudo systemsetup -liststartupdisks 60 Chapter 5 Setting General System Preferences To change the current startup disk: $ sudo systemsetup -setstartupdisk path Viewing or Changing the Sharing Settings You can use the systemsetup tool to view or change Sharing settings. These can also be set using the Sharing pane of System Preferences. Viewing or Changing Remote Login Settings You can use SSH to log in to a remote server if remote login is enabled. To see if the system is set to allow remote login: $ sudo systemsetup -getremotelogin To enable or disable remote login: $ sudo systemsetup -setremotelogin (on|off) or $ serversetup -enableSSH Telnet access is disabled by default because it isn’t as secure as SSH. You can, however, enable Telnet access. See “Using Telnet” on page 36. Viewing or Changing Apple Event Response To see if the system is set to respond to remote events: $ sudo systemsetup -getremoteappleevents To set the server to respond to remote events: $ sudo systemsetup -setremoteappleevents (on|off) Viewing or Changing the International Settings You can use the serversetup tool to view or change language settings. These can also be set using the International pane of System Preferences. To view the current primary language: $ serversetup -getPrimaryLanguage To view the installed primary language: $ serversetup -getInstallLanguage To change the installation language: $ sudo serversetup -setInstallLanguage language To view the script setting: $ serversetup -getPrimaryScriptCode Chapter 5 Setting General System Preferences 61 Viewing and Changing the Login Settings You can enable or disable the Restart and Shutdown buttons that appear in the login dialog. To disable or enable the Restart and Shutdown buttons in the login dialog: $ sudo serversetup -setDisableRestartShutdown (0|1) 0 disables the buttons and 1 enables the buttons. To view the current setting: $ serversetup -getDisableRestartShutdown 62 Chapter 5 Setting General System Preferences 6 Setting Network Preferences 6 In this chapter you will find commands you can use to change the network settings on a server. Mac OS X Server provides command-line control to manage servers in a mixedplatform environment and to configure, deploy, and manage powerful network services. These tools make it easy to configure and maintain core network services, while providing the advanced features and functionality required by experienced IT professionals. Configuring Network Interfaces Mac OS X Server includes ifconfig, the standard UNIX tool for configuring networks. Both ifconfig and networksetup make system calls to change the interface configuration. However, ifconfig and networksetup do not communicate with each other. ifconfig changes the network interface settings. Warning: If you use ifconfig, your computer will be out of sync and will revert back to the contents of preferences.plist after a restart. You can still use ifconfig to view the entire interface configuration. This is particularly beneficial when your computer is using an autonegotiated Ethernet connection. It’s best to rely on networksetup and serversetup for your manual configuration. You are encouraged to view the man pages of both commands to see all the available configuration options. 63 Managing Network Interface Information This section describes commands you address to a specific hardware device (for example, en0) or port (for example, Built-in Ethernet). If you prefer to work with network port configurations following the approach used in the Network preferences pane of System Preferences, see the commands in “Managing Network Port Configurations” on page 65. Viewing Port Names and Hardware Addresses To list all port names: $ serversetup -getAllPort To list all port names with their Ethernet (MAC) addresses: $ sudo networksetup -listallhardwareports To list hardware port information by port configuration: $ sudo networksetup -listallnetworkservices An asterisk (*) in the results marks an inactive configuration. To view the default (en0) Ethernet (MAC) address of the server: $ serversetup -getMacAddress To view the Ethernet (MAC) address of a particular port: $ sudo networksetup -getmacaddress (devicename|"portname") To scan for new hardware ports: $ sudo networksetup -detectnewhardware This command checks the computer for new network hardware and creates a default configuration for each new port. Viewing or Changing MTU Values All data that is transmitted over a network travels in data packets. The size of the data packets is called maximum transmission units (MTU), which if too large or too small will affect performance. You can use the networksetup tool to change the MTU size for a port. To view the MTU value for a hardware port: $ sudo networksetup -getMTU (devicename|"portname") To list valid MTU values for a hardware port: $ sudo networksetup -listvalidMTUrange (devicename|"portname") To change the MTU value for a hardware port: $ sudo networksetup -setMTU (devicename|"portname") 64 Chapter 6 Setting Network Preferences Viewing or Changing Media Settings To view the media settings for a port: $ sudo networksetup -getMedia (devicename|"portname") To list valid media settings for a port: $ sudo networksetup -listValidMedia (devicename|"portname") To change the media settings for a port: $ sudo networksetup -setMedia (devicename|"portname") subtype [option1] [option2] [...] Managing Network Port Configurations Network port configurations are sets of network preferences that can be assigned to a particular network interface and then enabled or disabled. The Network pane of System Preferences stores and displays network settings as port configurations. Creating or Deleting Port Configurations To list an existing port configuration: $ sudo networksetup -listallnetworkservices To create a port configuration: $ sudo networksetup -createnetworkservice configuration hardwareport To duplicate a port configuration: $ sudo networksetup -duplicatenetworkservice configuration newconfig To rename a port configuration: $ sudo networksetup -renamenetworkservice configuration newname To delete a port configuration: $ sudo networksetup -removenetworkservice configuration Activating Port Configurations To see if a port configuration is on: $ sudo networksetup -getnetworkserviceenabled configuration To enable or disable a port configuration: $ sudo networksetup -setnetworkserviceenabled configuration (on|off) Changing Configuration Precedence To list the configuration order: $ sudo networksetup -listnetworkserviceorder The configurations are listed in the order that they’re tried when a network connection is established. An asterisk (*) marks an inactive configuration. Chapter 6 Setting Network Preferences 65 To change the order of the port configurations: $ sudo networksetup -ordernetworkservices config1 config2 [config3] [...] Managing TCP/IP Settings TCP/IP is a set of layered protocols that allow shared applications between computers on a high-speed network. You can use the following commands to change the TCP/IP settings of a server. Changing a Server’s IP Address Changing a server’s IP address isn’t as simple as changing the TCP/IP settings. Address information is set throughout the system when you set up the server. To make sure that all the necessary changes are made, use the changeip tool. is a python script that runs tools out of the /usr/libexec/changeip folder. There are currently three tools available: changeip_ds, changeip_jabber, and changeip_mail. changeip The changeip_ds tool updates the following local configuration files:  /Library/Preferences/DirectoryService/DSLDAPv3PlugInConfig.plist  /etc/openldap/slapd_macosxserver.conf  /etc/hostconfig (if there is a static hostname)  /etc/smb.conf The changeip_ds tool also updates the following records in the local NetInfo directory domain, as well as a parent directory domain, if specified:  AuthAuthority and HomeDirectory in user records  Addresses and hostname in machine records  Addresses and hostname in computer records  Mount paths and addresses in mount records  Addresses in LDAP and Password Server config records The changeip_jabber tool updates the jabber configuration using serveradmin. The changeip_mail tool updates the mailman, postfix and imap configurations using serveradmin. 66 Chapter 6 Setting Network Preferences To change a server’s IP address: 1 Run the changeip tool: $ changeip [(directory|-)] old-ip new-ip [old-hostname new-hostname] Parameter Description directory If the server is an Open Directory master or replica, or is connected to a folder system, you must include the path to the folder domain (folder directory domain). For a standalone server, enter “-” instead. old-ip The current IP address. new-ip The new IP address. old-hostname (optional) The current DNS host name of the server. new-hostname (optional) The new DNS host name of the server. See the changeip man page for more information and examples. 2 Use the networksetup or serversetup tool (or the Network pane of System Preferences) to change the server’s IP address in its network settings. 3 Restart the server. To change the IP address of a computer hosting an LDAP master: $ changeip /LDAPv3/127.0.0.1 192.0.0.12 192.0.1.10 oldhost newhost It might still be necessary to change the configuration of computers pointing to this master. To change the IP address of a standalone server: $ changeip - 192.0.0.12 192.0.1.10 oldhost newhost To change the IP address of a server bound to a parent NetInfo directory domain: $ changeip /NetInfo/root/netinfonode 192.0.0.12 192.0.1.10 oldhost newhost To change the IP address of a server bound to a parent NetInfo directory domain, where the old and new IP addresses map to the same name: $ changeip /NetInfo/root/netinfonode 192.0.0.12 192.0.1.10 Viewing or Changing IP Address, Subnet Mask, or Router Address You can use the serversetup and networksetup tools to change a computer’s TCP/IP settings. Important: Changing a computer’s IP address isn’t as simple as changing the TCP/IP settings. You must first run the changeip tool to make sure necessary changes are made throughout the system. See “Changing a Server’s IP Address” on page 66. Chapter 6 Setting Network Preferences 67 To list TCP/IP settings for a configuration: $ sudo networksetup -getinfo "configuration" For example, for Built-In Ethernet, the computer responds with the following output: $ networksetup -getinfo "Built-In Ethernet" Manual Configuration IP Address: 192.168.10.12 Subnet mask: 255.255.0.0 Router: 192.18.10.1 Ethernet Address: 1a:2b:3c:4d:5e:6f To view TCP/IP settings for port en0: $ serversetup -getDefaultinfo (devicename|"portname") To view TCP/IP settings for a particular port or device: $ serversetup -getInfo (devicename|"portname") To change TCP/IP settings for a particular port or device: $ sudo serversetup -setInfo (devicename|"portname") ipaddress subnetmask router To set manual TCP/IP information for a configuration: $ sudo networksetup -setmanual "configuration" ipaddress subnetmask router To validate an IP address: $ serversetup -isValidIPAddress ipaddress Displays 0 if the address is valid, 1 if it isn’t. To validate a subnet mask: $ serversetup -isValidSubnetMask subnetmask To set a configuration to use DHCP: $ sudo networksetup -setdhcp "configuration" [clientID] To set a configuration to use DHCP with a manual IP address: $ sudo networksetup -setmanualwithdhcprouter "configuration" ipaddress To set a configuration to use BootP: $ sudo networksetup -setbootp "configuration" 68 Chapter 6 Setting Network Preferences Viewing or Changing DNS Servers You can use the serversetup tool to view and modify the Domain Name Server (DNS) settings. To view the DNS servers for port en0: $ serversetup -getDefaultDNSServer (devicename|"portname") To change the DNS servers for port en0: $ sudo serversetup -setDefaultDNSServer (devicename|"portname") server1 [server2] [...] To view the DNS servers for a particular port or device: $ serversetup -getDNSServer (devicename|"portname") To change the DNS servers for a particular port or device: $ sudo serversetup -setDNSServer (devicename|"portname") server1 [server2] [...] To list the DNS servers for a configuration: $ sudo networksetup -getdnsservers "configuration" To view the DNS search domains for port en0: $ serversetup -getDefaultDNSDomain (devicename|"portname") To change the DNS search domains for port en0: $ sudo serversetup -setDefaultDNSDomain (devicename|"portname") domain1 [domain2] [...] To view the DNS search domains for a particular port or device: $ serversetup -getDNSDomain (devicename|"portname") To change the DNS search domains for a particular port or device: $ sudo serversetup -setDNSDomain (devicename|"portname") domain1 [domain2] [...] To list the DNS search domains for a configuration: $ sudo networksetup -getsearchdomains "configuration" To set the DNS servers for a configuration: $ sudo networksetup -setdnsservers "configuration" dns1 [dns2] [...] To set the search domains for a configuration: $ sudo networksetup -setsearchdomains "configuration" domain1 [domain2] [...] To validate a DNS server: $ serversetup -verifyDNSServer server1 [server2] [...] To validate DNS search domains: $ serversetup -verifyDNSDomain domain1 [domain2] [...] Chapter 6 Setting Network Preferences 69 Enabling TCP/IP Use the serversetup tool to enable or disable TCP/IP on a computer. To enable TCP/IP on a particular port: $ serversetup -EnableTCPIP [(devicename|"portname")] If you don’t provide an interface, en0 is assumed. To disable TCP/IP on a particular port: $ serversetup -DisableTCPIP [(devicename|"portname")] If you don’t provide an interface, en0 is assumed. Working with VLANs A virtual local area network (VLAN) connects devices that may be on separate physical LANs to perform and communicate as if they were on the same physical LAN. Use the networksetup tool to configure and modify a VLAN. To create a VLAN: $ networksetup -createVLAN name parentdevice tag To delete a VLAN: $ networksetup -deleteVLAN name parentdevice tag To list available VLANs: $ networksetup -listVLANs To list the devices that support VLANs: $ networksetup -listdevicesthatsupportVLAN IEEE 802.3ad Ethernet Link Aggregation Apple introduced the implementation of the IEEE 802.3ad Ethernet Link Aggregation standard as part of the ifconfig tool. IEEE 802.3ad is a standard for bonding or aggregating multiple Ethernet ports into one virtual interface. The aggregated ports appear as a single IP address internally to your computer and tools and externally to other clients on the Internet. Any tool or server that relies on your IP address will continue to work seamlessly without any modifications. The advantage of aggregation is that the virtual interface provides increased bandwidth by merging the bandwidth of the individual ports. The TCP connection load is then balanced across the ports. In addition to load balancing, IEEE 802.3ad provides automatic failover in the event any port or cable fails. All traffic that was being routed over the failed port is automatically rerouted to use one of the remaining ports. This failover is completely transparent to the software using the connection. This feature provides increased bandwidth and automatic failover for the server environment. 70 Chapter 6 Setting Network Preferences Configuring a Network Interface You can configure a network interface for TCP/IP using ifconfig. This tool is used to bring the interface up or down and set the interface IP address and subnet mask. To add an Ethernet interface to a bond virtual device (pseudo device): $ ifconfig bond_interface_name bondev physical_interface The bond_interface_name is the name of the pseudo device and the physical_interface is the actual Ethernet interface you want to associate with the pseudo device, for example, en0. If this is the first physical interface to be associated with the bond interface, the bond interface inherits the Ethernet address from the physical interface. Physical interfaces that are added to the bond have their Ethernet address reprogrammed so that all members of the bond have the same Ethernet address. If the physical interface is subsequently removed from the bond, a new Ethernet address is chosen from the remaining interfaces, and all interfaces are reprogrammed with the new Ethernet address. If no remaining interfaces exist, the bond interface’s Ethernet address is cleared. To remove an Ethernet interface from a bond virtual device (pseudo device): $ ifconfig bond_interface_name -bondev physical_interface The link status of the bond interface depends on the state of link aggregation. If no active partner is detected, the link status will remain inactive. To monitor the IEEE 802.3ad Link Aggregation state, use the -b option. See the ifconfig man page for more information. Configuring Ethernet Link Aggregation You can also use networksetup to configure Ethernet Link Aggregation. The following commands are supported. To display if the device can be added to a bond: $ sudo networksetup -isBondSupported device To create a bond and add devices to it: $ sudo networksetup -createBond name [device1] [device2] [...] To delete a bond: $ sudo networksetup -deleteBond bond To add a device to a bond: $ sudo networksetup -addDeviceToBond device bond To remove a device from a bond: $ sudo networksetup -removeDeviceFromBond device bond To list available bonds: $ sudo networksetup -listBonds Chapter 6 Setting Network Preferences 71 To display a bond status: $ sudo networksetup -showBondStatus bond Managing AppleTalk Settings AppleTalk is a suite of protocols developed to implement file sharing, mail service, and printing between Apple computers. Use the serversetup tool to enable or disable AppleTalk. To enable AppleTalk on a particular port: $ serversetup -EnableAT [(devicename|"portname")] If you don’t provide an interface, en0 is assumed. To disable AppleTalk on a particular port: $ serversetup -DisableAT [(devicename|"portname")] If you don’t provide an interface, en0 is assumed. To enable AppleTalk on en0: $ serversetup -EnableDefaultAT To disable AppleTalk on en0: $ serversetup -DisableDefaultAT To make AppleTalk active or inactive for a configuration: $ sudo networksetup -setappletalk "configuration" (on|off) To check AppleTalk state on en0: $ serversetup -getDefaultATActive To see if AppleTalk is active for a configuration: $ sudo networksetup -getappletalk Managing SNMP Settings Simple Network Management Protocol (SNMP) is a set of standard protocols used to manage and monitor multiplatform computer network devices. SNMP uses a manager/ agent design. SNMP relies on a manager/agent design where the agent provides the interface between the manager and the physical device being managed. SNMP uses five basic messages (GET, GET-NEXT, GET-RESPONSE, SET, and TRAP) to communicate between the manager and the agent. 72 Chapter 6 Setting Network Preferences Installing SNMP To use SNMP for monitoring or data collection, an SNMP agent (snmpd) must be running on the monitored Mac OS X Server host computer. Mac OS X Server version 10.1.5 or later includes a version of SNMP (UCD-SNMP v. 4.2.3 or later). If you do not have the file /usr/sbin/snmpd, then SNMP is not installed. Mac OS X Server version 10.1.4 or earlier require that SNMP be built and installed. Mac OS X Server v10.1.5 or later Admin CDs include the SNMP package on the CD used to install UCDSNMP 4.2.3 on these older systems. If you do not have access to the CD, you may download current SNMP source from the NET-SNMP Project Home Page (www.netsnmp.org/). Warning: Once SNMP is active, anyone with a route to the SNMP host will be able to collect SNMP data from it. To learn more, consult the various SNMP information sources listed below. The default configuration of snmpd uses privileged port 161. For this reason and others, it must be executed by root or by using setuid. You should only use setuid as root if you understand the ramifications. If you do not, seek assistance or additional information. There are flags available for snmpd that will change the UID and GID of the process after it starts. See the snmpd man page for more information. Starting SNMP To start SNMP you have three options:  Click the checkbox to enable SNMP in the Server Admin application. This modifies the hostconfig file for you.  Modify the hostconfig file to start SNMP automatically at system startup.  Start the SNMP agent manually. To start SNMP on Mac OS X Server version 10.4 or later by modifying the hostconfig file: 1 Open the /etc/hostconfig file. 2 Locate the line: SPOTLIGHT=-YES- 3 Immediately above it, add this line: SNMPSERVER=-YES- 4 Save the file. Chapter 6 Setting Network Preferences 73 To start SNMP on Mac OS X 10.4 client computers by modifying the hostconfig file: Mac OS X 10.4 client systems already have the SNMPSERVER:=-NO- line in their hostconfig file by default. 1 Open the /etc/hostconfig file. 2 Locate the line: SNMPSERVER=-NO- 3 Change NO to YES. 4 Save the file. Note: Systems running Mac OS X Server version 10.3 or earlier will need to have the line added. Changing the SNMPSERVER line in the hostconfig file, causes snmpd to be executed during system startup, with no options, as dictated by the /System/Library/ StartupItems/SNMP/SNMP file. For further instruction on editing configuration files, including important precautionary statements, see technical document 106619, “Mac OS X Server: How to Edit Configuration Files”. To start the snmp agent manually: $ /usr/sbin/snmpd Configuring SNMP The configuration (conf ) file for snmpd is typically in the /usr/share/snmp/ folder, and is named snmpd.conf or snmpd.local.conf. If you have an environment variable SNMPCONF, snmpd will read any files named snmpd.conf and snmpd.local.conf in these folders. The SNMP agent can be started with a -c flag to indicate other conf files. See the snmpd man page for more information about which conf files can be used. Configuration files can be created and installed more easily using the included script /usr/bin/snmpconf. As root, use this script with the -i flag to install the file in the /usr/share/snmp/ folder. Otherwise, the default location for the file to be written is the user's home directory (~/). Only root has write permission for /usr/share/snmp/. Because snmpd reads its conf files at startup, changes to the conf files require that the process be stopped and restarted. To do this, you must identify the process id. To identify the process id: $ ps aux |grep snmpd To stop snmpd : $ kill Once snmpd is stopped, you can customize the snmpd.conf file as needed. 74 Chapter 6 Setting Network Preferences To customize the data provided by snmpd, you may add an snmpd.conf file using /usr/bin/snmpconf: $ sudo /usr/bin/snmpconf -i You will then see a series of text menus. Make these choices in this order: 1 Select File: 1 (snmpd.conf ) 2 Select section: 5 (System Information Setup) 3 Select section: 1 (The [typically physical] location of the system) 4 The location of the system: type text string here—such as server_room 5 Select section: f (finish) 6 Select section: f (finish) 7 Select File: q (quit) This creates an snmpd.conf file with a creation date of today. To view the snmp.conf file: $ ls -l /usr/share/snmpd.conf Once the configuration file is created, restart the snmpd process. To start snmpd, execute this as root: $ sudo /usr/sbin/snmpd Collecting SNMP Information from the Host To get the SNMP information you just added, execute this command from a host that has the SNMP tools installed, where hostname is replaced with the actual name of the target host: $ snmpget -v 1 -c public hostname system.sysLocation.0 You should see the location you provided. In this example, you would see: system.sysLocation.0 = server_room The other options in the menu you were working in are: $ snmpget -v 1 -c hostname public system.sysContact.0 $ snmpget -v 1 -c hostname public system.sysServices.0 The final .0 indicates you are looking for the index object. The word public is the name of the SNMP community, which you did not alter. If you need information about either of these, or explanations of SNMP syntax, there are tutorials available at www.netsnmp.sourceforge.net. Another way to retrieve SNMP information is by retrieving a subtree of management values using the snmpwalk tool. Chapter 6 Setting Network Preferences 75 To gather SNMP information in bulk: $ sudo snmpwalk -v 1 -c public localhost This will list multiple entries of SNMP data similar to the following output, where system name and location are defined in the snmp.conf file. SNMPv2-MIB::sysName.0 - system name SNMPv2-MIB::sysLocation.0 - system location SNMPv2-MIB::sysUpTime.0 - time in 1/100ths of a second since the last system start To retrieve specific SNMP management values, use the snmpget tool as shown in the following examples. To view the system name: $ snmpget -v 1 -c public localhost system.sysName.0 SNMPv2-MIB::sysName.0 = STRING: xlabxs06.apple.com To view the system location: $ snmpget -v 1 -c public localhost system.sysLocation.0 SNMPv2-MIB::sysLocation.0 = STRING: "server_room" To view the system uptime: $ snmpget -v 1 -c public localhost system.sysUptime.0 SNMPv2-MIB::sysUpTime.0 = Timeticks: (72239) 0:12:02.39 For a list of snmp man pages, enter the following: $ man -k snmp Managing Proxy Settings The proxy server is a component of Mac OS X Server that functions as a relay between a client and the server. This proxy server protects the network from unauthorized users and allows for a more secure environment. Use the networksetup tool to view or change the proxy settings. Viewing or Changing FTP Proxy Settings To view the FTP proxy information for a configuration: $ sudo networksetup -getftpproxy "configuration" To set the FTP proxy information for a configuration: $ sudo networksetup -setftpproxy "configuration" domain portnumber To view the FTP passive setting for a configuration: $ sudo networksetup -getpassiveftp "configuration" To enable or disable FTP passive mode for a configuration: $ sudo networksetup -setpassiveftp "configuration" (on|off) 76 Chapter 6 Setting Network Preferences To enable or disable the FTP proxy for a configuration: $ sudo networksetup -setftpproxystate "configuration" (on|off) Viewing or Changing Web Proxy Settings To view the web proxy information for a configuration: $ sudo networksetup -getwebproxy "configuration" To set the web proxy information for a configuration: $ sudo networksetup -setwebproxy "configuration" domain portnumber To enable or disable the web proxy for a configuration: $ sudo networksetup -setwebproxystate "configuration" (on|off) Viewing or Changing Secure Web Proxy Settings To view the secure web proxy information for a configuration: $ sudo networksetup -getsecurewebproxy "configuration" To set the secure web proxy information for a configuration: $ sudo networksetup -setsecurewebproxy "configuration" domain portnumber To enable or disable the secure web proxy for a configuration: $ sudo networksetup -setsecurewebproxystate "configuration" (on|off) Viewing or Changing Streaming Proxy Settings To view the streaming proxy information for a configuration: $ sudo networksetup -getstreamingproxy "configuration" To set the streaming proxy information for a configuration: $ sudo networksetup -setstreamingproxy "configuration" domain portnumber To enable or disable the streaming proxy for a configuration: $ sudo networksetup -setstreamingproxystate "configuration" (on|off) Viewing or Changing Gopher Proxy Settings To view the gopher proxy information for a configuration: $ sudo networksetup -getgopherproxy "configuration" To set the gopher proxy information for a configuration: $ sudo networksetup -setgopherproxy "configuration" domain portnumber To enable or disable the gopher proxy for a configuration: $ sudo networksetup -setgopherproxystate "configuration" (on|off) Chapter 6 Setting Network Preferences 77 Viewing or Changing SOCKS Firewall Proxy Settings To view the SOCKS firewall proxy information for a configuration: $ sudo networksetup -getsocksfirewallproxy "configuration" To set the SOCKS firewall proxy information for a configuration: $ sudo networksetup -setsocksfirewallproxy "configuration" domain portnumber To enable or disable the SOCKS firewall proxy for a configuration: $ sudo networksetup -setsocksfirewallproxystate "configuration" (on|off) Viewing or Changing Proxy Bypass Domains To list the proxy bypass domains for a configuration: $ sudo networksetup -getproxybypassdomains "configuration" To set the proxy bypass domains for a configuration: $ sudo networksetup -setproxybypassdomains "configuration" [domain1] domain2 [...] Managing AirPort Settings AirPort uses wireless local area network (WLAN) technology to provide wireless communication between computers. Use the networksetup tool to view or change the AirPort settings. To see if AirPort power is on or off: $ sudo networksetup -getairportpower To turn AirPort power on or off: $ sudo networksetup -setairportpower (on|off) To display the name of the current AirPort network: $ sudo networksetup -getairportnetwork To join an AirPort network: $ sudo networksetup -setairportnetwork network [password] 78 Chapter 6 Setting Network Preferences Managing the Computer, Host, and Bonjour Names These names are used by networking applications to identify a computer. Computer Name The computer name is the local name of a computer. This name is typically assigned to the computer when the operating system is installed. Use the serversetup tool to view or modify the computer name. To display the computer name: $ sudo systemsetup -getcomputername or $ sudo networksetup -getcomputername or $ serversetup -getComputername To change the computer name: $ sudo systemsetup -setcomputername computername or $ sudo networksetup -setcomputername computername or $ sudo serversetup -setComputername computername To validate a computer name: $ serversetup -verifyComputername computername Hostname The host name is a unique name that corresponds to a unique hardware MAC address. It is the name that the network uses to identify a device attached to the network. Use the serversetup tool to view or modify the host name. To display the server’s local host name: $ serversetup -getHostname To change the server’s local host name: $ sudo serversetup -setHostname hostname Note: You can also set and get the host name using snmpd and scutil tools. Chapter 6 Setting Network Preferences 79 Bonjour Name Bonjour, also known as zero-configuration networking, enables automatic discovery of computers, devices, and services on IP networks. Bonjour uses industry-standard IP protocols to allow devices to automatically discover each other without the need to enter IP addresses or configure DNS servers. Specifically, Bonjour enables automatic IP address assignment without a DHCP server, name-to-address translation without a DNS server, and service discovery without a directory server. Use the serversetup tool to view or change the Bonjour name. To display the server’s Bonjour name: $ serversetup -getBonjourname To change the server’s Bonjour name: $ sudo serversetup -setBonjourname bonjourname The command displays 0 if the name was changed. Note: If you use Server Admin to connect to a server using its Bonjour name, then to change the server’s Bonjour name, you will need to reconnect to the server the next time you open the Server Admin application. Managing Preference Files and the Configuration Daemon The various sets of configuration information that a user creates at different locations, whether in System Preferences or through the command line, are stored in the preference.plist file located in /Library/Preferences/SystemConfiguration/. Network configuration is handled by configd, the configuration daemon. configd reads the network configuration and stores it with the current state of the computer’s networking information. This storage is in the form of key-value pairs. The key is a description of what is being stored, and the value is the actual value of the information being stored. You can view the values stored by configd at run time, and monitor them using the scutil tool. This can be especially valuable when you are trying to debug your network configuration from the command line. Invoked with no options, scutil provides a command-line interface to the data that is maintained by configd. For a list of commands you can use with scutil, enter help at the scutil prompt. To start a scutil session (interactive mode), perform the following: $ scutil > open This opens a session with configd. Once the session is open, you can list all of the keys in data store for configd: > list 80 Chapter 6 Setting Network Preferences Each item on the list is a piece of information stored by configd, sorted by type. Setup indicates information that has been read from a configuration file. State indicates information that represents the actual state of the computer. File indicates stored information as of the last time the configuration file was updated. Using scutil, you can view data in the keys. First you must get the data, and then you can show the data. For example: > get State:/Network/Interface/en0/IPv4 > d.show stores the information from the get command in a local dictionary variable called d. You can also watch or monitor a variable, such that if its state changes, scutil will alert you. To quit the scutil session, enter quit at the prompt. scutil > quit You can also manage system configuration parameters from within scutil using the --get and --set options. These provide a means of reporting and updating a select group of persistent system preferences, including ComputerName, LocalHostName, or HostName. To set the hostname of a system: $ sudo scutil --set HostName mycomputer.mac.com Parameter Description mycomputer.mac.com This is the new hostname value you wish to set. To get the hostname of a system: $ scutil --get HostName mycomputer.mac.com See the scutil man page for more information or enter help at the scutil prompt. Changing Network Locations A network location contains all of the network configuration settings for a specific network, such as Ethernet, AirPort, FireWire, or Bluetooth. Each location has a separate set of network settings. Mobile users who switch between networks have multiple locations set up on their computer and may need to switch between locations quickly. scselect allows you to access these configuration sets or locations. Chapter 6 Setting Network Preferences 81 To view the current locations: $ scselect The computer will respond with output similar to the following: Defined sets include: (* == current set) * 0 (Automatic) 1 (AirPort) 2 (Home Office) To change the location, enter the number of the location listed that you want to switch to: $ scselect 1 In this example, the network location will switch to AirPort. 82 Chapter 6 Setting Network Preferences 7 Working with Disks and Volumes 7 In this chapter you will find commands that are used to initialize and test disks and volumes. Computers use disks and partitions to store and organize data. This chapter covers the commands that are used to manage, configure, initialize, and test disks and volumes. Understanding Disks, Partitions, and the File System Like UNIX, Mac OS X uses special files called device files, located in /dev, to keep track of the devices (disks, keyboards, monitors, network connections, and so on) attached to the computer. Device files for a disk are named /dev/diskn, where n is the number of the disk. For example, a computer with one drive would have a device file called /dev/ disk0. If the computer has a second drive, the computer creates a second device file called /dev/disk1, and so on. Each drive that is divided into multiple partitions has a device file for each partition. The first partition on disk 0 would be called /dev/disk0s1, the second partition would be /dev/disk0s2, and so on. Although Mac OS X Server assigns a device name to each device, the files on a particular device are not accessed in this way. A virtual file system is created where all files on all devices appear to exist under a single hierarchy. This sets one root folder and every file exisiting on the computer is under that folder. This is known as the Hierarchical File System (HFS+). The root folder can exist anywhere on a network as a shared resource. Mounting and Unmounting Volumes To gain access to files on a different device, you must first mount the device. This process informs the operating system where in the folder tree you would like those files to appear. The folder given to the operating system is the mount point. Different volumes on a computer may have different file systems. 83 Mounting Volumes You can use the mount tool with parameters appropriate to the type of file system you want to mount, or use one of these file-system–specific mount commands:  mount_afp for Apple File Protocol (AppleShare) volumes  mount_cd9660 for ISO 9660 volumes  mount_cddafs for CD Digital Audio format (CDDA) volumes  mount_hfs for Apple Hierarchical File System (HFS) volumes  mount_msdos for PC MS-DOS volumes  mount_nfs for Network File System (NFS) volumes  mount_smbfs for Server Message Block (SMB/CIFS) volumes  mount_udf for Universal Disk Format (UDF) volumes  mount_webdav for Web-based Distributed Authoring and Versioning (WebDAV) volumes prepares and grafts a special device or the remote node (rhost:path) on to the file system tree at the point node. See the related man pages for more information. mount To view a list of currently mounted file systems: $ sudo mount To mount a network folder: $ mount /dev/ mount returns the value 0 if the mount succeeded. Unmounting Volumes You can use the umount tool to unmount a volume. umount removes a special device or the remote node (rhost:path) from the file system tree at the point node. To unmount a volume: $ umount returns the value 0 if the umount succeeded. See the umount man page for more information. umount 84 Chapter 7 Working with Disks and Volumes Displaying Disk Information The df tool located in /bin is designed to display free disk space. In addition, df is a useful way to find out what your current disk partitions are, how much space each one takes up, which block each partition starts on, which device file is associated with each partition, and where each partition is mounted. To display disk information: $ df The computer will respond with output similar to the following: Filesystem 512-blocks Used Avail Capacity /dev/disk0s3 156039264 26138984 129388280 17% devfs 193 193 0 100% fdesc 2 2 0 100% 1024 1024 0 100% automount -nsl [170] 0 0 0 100% automount -fstab [174] 0 0 0 100% Servers automount -static [174] 0 0 0 100% static Mounted on / /dev /dev /.vol /Network /automount/ /automount/ The -l option restricts reporting to local drives only. The -k option displays sizes in kilobyte format. Each line in the output refers to a different partition. The first column tells you the device file associated with that partition. The second column displays the capacity of the partition followed by used and available space on the volume. The last column tells you where the partition is mounted. Monitoring Disk Space You can monitor the amount of free space on disks and take predefined actions when thresholds are exceeded. When you need more vigilant monitoring of disk space than the log rolling scripts provide, you can use the diskspacemonitor tool. It lets you monitor disk space and take action more frequently than once a day when disk space is critically low, and gives you the opportunity to provide your own action scripts. diskspacemonitor is disabled by default. To enable diskspacemonitor: $ sudo diskspacemonitor on. You may be prompted for your password. See the diskspacemonitor man page for more information. Chapter 7 Working with Disks and Volumes 85 When enabled, diskspacemonitor uses information in a configuration file to determine when to execute alert and recovery scripts for reclaiming disk space:  The configuration file is /etc/diskspacemonitor/diskspacemonitor.conf. It lets you specify how often you want to monitor disk space, and specify thresholds to use for determining when to take the actions in the scripts. By default, disks are checked every 10 minutes, an alert script is executed when disks are 75% full, and a recovery script is executed when disks are 85% full. To edit the configuration file, log in to the server as an administrator and use a text editor to open the file. See the comments in the file for additional information.  By default, two predefined action scripts are executed when the thresholds are reached. The default alert script is /etc/diskspacemonitor/action/alert. It runs in accord with instructions in the configuration file /etc/diskspacemonitor/alert.conf. It sends email to recipients you specify. The default recovery script is /etc/diskspacemonitor/action/recover. It runs in accord with instructions in the configuration file /etc/diskspacemonitor/recover.conf. See the comments in the script and configuration files for more information about these files.  If you want to provide your own alert and recovery scripts, put your alert script in /etc/diskspacemonitor/action/alert.local and your recovery script in /etc/ diskspacemonitor/action/recovery.local. Your scripts will be executed before the default scripts when the thresholds are reached. To configure the scripts on a server from a remote Mac OS X computer, open a Terminal window and log in to the remote computer using SSH. Reclaiming Disk Space Using Log-Rolling Scripts Three predefined scripts are executed automatically, in order to reclaim space used on your server for log files generated by:  Apple file service  Windows service  Web service  Web performance cache  Mail service  Print service 86 Chapter 7 Working with Disks and Volumes The scripts use values in the following configuration files to determine whether and how to reclaim space:  The script /etc/periodic/daily/600.daily.server runs daily. Its configuration file is /etc/diskspacemonitor/daily.server.conf.  The script /etc/periodic/weekly/600.weekly.server is intended to run weekly, but is currently empty. Its configuration file is /etc/diskspacemonitor/weekly.server.conf.  The script /etc/periodic/monthly/600.monthly.server is intended to run monthly, but is currently empty. Its configuration file is /etc/diskspacemonitor/monthly.server.conf. As configured, the scripts specify actions that complement the log file management performed by the services listed above, so don’t modify them. All you need to do is log in as an administrator and use a text editor to define thresholds in the configuration files that determine when the actions are taken. For example:  The number of megabytes a log file must contain before its space is reclaimed.  The number of days since a log file’s last modification that need to pass before its space is reclaimed. Specify one or both thresholds. The actions are taken when either threshold is exceeded. There are several additional parameters you can specify. See comments in the configuration files for information about all the parameters and how to set them. The scripts ignore all log files except those for which at least one threshold is present in the configuration file. To configure the scripts on a server from a remote Mac OS X computer, open a Terminal window and log in to the remote server using SSH. Then, open a text editor and edit the scripts. You can also use the diskspacemonitor tool to reclaim disk space. Erasing, Modifying, Verifying, and Repairing Disks You can use diskutil to erase, modify, verify, and repair disks. This command provides functionality that overlaps with the functionality of pdisk, newfs_hfs, and disktool. For example, you can use both diskutil and pdisk to partition a disk. However, unlike pdisk, which lets you partition tables at their most basic level by setting the exact base address and partition length in blocks, diskutil lets you partition a disk automatically by calculating the base address and the partition length in blocks based on the partition size you specify. The diskutil tool allows you to perform the following actions on a disk: Chapter 7 Working with Disks and Volumes 87 To list the disks currently known and available on the computer: $ diskutil list If your system is an Xserve computer, you can use this command to determine which drive is in which bay. To get mount info about a partition: $ diskutil info diskvol Parameter Description diskvol Device name (for example, disk0s9) for the partition. This command tells you the device file that corresponds to the mounted partition (or device name) you specify. To mount a drive: $ diskutil mountDisk diskvol Parameter Description diskvol Device name. To erase and repartition a disk: $ diskutil partitionDisk disk numberOfPartitions part1Format part1Name part1Size Parameter Description disk Device name (such as disk0). numberOfPartitions part1Format HFS+ or UFS. part1Name part1Size Can be either bytes (such as 98187445B), kilobytes (such as 810240K), megabytes (such as 4024M), gigabytes (such as 4G), or terabytes (such as 1T). Because HFS+ is case preserving but not case sensitive, there may be times when you would want to set the file system to be case sensitive. You can use the diskutil tool to format a drive for case-sensitive HFS+. Note: Volumes you format as case-sensitive HFS+ are also journaled. 88 Chapter 7 Working with Disks and Volumes To format a Mac OS Extended volume as case-sensitive HFS+: $ sudo diskutil eraseVolume "Case-sensitive HFS+" newvolname volume Parameter Description newvolname The name given to the reformatted, case-sensitive volume. volume The path to the existing volume to be reformatted. For example: /Volumes/HFSPlus See the diskutil man page for more options and information about repairing and modifying disks. Partitioning and Formatting Disks Disk partitions are subsdivisions of a disk to which you apply operating-system–specific formatting. Partitioning a Disk You can use pdisk, located in /usr/sbin, to edit the disk partition table. You can initialize the disk, create partitions, and delete partitions. The pdisk tool is menu-driven, which means that once it is launched, you are prompted to enter a pdisk command. You can find the commands by typing ? at the pdisk prompt. The following are some of the more useful commands: Command Description L Lists the partition maps of all the drives. pdisk lists all the partitions for a disk—even the unmountable partitions, such as the partition containing the partition map. e Edits the partition map of the named device. To edit a partition map, you have to use the raw device file as the argument. Once you start editing a device, the pdisk options change. Enter ? at the pdisk prompt to see the editing commands. The following are some of the more important ones: Command Description p Prints the partition map for the current device. i Initializes the partition map for the current device. C Creates a new partition. There are two partition types, Apple_HFS and Apple_UFS. w Writes the modifications to the partition map on-disk. Before that, all edits and modifications are only in memory and not yet implemented. pdisk does not support the Intel/DOS partitioning scheme supported by fdisk. See the fdisk man page for more information about DOS partitions. Chapter 7 Working with Disks and Volumes 89 After a partition has been created on a device, the partition needs to be formatted before the computer will be able to store data on the device. Formatting a disk partition creates the volume and sets the file system. Labeling a Disk Once a disk is formatted, it needs to be labeled. The disklabel tool manipulates “Apple Label” partition metadata. ”Apple Label” partitions allow for a disk device to have a consistent name, ownership, and permissions across reboots, even though it uses a dynamic pseudo file system for /dev. The “Apple Label” partition uses a set of metadata (as a plist) in a reserved area of the partition. This metadata describes the owner, name, and so forth. To create a disk label for a device with 1 MB of metadata area, owned by anne, with a device name of fred, and be writable by anne: $ disklabel -create /dev/rdisk1s1 -msize=1M owner-uid=anne dev-devname=anne name=anne owner-mode=0644 The following example prints out the key-value pairs from the previous example: $ disklabel -properties /dev/rdisk1s1 See the disklabel man page for more information about creating disk labels. Formatting a Disk You can use newfs, located in /sbin, to create a new volume. newfs builds a file system on the specified special device, basing its defaults on the information in the disk label. There are many parameters you can set when formatting disks, such as block and clump size, b-tree attribute, and catalog node sizes. Extreme care should be taken to ensure a successful format when modifying the settings beyond the default. Before running newfs, the disk must be labeled using the disklabel tool. To fomat a disk: $ newfs See the newfs man page for options in detail. To format a disk to HFS+, you would need to use the newfs_hfs tool located in /sbin: $ newfs_hfs See the newfs_hfs man page for more information. Checking for Disk Problems You can use the diskutil or fsck tool (fsck_hfs for HFS volumes) to check the physical condition and file system integrity of a volume. See the related man pages for more information. 90 Chapter 7 Working with Disks and Volumes Managing Disk Journaling A robust file system journaling feature is available to enhance the availability and fault tolerance of servers and server-attached storage devices. Journaling protects the integrity of the Mac OS Extended (HFS+) file system in the event of an unplanned shutdown or power failure, and maximizes uptime by expediting repairs to the affected volumes when the computer restarts. Checking to See If Journaling is Enabled You can use the mount tool to see if journaling is enabled on a volume. To see if journaling is enabled: $ mount Look for journaled in the attributes in parentheses following a volume. For example: /dev/disk0s9 on / (local, journaled) Enabling Journaling for an Existing Volume You can use the diskutil tool to enable journaling on a volume without affecting existing files on the volume. Important: Always check the volume for disk errors using the fsck_hfs tool before you enable journaling. To enable journaling: $ diskutil enableJournal volume Parameter Description volume The volume name or device name of the volume. The following example shows journaling being enabled on the exisiting volume /dev/ disk0s10. $ mount /dev/disk0s9 on / (local, journaled) /dev/disk0s10 on /Volumes/OS 9.2.2 (local) $ sudo fsck_hfs /dev/disk0s10/ ** /dev/rdisk0s10 ** Checking HFS plus volume. ** Checking extents overflow file. ** Checking Catalog file. ** Checking Catalog hierarchy. ** Checking volume bitmap. ** Checking volume information. ** The volume OS 9.2.2 appears to be OK. $ diskutil enableJournal /dev/disk0s10 Allocated 8192K for journal file. Journaling has been enabled on /dev/disk0s10 $ mount Chapter 7 Working with Disks and Volumes 91 /dev/disk0s9 on / (local, journaled) /dev/disk0s10 on /Volumes/OS 9.2.2 (local, journaled) Enabling Journaling When You Erase a Disk You can use the newfs_hfs tool to set up and enable journaling when you erase a disk. To enable journaling when erasing a disk: $ newfs_hfs -J -v volname device Parameter Description volname The name you want the new disk volume to have. device The device name of the disk. Disabling Journaling To disable journaling: $ diskutil disableJournal volume Parameter Description volume The volume name or device name of the volume. Understanding Spotlight Technology Spotlight is a desktop search technology that combines metadata-indexing with content-indexing that’s optimized for Mac OS X. Whenever a file is added, moved, deleted, or modified, the file system notifies the Spotlight engine. The Spotlight engine then updates its index, known as the Spotlight store. The Spotlight engine then updates all of the applications using Spotlight, and changes are reflected dynamically to the user. The Spotlight store retains information that is extracted into two seperate indexes, one for metadata and the other for content. Each index is created on a per-volume basis, which means each disk or partition carries its own set of indexes for the information about that volume. Enabling and Disabling Spotlight By default, the value of the spotlight parameter in the /etc/hostconfig file is set to -YESwhich means Spotlight is enabled on your Mac OS X Server computer. To disable Spotlight on your server: 1 Open the /etc/hostconfig file for editing as root using your favorite editor. For example: $ sudo pico /etc/hostconfig 2 Change the value of the spotlight parameter to -NO-. You can also set the value of the spotlight parameter to -NO- as follows: $ sudo /System/Library/ServerSetup/serversetup -setAutoStartSpotlight 0 92 Chapter 7 Working with Disks and Volumes 3 Restart your server. To enable Spotlight on your server: 1 Open /etc/hostconfig for editing as root. 2 Change the value of the spotlight parameter to -YES-. You can also set the value of the SPOTLIGHT parameter to -YES- as follows: $ sudo /System/Library/ServerSetup/serversetup -setAutoStartSpotlight 1 3 Restart your server. Performing Spotlight Searches Mac OS X provides the ability to view the metadata of a file and perform Spotlight searches from the command line. To view a file’s Spotlight metadata, use the mdls tool. This tool, which is similar to the ls tool, lists all of the metadata attributes for a specific file. To view the metadata of a file: $ mdls filename The computer will respond with something similar to the following output: ------------kMDItemAttributeChangeDate kMDItemFSContentChangeDate kMDItemFSCreationDate kMDItemFSCreatorCode kMDItemFSFinderFlags kMDItemFSInvisible kMDItemFSIsExtensionHidden kMDItemFSLabel kMDItemFSName kMDItemFSNodeCount kMDItemFSOwnerGroupID kMDItemFSOwnerUserID kMDItemFSSize kMDItemFSTypeCode kMDItemID kMDItemLastUsedDate kMDItemUsedDates = = = = = = = = = = = = = = = = = 1970-01-01 00:43:07 -0600 2005-10-03 22:04:19 -0500 2005-10-03 22:04:19 -0500 0 16384 1 0 0 "filename" 0 0 0 4330232 0 634516 2005-10-03 21:04:19 -0500 (2005-10-03 21:04:19 -0500) To perform a Spotlight search, use the mdfind tool: $ mdfind “kMDItemAcquisitionModel ==’Canon Powershot S45’” /Users/anne/Documents/vacation1.jpg /Users/anne/Documents/vacation2.jpg /Users/anne/Documents/vacation3.jpg /Users/anne/Documents/vacation4.jpg Chapter 7 Working with Disks and Volumes 93 Controlling Spotlight Indexing By default, indexing of volumes in Mac OS X Server is disabled. However, you can use the mdutil tool to enable or disable indexing on any volume. To enable indexing on a volume: Run the mdutil tool as root and set the indexing status to on. $ sudo mdutil -i on volume To disable indexing on a volume: Run the mdutil tool as root and set the indexing status to off. $ sudo mdutil -i off volume See the mdutil man page for more information. Managing RAID Volumes In addition to standard drive management options, diskutil has the ability to manage software RAID volumes. To create a RAID set: $ diskutil createRAID type setName volType disks Parameter Description type Mirror or stripe. setName Name of the new RAID volume. volType HFS, HFS+, UFS, or BootableHFS. disks List of device names for members of the RAID set. To get a list of of disks available to add to a RAID set: $ diskutil list Similarly, you can remove a RAID set with the diskutil destroyRAID To view a list of available RAID sets: $ diskutil checkRAID device Parameter Description device Device file. To create an unpaired mirrored RAID from a single file system disk: $ diskutil enableRAID mirror device 94 Parameter Description mirror Name of the mirror RAID set. device Device file. Chapter 7 Working with Disks and Volumes command. To repair a failed mirror: $ diskutil repairMirror device slicenumber fromDisk toDisk Parameter Description device Device file. slicenumber Specifies the slice number to replace. fromDisk Specifies the mirror source. toDisk Specifies the repaired mirror destination. Note: Xsan RAID volumes have their own set of commands, which are described in an appendix of the Xsan administrators guide. See the appendix for informatian about the megaraid tool, used for managing a PCI RAID card. Imaging and Cloning Volumes Using ASR You can use Apple Software Restore (ASR) to copy a disk image onto a volume or to prepare existing disk images with checksum information for faster copies. ASR can perform file copies, in which individual files are restored to a volume unless an identical file is already there, and block copies, which restore entire disk images. The asr tool doesn’t create the disk images. You can use hdiutil to create disk images from volumes or folders. You must run ASR as root. You cannot use ASR on read or write disk images. To image a boot volume: 1 Install and configure Mac OS X on the volume. 2 Restart from a different volume. 3 Make sure the volume you’re imaging has permissions enabled. Use the following to verify permissions: $ diskutil verifyPermissions [mount point|disk identifier|device node] 4 Use hditutil to make a read-write disk image of the volume. See “To create an image from a folder:” on page 177. 5 Mount the disk image. 6 Remove cache files, host-specific preferences, and virtual memory files. See the asr man page for examples of what files to remove. 7 Unmount the volume and convert the read-write image to a read-only compressed image. $ hdiutil convert -format UDZO pathtoimage -o compressedimage 8 Prepare the image for duplication by adding checksum information: $ sudo asr -imagescan compressedimage Chapter 7 Working with Disks and Volumes 95 To restore a volume from an image: $ sudo asr -source compressedimage -target targetvolume -erase See the asr man page for command syntax, limitations, and image preparation instructions. 96 Chapter 7 Working with Disks and Volumes 8 Working with Users and Groups 8 In this chapter you will find commands you can use to set up and manage user and group accounts. With Mac OS X Server, you can quickly create and administer accounts for users and groups. There are several command-line tools that facilitate working with the directory domains that hold these accounts. Understanding Accounts There are three kinds of accounts you can set up with Workgroup Manager: user accounts, group accounts, and computer lists. When you define a user’s account, you specify the information needed to prove the user’s identity: user name, password, and user identification number (user ID). Other information in a user’s account is needed by various services—to determine what the user is authorized to do and perhaps to personalize the user’s environment. Along with accounts you create, Mac OS X Server has some predefined user and group accounts, some of which are reserved for use by Mac OS X. Most users have an individual account used to authenticate them and control their access to services. When you want to personalize a user’s environment, you define user, group, or computer preferences for that user. The term managed client or managed user designates a user who has administrator-controlled preferences associated with his or her account. When a managed user logs in, the preferences that take effect are a combination of the user’s preferences and preferences set up for any workgroup or computer list he or she belongs to. 97 Administering and Creating Accounts A user account stores data that Mac OS X Server needs to validate the user’s identity and provide services for the user. This section provides an overview of user accounts. User accounts, as well as group accounts and computer lists, can be stored in any Open Directory domain accessible from any Mac OS X computer. A directory domain can reside on a Mac OS X computer (for example, the LDAP folder of an Open Directory master, a NetInfo domain, or other read/write directory domain) or it can reside on a non-Apple server (for example, a non-Apple LDAP or Active Directory server). This section describes how to administer user accounts stored in various kinds of directory domains. Creating a Local Administrator User Account for a Server Users with server or directory domain administration privileges are known as administrators. An administrator can be a server administrator, domain administrator, or both. Server administrator privileges determine whether a user can view info about or change the settings of a particular server. Domain administrator privileges determine the extent to which the user can view or change the account settings for users, groups, and computer lists in the directory domain. You can use the serversetup tool to create local administrator users for a server. The serversetup tool is located in /System/Library/ServerSetup/ and it is not in the local path, so you have to provide the path to it. You also have to run it as root. To create nonadministrator users, see “Creating a Nonadministrator User Account” on page 100. To create administrator users in a network directory domain, see “Creating a Domain Administrator User Account” on page 99. To create a local administrator user account: $ sudo /System/Library/ServerSetup/serversetup -createUser fullname shortname password The name, short name, and password must be entered in the order shown. If the full name includes spaces, enter it in quotes. The command displays a 0 if successful, or a 1 if the full name or short name is already in use. To create an local administrator user with a specific UID: $ sudo /System/Library/ServerSetup/serversetup -createUserWithID fullname shortname password uid The name, short name, password, and UID must be entered in the order shown. If the full name includes spaces, enter it in quotes. The command displays a 0 if successful, or a 1 if the full name, short name, or UID is already in use or if the UID you specified is less than 100. 98 Chapter 8 Working with Users and Groups To create an local administrator user with a specific UID and home folder: $ sudo /System/Library/ServerSetup/serversetup -createUserWithIDIP fullname shortname password uid homedirpath The name, short name, password, and UID must be entered in the order shown. If the full name includes spaces, enter it in quotes. The command displays a 0 if successful, or a 1 if the full name, short name, or UID is already in use or if the UID you specified is less than 100. Creating a Domain Administrator User Account In order to create a domain administrator user account for a networked directory, you need to already have a domain administrator user account. Before starting, you should already have a nonadministrator user account that you want to give domain administrator privileges to. For instructions on creating nonadministrator user accounts, see “Creating a Nonadministrator User Account” on page 100. To create a domain administrator user account: 1 Start the dscl tool in interactive mode, specifying the computer you are using as the source of directory service data. Use the dscl tool to create a domain administrator user account. $ dscl localhost > In interactive mode, the dscl tool displays the current folder in the directory domain (not the current folder in the file system) and a “>” character as a prompt. 2 Once connected to the directory, choose the directory domain. Change the current folder to LDAPv3/ipaddress/Groups. > cd LDAPv3/ipaddress/Groups Replace ipaddress with the IP address of your directory server. If using a NetInfo directory domain, enter cd /NetInfo/root/Groups at the prompt. 3 Create an administrator user. >append admin Member adminusername This command creates an administrator user, but it doesn’t add the GUID (globally unique identifier) of the administrator user to the group account. 4 Add the administrator user to the group. > append admin GroupMembers guid Replace guid with the globally unique identifier. 5 Quit the dscl tool. >quit Chapter 8 Working with Users and Groups 99 To find the GUID of the administrator user: > cd /Users/ > read adminusername GeneratedUID Checking a User’s Administrator Privileges Use the serversetup tool to verify the administrator privileges of a specific user. To see if a user is a server administrator: $ sudo /System/Library/ServerSetup/serversetup -isAdministrator shortname The command displays a 0 if the user is an administrator, or a 1 if the user is not an administrator. Creating a Nonadministrator User Account You can create new user accounts by using dscl and other tools. When you create a user account from the command line, you must also set values for basic attributes of the user account, such as the short name, long name, user ID, and home folder location. To create a nonadministrator user account: 1 Identify an unused user ID. Each user on a server must have a unique user ID. Use the dscl tool to display lists of assigned user IDs and group IDs. $ dscl /LDAPv3/ipaddress -list /Users UniqueID| awk '{print $2}' | sort -n Replace /LDAPv3/ipaddress with the location of your directory domain (the way it is displayed in the search path in Directory Access). If you connect to a NetInfo domain, replace UniqueID with uid. After you enter the command, the dscl tool displays a list of assigned user ID numbers, similar to the following output. These user IDs are for computer accounts that are included with Mac OS X Server: -2 0 1 99 25 26 27 70 71 75 76 77 78 79 501 100 Chapter 8 Working with Users and Groups Important: Pick a user ID that isn’t on either list and that is greater than 501. 501 is the user ID of the local administrator user that gets created when you install Mac OS X Server. 2 Start the dscl tool in interactive mode, specifying the computer you are using as the source of directory service data. Use the dscl tool to create a nonadministrator user account. $ dscl localhost > In interactive mode, the dscl tool displays the current folder in the directory domain (not the current folder in the file system) and a “>” character as a prompt. 3 Change the current folder to /LDAPv3/ipaddress/Users by entering the path at the prompt: > cd /LDAPv3/ipaddress/Users Replace ipaddress with the IP address of your directory server. If using a NetInfo directory domain, enter cd /NetInfo/root/Users at the prompt. 4 Authenticate as an administrator by entering the following command, replacing adminusername with your administrator user name, and entering your administrator password when prompted: > auth adminusername 5 Create a new user account, replacing ajohnson with the new user account’s short name and specifying the path to the new user’s home folder in /Users/: > create ajohnson HomeDirectory “ ” > create ajohnson NFSHomeDirectory /Network/Servers/sp.apple.com/Users/ ajohnson Replace sp.apple.com with your home folder server’s location. 6 Specify the new user’s default UNIX shell: > create ajohnson UserShell /bin/bash 7 Specify the user ID, replacing 1234 with the new user’s ID: > create ajohnson UniqueID 1234 8 Specify the long name for the new user account, replacing Anne Johnson with the actual long name: > create ajohnson RealName "Anne Johnson" 9 Review the settings of your new user account by entering the following command, replacing ajohnson with the new user account’s short name as before: > read ajohnson Chapter 8 Working with Users and Groups 101 dscl displays the settings for your new user account, similar to the following output: apple-generateduid:1B2A3456-E7C8-9EC1-2345-678D912E3456 cn: anne johnson gidNumber: 99 HomeDirectory: /LDAPv3/ipaddress/Users/ajohnson loginShell: /bin/bash objectClass: inetOrgPerson posixAccount shadowAccount apple-user extensible object organizationalPerson top person sn: ajohnson uid: ajohnson uidNumber: 1234 AppleMetaNodeLocation: /LDAPv3/ipaddress GeneratedUID:1B2A3456-E7C8-9EC1-2345-678D912E3456 LastName: johnson NFSHomeDirectory: /LDAPv3/ipaddress/Users/ajohnson PasswordPlus:******** PrimaryGroupID: 99 RealName: Anne Johnson RecordName: ajohnson anne RecordType: dsRecTypeStandard:Users UniqueID: 1234 UserShell: /bin/bash 10 Assign a password to the account by entering the following command, replacing ajohnson with the new account’s short name: > passwd ajohnson You will be prompted to enter a password. 11 Quit dscl by entering: > quit The dscl tool displays Goodbye, and then the standard shell prompt appears. 12 Use the ssh tool to connect to the server where you are hosting all of the home folders: $ ssh -l username server where username is the name of an administrator user on the remote server and server is the name or IP address of the server. 13 Create the home folder for the new user. Use the -s option if you are using a network directory domain or the -c option if you are using a local directory domain. $ sudo createhomedir -s -u ajohnson To create a group account for the new user, see “Creating a Group Account” on page 111 before doing this step. The new user account is now complete and can be used for login. See the dscl man page for more information. 102 Chapter 8 Working with Users and Groups Retreiving a User’s GUID When a user account is created, the computer generates a 128-bit integer called a globally unique identifier (GUID). This is stored in the LDAP directory. The GUID is used for permissions and for associating users with group memberships. In command-line tools, you might see a GUID referred to as a GeneratedUID. To retrieve a user’s GUID: 1 Start the dscl tool in interactive mode, specifying the computer you are using as the source of directory service data: $ dscl localhost > 2 Change the current folder to /LDAPv3/ipaddress/Users by entering the path at the prompt: > cd /LDAPv3/ipaddress/Users Replace ipaddress with the IP address of your directory server. If using a NetInfo directory domain, enter cd /NetInfo/root/Users at the prompt. 3 Authenticate as an administrator by entering the following command, replacing adminusername with an administrator’s user name, and entering an administrator’s password when prompted: > auth adminusername 4 Review the GUID for a particular user. > read username GeneratedUID 5 Quit dscl by entering: > quit Removing a User Account You can remove a user account by using the dscl tool. This does not remove the user’s home folder and the data that may be stored there. You can use the Finder to drag the deleted user’s home folder to the Trash. To delete a user account: 1 Start the dscl tool in interactive mode, specifying the computer you are using as the source of directory service data: $ dscl localhost > 2 Change the current folder to /LDAPv3/ipaddress/Users by entering the path at the prompt: > cd /LDAPv3/ipaddress/Users Replace ipaddress with the IP address of your directory server. If using a NetInfo directory domain, enter cd /NetInfo/ipaddress/Users at the prompt. Chapter 8 Working with Users and Groups 103 3 Authenticate as an administrator by entering the following command, replacing adminusername with an administrator’s user name, and entering that administrator’s password when prompted: > auth adminusername 4 Delete the user account by entering the following command, replacing ajohnson with the user account’s short name: > delete ajohnson 5 Quit dscl by entering: > quit A user account usually has a matching group of the same name. See “Removing a Group Account” on page 112, for information about deleting this group. Revoking a User’s Right to Access His or Her Account There are times when it is necessary to revoke a user’s ability to access the computer. This involves preventing the user from logging in and then terminating all of the user’s processes. This can be done by forcing the user to log out and then killing any remaining processes, or by just killing all of the user’s processes. To prevent a user from logging in: 1 Start the dscl tool in interactive mode, specifying the computer you are using as the source of directory service data: $ dscl localhost > 2 Change the current folder to /LDAPv3/ipaddress/Users by entering the path at the prompt: > cd /LDAPv3/ipaddress/Users Replace ipaddress with the IP address of your directory server. If using a NetInfo directory domain, enter cd /NetInfo/root/Users at the prompt. 3 Authenticate as an administrator by entering the following command, replacing adminusername with your administrator user name, and entering your administrator password when prompted: > auth adminusername 4 Quit dscl by entering: > quit 5 Disable the user account by entering the following command: $ pwpolicy -a diradmin -u ajohnson -setpolicy “isDisabled=1” Replace ajohnson with the short name of the user account and replace diradmin with the short name of your domain administrator account. 104 Chapter 8 Working with Users and Groups To terminate all of a user’s processes: After disabling the user account, you need to kill all of the user’s active processes that are currently running on the directory server. Warning: Unconditionally killing all of a user’s processes will cause the user to lose any unsaved data. 1 Make all processes clean up and exit by entering the following command, replacing ajohnson with the user name: $ sudo killall -TERM -u ajohnson 2 Wait a few seconds to allow the previous command to execute. To terminate all user processes unconditionally, enter the following command, replacing ajohnson with the user name: $ sudo killall -9 -u ajohnson Refer to the killall man page for more information about terminating processes. To reenable a user account that is disabled: 1 Start the dscl tool in interactive mode, specifying the computer you are using as the source of directory service data: $ dscl localhost > 2 Change the current folder to /LDAPv3/ipaddress/Users by entering the path at the prompt: > cd /LDAPv3/ipaddress/Users Replace ipaddress with the IP address of your directory server. If using a NetInfo directory domain, enter cd /NetInfo/root/Users at the prompt. 3 Authenticate as an administrator by entering the following command, replacing adminusername with your administrator user name, and entering your administrator password when prompted: > auth adminusername 4 Quit dscl by entering: > quit 5 Enable the user account by entering the following command. Replace ajohnson with the short name of the user account and replace diradmin with the short name of your domain administrator account. $ pwpolicy -a diradmin -u ajohnson -setpolicy “isDisabled=0” Chapter 8 Working with Users and Groups 105 Checking a Server User’s Name, UID, or Password You can use the following commands to check the name, UID, or password of a user in the server’s local directory domain. Note: These tasks apply only to the local directory domain on the server. To see if a full name is already in use: $ sudo /System/Library/ServerSetup/serversetup -verifyRealName "longname" The command displays a 1 if the name is already in use, or a 0 if it isn’t. To see if a short name is already in use: $ sudo /System/Library/ServerSetup/serversetup -verifyName shortname The command displays a 1 if the name is already in use, or a 0 if it isn’t. To see if a UID is already in use: $ sudo /System/Library/ServerSetup/serversetup -verifyUID uid The command displays a 1 if the UID is already in use, or a 0 if it isn’t. To test a user’s password: $ sudo /System/Library/ServerSetup/serversetup -verifyNamePassword shortname password The command displays a 1 if the password is good, or a 0 if it isn’t. To view the names associated with a UID: $ sudo /System/Library/ServerSetup/serversetup -getNamesByID uid If you don’t receive a response, the UID is not valid. To get the default UNIX short name for a user long name: $ sudo /System/Library/ServerSetup/serversetup -getUNIXName "longname" Note: Mac OS X Server provides the net tool, which is essentially a clone of the Windows net command. The net tool enables administrators to perform advanced customization of the PDC and mapping domain privileges to UNIX groups. See the man page for more information. 106 Chapter 8 Working with Users and Groups net Modifying a User Account You can change the value of an attribute in a user account by using dscl. There are many attributes that can be set for users. The following table describes some of the user account attributes you can modify using dscl: Attribute Description apple-generateduid User id generated by the system. cn User’s common name. homeDirectory Location of the user’s Home Folder. loginShell User’sTerminal shell. sn User’s sir name. LastName User’s last name. NFSHomeDirectory Location of the user’s Home Folder. PasswordPlus User’s password. PrimaryGroupID User’s primary group ID. RealName User’s name. UserShell User’sTerminal shell. To change a user account attribute to a new value: 1 Start the dscl tool in interactive mode, specifying the computer you are using as the source of directory service data: $ dscl localhost > 2 Change the current folder to /LDAPv3/ipaddress/Users by entering the path at the prompt: > cd /LDAPv3/ipaddress/Users Replace ipaddress with the IP address of your directory server. If using a NetInfo directory domain, enter cd /NetInfo/root/Users at the prompt. 3 Authenticate as an administrator by entering the following command, replacing adminusername with your administrator user name, and entering your administrator password when prompted: > auth adminusername 4 Set the user attribute to the desired value by entering the following command, replacing ajohnson with the user account’s short name, attribute with the name of the attribute whose value you wish to change, and newvalue with the value: > create ajohnson attribute newvalue 5 Quit dscl by entering: > quit Chapter 8 Working with Users and Groups 107 Creating a Mobile User Account Mobile accounts are network accounts that have been set up to be accessible even when the user is not connected to the server where the account resides. The mobile account user is provided with a local home folder on the computer the user is logged in to. This functionality reduces network traffic and improves overall performance. You can use the MCXCacher tool to create a mobile account from the command line. MCXCacher performs the pre-login checks and refreshes cache if required. This tool will only work if the client is bound to a network directory system containing the target user record. Important: Creating a mobile user account is a client-only operation. These commands must be either performed on the client computer or while connected through SSH to a client computer. To create a mobile account: 1 Use the MCXCacher to create a mobile account on the current computer. $ sudo /System/Library/CoreServices/mcxd.app/Contents/Resources/ MCXCacher -U ajohnson Where ajohnson is the short name of a user in the parent folder and /Users/ajohnson is the Home Folder. 2 Run the passwd command to change passwords. $ passwd ajohnson Then enter verify passwords. You can also set the password by logging in while connected to the network. 3 Create a standard home folder for a user with a mobile account. $ sudo createhomedir -u ajohnson -c -l When a mobile account is enabled, it appears in the login window and in the Accounts pane of System Preferences with the label Mobile. You can alsol select the user in Workgroup Manager and click Preferences > Mobility. If “synchronize account for offline use” is checked, the account is mobile. The MCXCacher tool does not have a man page. This tool, located in the /System/ Library/CoreServices/mcxd.app/Contents/Resources/ folder, performs the pre-login checks and refreshes cache if necessary. The following examples describe other options for MCXCacher tool. To create (or overwrites an existing) mobile account on the current machine: Enter the following, replacing usershortname with the user’s short name and homepath with the location of the user’s Home Folder. $ sudo /System/Library/CoreServices/mcxd.app/Contents/Resources/ MCXCacher -U usershortname [-h homepath] 108 Chapter 8 Working with Users and Groups To perform the post–login checks and refreshes caches and caches the current user’s mcx_settings: Enter the following, replacing usershortname with the user’s short name. $ sudo /System/Library/CoreServices/mcxd.app/Contents/Resources/ MCXCacher -U usershortname To flush the cache: $ sudo /System/Library/CoreServices/mcxd.app/Contents/Resources/ MCXCacher -f To dirty the cache so that it will be refreshed at the next login: $ sudo /System/Library/CoreServices/mcxd.app/Contents/Resources/ MCXCacher -d Managing Home Folders A home folder is a folder where a user’s files and preferences are stored. Other users can see a user’s home folder and read files in its Public folder, but they can’t (by default) access anything else in that folder. This is true only for other users whose home folders reside on the same server or share point. When you create a user account in a directory domain on the network, you specify the location of the user’s home folder on the network. The location is stored in the user account and used by various services, including the login window and Mac OS X managed client services. Creating a User’s Home Folder Normally, you can create a user’s home folder by clicking the Create Home Now button on the Homes pane of Workgroup Manager. You can also create home folders using the createhomedir tool. Otherwise, Mac OS X Server creates the user’s home folder when the user logs in for the first time. You can use createhomedir to create:  A home folder for a particular user (-u option)  Home folders for all users in a directory domain (-l or -n option)  Home folders for all users in all domains in the folder search path (-a option) See the createhomedir man page for more information. In all cases, the home folders are created on the server where you run the tool. To create a home folder for a particular user: $ sudo createhomedir -u uid In addition to the uid, you can also use the user’s short name. Chapter 8 Working with Users and Groups 109 To create a home folder for users in the local domain: $ sudo createhomedir [(-a|-l|-n domain)] -u uid You can also create a user’s home folder using the serversetup tool. To create a home folder for a particular user: $ sudo /System/Library/ServerSetup/serversetup -createHomedir uid The command displays a 1 if the user ID you specify doesn’t exist. Mounting a User’s Home Folder You can use mnthome to mount a user’s home folder. The mnthome tool unmounts the AFP (AppleShare) home folder that was automounted as guest, and remounts it with the correct privileges by logging into the AFP server using the current user name and password. To mount a user’s shared home directory on an AFP server: $ mnthome -p password See the mnthome man page for more information. Administering Group Accounts A group is simply a collection of users who have similar needs. For example, you can add all users with a particular task to one group and give the group permission to access certain files or folders on a volume. Groups simplify the administration of shared resources. Instead of granting access to various resources to each individual who needs them, you can add the users to a group and then grant access to the group. Information in group accounts is used to help control user access to folders and files. Individual users may belong to multiple groups, depending on their access needs. A group can be nested within another group. A group that contains another group is called a parent group, and the group that is contained is called a nested group. Nested groups are useful for inheriting access permissions at login time. 110 Chapter 8 Working with Users and Groups Creating a Group Account You can create a new group account by using dscl and other tools. When you create a group account via the command line, you must also set values for basic attributes of a group account, such as short name and group ID. To add a group account: 1 Identify an unused group ID by entering the following command to display a list of assigned group IDs. $ dscl /LDAPv3/ipaddress -list /Groups PrimaryGroupID | awk '{print $2}' | sort -n Replace ipaddress with the location of your directory domain (the way it is displayed in the search path in Directory Access). If you connect to a NetInfo domain, use: $ dscl /NetInfo/root -list /Groups gid | awk ‘{print $2}’ | sort -n. After you enter the command, the dscl tool displays a list of assigned IDs similar to the following output: -2 0 1 99 25 26 27 70 71 76 77 78 79 501 Important: Pick an ID that isn’t on either list, and that is greater than 501. 2 Start the dscl tool in interactive mode, specifying the computer you are using as the source of directory service data: $ dscl localhost > 3 Change the current folder to /LDAPv3/ipaddress/Groups by entering the path at the prompt: > cd /LDAPv3/ipaddress/Groups Replace ipaddress with the IP address of your directory server. If using a NetInfo directory domain, enter cd /NetInfo/root/Groups at the prompt. Chapter 8 Working with Users and Groups 111 4 Authenticate as an administrator by entering the following command, replacing adminusername with your administrator user name, and entering your administrator password when prompted: > auth adminusername 5 Create a new group, replacing officegroup with the new group account’s short name and specify the group ID, replacing 600 with the primary group ID. > create officegroup PrimaryGroupID 600 6 Review the settings of your new group by entering the following command, replacing officegroup with the new group account’s short name. > read officegroup dscl displays the settings for your new group account, similar to the following output: apple-generateduid:4B3A5678-E9C1-2EC3-4567-891D234E5678 cn: officegroup gidNumber: 600 objectClass: posixGroup apple-group extensibleObject top AppleMetaNodeLocation: /LDAPv3/ipaddress GeneratedUID:4B3A5678-E9C1-2EC3-4567-891D234E5678 PasswordPlus:******** PrimaryGroupID: 600 RecordName: officegroup RecordType: dsRecTypeStandard:Groups 7 Quit the dscl tool. >quit See the dscl man page for more information about using the dscl command-line tool. Removing a Group Account You can remove group accounts by using the dscl tool. To remove a group account: 1 Start the dscl tool in interactive mode, specifying the computer you are using as the source of directory service data: $ dscl localhost > 2 Change the current folder to /LDAPv3/ipaddress/Groups by entering the path at the prompt: > cd /LDAPv3/ipaddress/Groups Replace ipaddress with the IP address of your directory server. If using a NetInfo directory domain, enter cd /NetInfo/root/Groups at the prompt. 112 Chapter 8 Working with Users and Groups 3 Authenticate as an administrator by entering the following command, replacing adminusername with your administrator user name, and entering your administrator password when prompted: > auth adminusername 4 Remove the group by entering the following command, replacing officegroup with the group account’s short name: > delete officegroup 5 Quit dscl by entering: > quit Adding a User to a Group You can add users to a group using the dscl tool. To add a user to a group: 1 Start the dscl tool in interactive mode, specifying the computer you are using as the source of directory service data: $ dscl localhost > 2 Change the current folder to /LDAPv3/ipaddress/Groups by entering the path at the prompt: > cd /LDAPv3/ipaddress/Groups Replace ipaddress with the IP address of your directory server. If using a NetInfo directory domain, enter cd /NetInfo/root/Users at the prompt. 3 Authenticate as an administrator by entering the following command, replacing adminusername with your administrator user name, and entering your administrator password when prompted: > auth adminusername 4 Add the user to the group by entering the following command, replacing ajohnson with the short name of the user account and officegroup with the short name of the group account: > append admin Member adminusername This creates an administrator user, but it does not add the GUID (globally unique identifier) of the administrator user to the group account. This may cause security and compatibility issues. 5 Add the administrator user to the admin group. > append admin GroupMembers guid Chapter 8 Working with Users and Groups 113 6 Review the new settings of the group by entering the following command, replacing officegroup with the group account’s short name: > read officegroup dscl displays the settings for the group account, similar to the following output: apple-generateduid:4B3A5678-E9C1-2EC3-4567-891D234E5678 cn: officegroup gidNumber: 600 MemberUid: mchen ajohnson bmiller objectClass: posixGroup apple-group extensibleObject top AppleMetaNodeLocation: /LDAPv3/ipaddress GeneratedUID:4B3A5678-E9C1-2EC3-4567-891D234E5678 GroupMembers:2B3A4567-E8C9-9EC2-3456-789D123E4567 1B2A3456-E7C8-9EC1-2345678D912E3456 8B9A1234-E5C6-7EC8-9123-456D78E9123 GroupMembership: mchen ajohnson bmiller Member: mchen ajohnson bmiller PasswordPlus:******** PrimaryGroupID: 600 RecordName: officegroup RecordType: dsRecTypeStandard:Groups 7 Quit dscl by entering: > quit To find the guid of the administrator user: > cd /Users/ > read adminusername GeneratedUID Removing a User from a Group You can remove users from a group by using the dscl tool. To remove a user from a group: 1 Start the dscl tool in interactive mode, specifying the computer you are using as the source of directory service data: $ dscl localhost > 2 Change the current folder to /LDAPv3/ipaddress/Groups by entering the path at the prompt: > cd /LDAPv3/ipaddress/Groups Replace ipaddress with the IP address of your directory server. If using a NetInfo directory domain, enter cd /NetInfo/root/Groups at the prompt. 3 Authenticate as an administrator by entering the following command, replacing adminusername with your administrator user name, and entering your administrator password when prompted: > auth adminusername 114 Chapter 8 Working with Users and Groups 4 View the current members of the group by entering the following (replacing officegroup with the group account’s short name): > read officegroup displays the settings for the group account, similar to the following output where the group named officegroup has users mchen, ajohnson, and bmiller as members: dscl apple-generateduid:4B3A5678-E9C1-2EC3-4567-891D234E5678 cn: officegroup gidNumber: 600 MemberUid: mchen ajohnson bmiller objectClass: posixGroup apple-group extensibleObject top AppleMetaNodeLocation: /LDAPv3/ipaddress GeneratedUID:4B3A5678-E9C1-2EC3-4567-891D234E5678 GroupMembers:2B3A4567-E8C9-9EC2-3456-789D123E4567 1B2A3456-E7C8-9EC1-2345678D912E3456 8B9A1234-E5C6-7EC8-9123-456D78E9123 GroupMembership: mchen ajohnson bmiller Member: mchen ajohnson bmiller PasswordPlus:******** PrimaryGroupID: 600 RecordName: officegroup RecordType: dsRecTypeStandard:Groups 5 Remove the user by entering the following command, replacing ajohnson with the short name of the user account, ajguid with ajohnson’s GUID, and officegroup with the short name of the group account: > delete officegroup GroupMembership ajohnson > delete officegroup GroupMembership ajguid 6 Review the new settings of the group: > read officegroup dscl displays the settings for the group, showing that the user you removed is no longer a group member, similar to the following output: apple-generateduid:4B3A5678-E9C1-2EC3-4567-891D234E5678 cn: officegroup gidNumber: 600 MemberUid: mchen bmiller objectClass: posixGroup apple-group extensibleObject top AppleMetaNodeLocation: /LDAPv3/ipaddress GeneratedUID:4B3A5678-E9C1-2EC3-4567-891D234E5678 GroupMembers:2B3A4567-E8C9-9EC2-3456-789D123E4567 8B9A1234-E5C6-7EC8-9123456D78E9123 GroupMembership: mchen bmiller Member: mchen bmiller PasswordPlus:******** PrimaryGroupID: 600 RecordName: officegroup RecordType: dsRecTypeStandard:Groups Chapter 8 Working with Users and Groups 115 7 Quit dscl by entering: > quit Creating and Deleting Nested Group Nested groups allow for one group (child) to be a member of a second group (parent), thus inheriting the permissions and attributes of the parent group. All members of a nested group will become child members of the parent group as well. You can create a nested group by using the dseditgroup tool with the -a option, which adds the group record to the parent group. To create a nested group: $ dseditgroup -o edit [-a childgroup] [-t group] [-u username] [-P password] [-n /LDAPv3/ipaddess] parentgroup Parameter Description childgroup The name of the child group you are adding to the parent group. username The short name of a user with LDAP directory service access. password The user password. ipaddress The IP address of your directory server. parentgroup The name of the parent group that the child group is being added to. To verify a nested group: 1 Start the dscl tool in interactive mode, specifying the computer you are using as the source of directory service data: $ dscl localhost > 2 Change the current folder to /LDAPv3/ipaddress/Groups by entering the path at the prompt: > cd /LDAPv3/ipaddress/Groups Replace ipaddress with the IP address of your directory server. If using a NetInfo directory domain, enter cd /NetInfo/root/Groups at the prompt. 3 Authenticate as an administrator by entering the following command, replacing adminusername with your administrator user name, and entering your administrator password when prompted: > auth adminusername 4 View the current members of the group by entering (replacing parentgroup with the group account’s short name): > read parentgroup 116 Chapter 8 Working with Users and Groups dscl displays the settings for the group account, similar to the following output where the group named parentgroup is shown as nested: apple-generateduid:4B3A5678-E9C1-2EC3-4567-891D234E5678 apple-group-nestedgroup:1A2B3456-C7D8-9EF1-2345-678G912H3456 cn: parentgroup gidNumber: 700 objectClass: posixGroup apple-group extensibleObject top AppleMetaNodeLocation: /LDAPv3/ipaddress GeneratedUID:4B3A5678-E9C1-2EC3-4567-891D234E5678 NestedGroups:1A2B3456-C7D8-9EF1-2345-678G912H3456 PasswordPlus:******** PrimaryGroupID: 700 RecordName: parentgroup RecordType: dsRecTypeStandard:Groups Once a nested group is established, it can be split apart or unnested by using the dseditgroup tool with the -d option which deletes the group record but leaves the group intact. To unnest a group: $ dseditgroup -o edit [-d childgroup] [-t group] [-u username] [-P password] [-n /LDAPv3/ipaddess] parentgroup Parameter Description childgroup The name of the child group you are adding to the parent group. group The type of account you are changing. In this case group. username The short name of a user with LDAP directory service access. password The user password. ipaddress The IP address of your directory server. parentgroup The name of the parent group that the child group is being added to. Editing Group Records You can use dsEditGroup to add, remove, or edit group records in the local directory service. To display the information about a particular group: $ dseditgroup officegroup To delete a group: $ dseditgroup -o delete -n /LDAPv3/ipaddress -u diradmin groupname Replace ipaddress with the IP address of the DNS name of the LDAPv3 server, diradmin with the name of the directory administrator, and groupname with the name of the group you want to delete. Chapter 8 Working with Users and Groups 117 This will prompt you for your diradmin password, which is much more secure than putting the password in the command you are sending. See the dseditgroup man page for more information. Creating a Group Folder A group folder facilitates the sharing of files between members of a group. Once you set up a group folder in Workgroup Manager you need to use the CreateGroupFolder tool to create the actual group folder. Group folders should be created on the server that hosts the group folders. To create a group folder: $ sudo /usr/bin/CreateGroupFolder See the CreateGroupFolder man page for more information. Viewing the Workgroup a User Selects at Login When you define preferences for a group, it is known as a workgroup. A workgroup provides you with a way to manage the working environment of group members. Any preferences you define for a Mac OS X workgroup are stored in the group account. When a user selects a workgroup at login, a property list (plist) file stores the short name of the selected workgroup in its “workgroup” key. Important: Viewing the workgroup a user selects at login must be performed on the client computer. To view the workgroup a user selects at login, from the client computer: 1 Connect to the client computer using an account with administrator privileges. $ ssh admin@computer.name Replace admin with the short name of the client computer’s administrator and computer.name with the IP address or the DNS name of the client computer. 2 Convert the binary com.apple.MCX.plist file to XML format. $ sudo plutil -convert xml1 /Library/Managed Preferences/shortname/ com.apple.MCX.plist Replace shortname with the short name of the logged-in client account. 3 View the key “workgroup” in /Library/Managed Preferences/shortname/ com.apple.MCX.plist file. $ cat /Library/Managed Preferences/shortname/com.apple.MCX.plist Replace shortname with the short name of the logged-in client account. 118 Chapter 8 Working with Users and Groups Importing Users and Groups You can use dsimport to import user and group accounts. into a folder. The dsimport tool permits logging at three levels with the -l switch. You can use the dsimport tool to import any number of records from a flexible text–delimited file. See the dsimport man page for more information. See the Open Directory administration guide for a list of record types and attributes. This guide also describes how to edit permitted attributes for each record type for use in an LDAP folder. The dsimport tool is located in /usr/bin/. See “Creating a Character-Delimited User Import File” on page 120 for information about the formats of the files you can import. $ dsimport (-g|-s|-p) file path (O|M|I|A) -u user -p password [options] Parameter Description -g|-s|-p You must specify one of these to indicate the type of file you’re importing: -g for a character-delimited file -s for an XML file exported from Users & Groups in Mac OS X Server version 10.1.x -p for an XML file exported from AppleShare IP version 6.x file The path of the file to import. path The path to the Open Directory directory domain where the records will be added. O|M|I|A Specifies how user data is handled if a record for an imported user already exists in the folder: O: Overwrite the matching record. M: Merge the records. Empty attributes in the folder and assume values from the imported record. I: Ignore imported record and leave existing record unchanged. A: Append data from import record to existing record. user The name of the folder administrator. password The password of the folder administrator. options Additional command options. To see available options, execute the dsimport command with no parameters. To import users and groups: 1 Create a file containing the accounts to import, and place it in a location accessible from the importing server. You can export this file from an earlier version of Mac OS X Server or AppleShare IP 6.3, or create your own character-delimited file. See “Creating a Character-Delimited User Import File” on page 120. Chapter 8 Working with Users and Groups 119 Open Directory supports up to 200,000 records. For a local NetInfo directory, make sure the file contains no more than 10,000 records. 2 Log in as the administrator of the directory domain you want to import accounts into. 3 Use the dsimport tool to import users and groups. For example, to import a file generated by Workgroup Manager named ”sample” and export it into the LDAPv3 directory located at 192.168.2.2, use the following command: $ dsimport -g sample /LDAPv3/192.168.2.2 -O -u diradmin Replace diradmin with the short name of the directory administrator. When two records match, the import file will overwrite the matching record. 4 To create home folders for imported users, use createhomedir . See “Creating a User’s Home Folder” on page 109. Creating a Character-Delimited User Import File You can create a character-delimited file by using Workgroup Manager or dsimport to export accounts in the LDAP directory of an Open Directory master or a NetInfo domain into a file. You can also create a character-delimited file by hand, using a script, or by using a database or spreadsheet application. The first record in the file, the record description, describes the format of each account record in the file. There are three options for the record description:  Write a full record description  Use the shorthand StandardUserRecord  Use the shorthand StandardGroupRecord The other records in the file describe user or group accounts, encoded in the format described by the record description. Any line of a character-delimited file that begins with # is ignored during importing. Writing a Record Description The record description specifies the fields in each record in the character-delimited file, specifies the delimiting characters, and specifies the escape character that precedes special characters in a record. Encode the record description using the following elements in the order specified, separating them with a space:  End-of-record indicator (in hex notation)  Escape character (in hex notation)  Field separator (in hex notation)  Value separator (in hex notation)  Type of accounts in the file (dsRecTypeStandard:Users or dsRecTypeStandard:Groups)  Number of attributes in each account record 120 Chapter 8 Working with Users and Groups  List of attributes For user accounts, the list of attributes must include the following, although you can omit UID and PrimaryGroupID if you specify a starting UID and a default primary group ID when you import the file:  RecordName (the user’s short name)  Password  UniqueID (the UID)  PrimaryGroupID  RealName (the user’s full name) In addition, you can include:  UserShell (the default shell)  NFSHomeDirectory (the path to the user’s home folder)  Other user data types, described in the Open Directory administration guide For group accounts, the list of attributes must include:  RecordName (the group name)  PrimaryGroupID (the group ID)  GroupMembership The following is an example of a record description: 0x0A 0x5C 0x3A 0x2C dsRecTypeStandard:Users 7 RecordName Password UniqueID PrimaryGroupID RealName NFSHomeDirectory UserShell The following is an example of a record encoded using the previous description: anne:Adl47E$:408:20:A. Johnsons, M.D.:/Network/Servers/somemac/Homes/anne:/ bin/csh The record consists of values, delimited by colons. Use a double-colon (::) to indicate that a value is missing. The following is another example, which shows a record description and user records for users whose passwords are to be validated using the Password Server. The record description should include a field named dsAttrTypeStandard:AuthMethod, and the value of this field for each record should be dsAuthMethodStandard:dsAuthClearText: 0x0A 0x5C 0x3A 0x2C dsRecTypeStandard:Users 8 dsAttrTypeStandard:RecordName dsAttrTypeStandard:AuthMethod dsAttrTypeStandard:Password dsAttrTypeStandard:UniqueID dsAttrTypeStandard:PrimaryGroupID dsAttrTypeStandard:Comment dsAttrTypeStandard:RealName dsAttrTypeStandard:UserShell skater:dsAuthMethodStandard\:dsAuthClearText:pword1:374:11:comment: Tony Hawk:/bin/csh mattm:dsAuthMethodStandard\:dsAuthClearText:pword2:453:161:: Chapter 8 Working with Users and Groups 121 Matt Mitchell:/bin/tcsh As these examples illustrate, you can use the prefix dsAttrTypeStandard: when referring to an attribute, or you can omit the prefix. When you use Workgroup Manager to export character-delimited files, it uses the prefix in the generated file. When importing user passwords, you can insert the following in the list of attributes to set the user’s password type to Open Directory: dsAttrTypeStandard:AuthMethod The method for setting an imported user’s password type to Open Directory requires that the imported data actually have a password value. If the password value is missing for a user, then the corresponding user record will be created with a password type of Crypt or Shadow Password. Then, insert the following in the formatted record (in this example, the user ‘s password is “password”): dsAuthMethodStandard\:dsAuthClearText:password Note: In this example, the colon (:) is the field separator. Because there is a colon in the description for this attribute, the escape character must be used to indicate that the colon should not be treated as a delimiter. The backslash (\) is the escape character in this example. If the field separator is anything other than the colon, the escape character is not needed. Using the StandardUserRecord Shorthand When the first record in a character-delimited import file contains StandardUserRecord, the following record description is assumed: 0x0A 0x5C 0x3A 0x2C dsRecTypeStandard:Users 7 RecordName Password UniqueID PrimaryGroupID RealName NFSHomeDirectory UserShell An example user account looks like this: anne:Adl47E$:408:20:A. Johnson, M.D.:/Network/Servers/somemac/Homes/anne:/ bin/csh Using the StandardGroupRecord Shorthand When the first record in a character-delimited import file contains StandardGroupRecord, the following record description is assumed: 0x0A 0x5C 0x3A 0x2C dsRecTypeStandard:Groups 4 RecordName Password PrimaryGroupID GroupMembership The following is an example of a record encoded using the description: students:Ad147:88:johnson,miller,clark,chen,wong 122 Chapter 8 Working with Users and Groups Setting Permissions To control access to your information, Mac OS X automatically sets permissions for disks, folders, and files. You can only change permissions to items that you own. Be sure that the default permissions are appropriate. For most purposes, files should be accessible to the other members of your group. If you have private or confidential information, the default permissions of the files may allow others to see it. To prevent others from accessing personal information, create a folder and set its permissions to “owner.” Then place your confidential files into it. No other users will be allowed into the folder. Mac OS X provides distinct permissions for three types of users:  The “owner” of the item, who is usually the person who created the item  Any member of the group assigned to the item by Mac OS X  Any other user with access to the computer There are four levels of permission:  Read & Write allows a user to open the item to see its contents and change it.  Read Only allows a user to open the item to see its contents, but not change or copy the contents.  Write Only makes a folder into a drop box. Users can copy items to the drop box, but cannot open the drop box to see its contents. Only the owner of the drop box can open it to access items.  No Access blocks all access to the item so that users can’t open the item, change its contents, or copy its contents. Viewing Permissions Each security group is assigned a code that controls that group’s permissions:  r (read) allows the user to see the item but not make changes.  w (write) allows the user to see and make changes to the item.  x (execute) allows the user to run scripts or programs.  - (access) means access is turned off. To view permissions for files and folders, enter the ls -l command. For each file or folder listed, you see the permissions, owner and group name, and file or folder name. Some examples of permission settings:  The following file (-) displays read, write, and executable permissions for owner (rwx), group (rwx) and all others (rwx): -rwxrwxrwx  The following file (-) displays read, write, and executable permissions for owner (rwx), and group (rwx), but no permissions for others (---): -rwxrwx--- Chapter 8 Working with Users and Groups 123  The following file (-) displays read, write, and executable permissions for owner (rwx), but no permissions for group (---) or others (---): -rwx------  The following file (-) displays read and write, but no executable permissions for owner (rw-), group (rw-), and others (rw-): -rw-rw-rw-  The following file (-) displays read, write, and executable permissions for owner (rwx), but only read and executable for group (r-x) and others (r-x): -rwxr-xr-x  The following file (-) displays read, write, and executable permissions for owner (rwx), but only read for group (r--) and others (r--): -rwxr--r-- See the ls man page for more information about viewing permissions. Setting the umask for Individual Users The global umask setting determines the permissions of new files and folders created by a local user. $ sudo defaults write -g NSUmask -int value Use one of the following values to set the permission level: Value Permission Level 63 (octal equivalent 077) Only the user can read newly created files. 23 (octal equivalent 027) User and members of the user’s default group can read newly created files. 18 (octal equivalent 022) All users can read newly created files. The default umask setting, 022, removes group and world write permissions, but allows group and world read permissions. With a umask setting of 027, files and folders created by a user will not be readable by every other user on the computer, but will still be readable by members of his assigned group. The owner of the file or folder can still make it accessible to others by changing the permissions in the Finder’s Get Info window or by using the chmod tool. To set the NSUmask settings for all local users to octal 027 (decimal equivalent 23): $ sudo defaults write /Library/Preferences/.GlobalPreferences NSUmask 23 Note: The path above refers to the .GlobalPreferences defaults domain, not to the file .GlobalPreferences.plist, which might accidentally be filled in while using the shell autocomplete feature. 124 Chapter 8 Working with Users and Groups This command affects the permissions on files and folders created by programs that respect the Mac OS X NSUmask settings. Programs should follow the value set for NSUmask, but there is no guarantee that they will. Also, users can override their own NSUmask setting at any time. The changes to the umask settings take effect at next login. Warning: Setting permissions to group, or all, will allow any private, or confidential information in these folders to be visible to others. To prevent private files being accessed, the user should create a folder and restrict the permissions. Changing Permissions Use the chmod tool to change permissions for an item. $ chmod securitygroup changetype permission fileorfolder Parameter Description securitygroup The person or group whose permission you are changing. Can be any of the following:  u - user  g - group  o - other  all - all changetype Type of change. Whether you are adding or subtracting the permission:  “+” - add permission  “-” - subtract permission permission The permission you are changing:  r - read  w - write  x - execute fileorfolder The name of the file or folder to change. To remove write access permission for group and others from the file myfile: $ chmod go-w myfile To add read and write access permission for group and others to files myfile1 and myfile2: $ chmod go+rw myfile1 myfile2 To add read, write, and execute permission for everyone to myfile1: $ chmod ugo+rwx myfile1 See the chmod man page for more information. Chapter 8 Working with Users and Groups 125 Changing the Owner Use the chown tool to change the owner of a file or folder. $ chown username fileorfolder Parameter Description username The user who will become the owner of the file. fileorfolder The name of the file or folder to change. To change the owner of file1 to the user jdoe: $ chown jdoe file1 See the chown man page for more information. Changing the Group Use the chgrp tool to change the group of a file or folder. $ chgrp groupname fileorfolder Parameter Description groupname The group that will become associated with the file or folder. fileorfolder The name of the file or folder to change. To change the group of file1 and file2 to the group ateam: $ chgrp ateam file1 file2 See the chgrp man page for more information. Securing System Accounts Security is very important when setting up and administering system accounts. The following sections cover security settings for user accounts. Securing Initial System Accounts Two accounts on the computer require attention before any further configuration is done. First, the permissions on the home folder of the initial administrator account should be changed. Second, any necessary modifications to the root account should be performed. To secure initial system accounts, the permissions on the home folder of the initial administrator account should be changed to allow only administrator access. The permissions on the home folder of the just-created administrator account allow any user who logs in to the computer to browse its contents. To change permissions on the administrator’s home folder: $ chmod 700 /Users/adminname where adminname is the name of the account. The 700 permission setting allows only the administrator to read and browse files in his home folder. 126 Chapter 8 Working with Users and Groups Securing the Root Account Mac OS X Server includes a root account like other UNIX-based systems. Initially, its password is set to that of the first administrator account. Direct root login should not be allowed, because the logs cannot identify which administrator logged in. Instead, accounts with administrator privileges should be used for login, and then the sudo tool used to perform actions as root. The computer uses a file called /etc/sudoers to determine which users have the authority to use the sudo program, and this file initially specifies that all accounts with administrator privileges may use sudo. To disable root login: 1 Start the dscl tool in interactive mode, specifying the computer you are using as the source of directory service data: $ dscl localhost > 2 Change the current folder to /NetInfo/root/Users by entering the path at the prompt: > cd /NetInfo/root/Users 3 Authenticate as an administrator by entering the following command, replacing adminusername with your administrator user name, and entering your administrator password when prompted: > auth adminusername 4 The following commands disable the root login by removing the AuthenticationAuthority property and its value, and modifying the root password property. > delete root AuthenticationAuthority ;ShadowHash; > delete root AuthenticationAuthority Any user with administrative privileges can reenable root login by entering passwd root in a Terminal window. Restricting Use of the sudo Tool The list of administrators allowed to use the sudo tool should be limited to only those administrators who require the ability to run commands as root. To change the /etc/sudoers file: 1 Edit the /etc/sudoers file using the visudo tool, which allows for safe editing of the file. The command must be run as root: $ sudo visudo 2 Enter the root password when prompted. Chapter 8 Working with Users and Groups 127 Note: There is a timeout value associated with the sudo tool. This value indicates the number of minutes until the sudo tool prompts for a password again. The default value is 5, which means that after issuing the sudo command and entering the correct password, additional sudo commands can be entered for 5 minutes without reentering the password. This value is set in the /etc/sudoers file. See the sudo and sudoers man pages for more information. 3 In the Defaults specification section of the file, add the following line: Defaults timestamp_timeout=0 4 Restrict which administrators are allowed to run the sudo tool by removing the line that begins with %admin, and adding the following entry for each user, substituting the user’s short name for the word user: user ALL=(ALL) ALL Doing this will mean that any time a new administrator is added to a system, that administrator must be added to the /etc/sudoers file as described above if that administrator requires the ability to use the sudo tool. 5 Save and quit visudo. See the vi and visudo man pages for more information. Securing Single-User Boot On Apple computers running Mac OS X, Open Firmware is the software executed immediately after the computer is powered on. This boot firmware is analogous to the BIOS on an x86-based PC. To prevent users from obtaining root access by booting into single user mode or booting from other disks, the Open Firmware settings should be altered. For desktop computers, the Open Firmware security mode should be set to command. To configure the Open Firmware settings, use the nvram tool. To set the variable security mode, enter the following command: $ nvram security-mode=“command” In command mode, the computer will boot from the boot device specified in the computer’s boot device variable and disallow users from providing any boot arguments. To test that the computer has been put into command mode as recommended: 1 Close all applications and choose Restart from the Apple menu. 2 A confirmation window will pop up. Restart the computer by clicking the Restart button. 3 Hold down the key combination Command-S while the computer boots. 4 If the command mode has been set correctly, the computer will display the Mac OS X login window. Normally, holding down the Command-S key combination while starting up would cause the computer to start up in single-user mode. 128 Chapter 8 Working with Users and Groups 5 If the computer did start up in single-user mode, restart the computer by issuing the command reboot. Then repeat the previous steps for putting the computer into command mode. Open Firmware protection can be violated if the user has physical access to the computer; If the user changes the physical memory configuration of the computer and then resets the PRAM 3 times (holding down Option-P-R during boot), the Open Firmware password will be disabled. To set the Open Firmware password for increased security: 1 Boot the computer while holding Command-Option-O-F (all four keys at the same time) to enter the Open Firmware command prompt. 2 At the prompt, enter the command: > password 3 Enter and verify the password to be used as the Open Firmware password. This password is limited to eight characters. A strong password should be chosen; in this instance, a computer-generated random password would be a good choice. This password should be written down, and secured in the same location as the Master FileVault password. This password will not be needed except for situations where the computer must be booted from an alternate disk, such as if the startup disk fails or its file system is in need of repair. 4 To restart the computer and enable the settings, enter the command: > reset-all 5 The computer should restart and display the login window. Note: An Open Firmware password provides some protection, although it can be reset if a user has physical access to the computer and can change the physical memory configuration of the computer. Setting Password Policy Us the pwpolicy tool to adjust the password policies of your users. This tool can be used to view or set global password policies that force users to change passwords, limit the number and type of characters in a password, the length of time before passwords can be reused, and when passwords must be changed. For secure passwords, you should require every password to have a minimum of 5 characters. You may use a higher number of characters if a more secure password is desired. It is also a good idea to have users change passwords frequently. Chapter 8 Working with Users and Groups 129 To change a user’s password: $ pwpolicy -n /LDAPv3/ipaddress -a adminusername -u usertochange -setpassword newpassword Parameter Description ipaddress Location of the LDAP directory. adminusername User name of an administrator. usertochange User name of the user whose password is changing. newpassword The password the user is changing to. To view the global password policy: $ pwpolicy -getglobalpolicy To set the minimum password length to 5 characters: $ pwpolicy -n /LDAPv3/ipaddress -a adminusername -setglobalpolicy “minChars=5” Parameter Description ipaddress Location of the LDAP directory. adminusername User name of an administrator. minChars Minimum number of characters in the password. To set a more secure global password policy: $ pwpolicy -n /LDAPv3/ipaddress -a adminusername -setglobalpolicy "minChars=6 usingHistory=4 requiresNumeric=1 maxMinutesUntilChangePassword=43200" This sets the global password policy for all users requiring:  the password to have a minimum of six characters  the users cannot reuse a password from the previous four passwords  the password must contain at least one number  the password must be changed every thirty days Parameter Description ipaddress Location of the LDAP directory. adminusername User name of an administrator. minChars Minimum number of characters in the password. usingHistory Sets the number of previous passwords that the user is not allowed to reuse. requiresNumeric Number of numeric characters that must be in the password. maxMinutesUntilChangePas Number of minutes until a password must be changed. sword 130 Chapter 8 Working with Users and Groups To set the password policy of an individual user to change their password: $ pwpolicy -n /LDAPv3/ldap.apple.com -a adminusername -p adminpassword -u usertochange -setpolicy "newPasswordRequired=1" Parameter Description ldap.apple.com Location of the LDAP directory. adminusername User name of an administrator. adminpassword The administrator password (omit this to prompt for the password) usertochange User name of the user whose password is changing. newPasswordRequired Set to 1 to prompt the user to enter a new password. See the pwpolicy man page for more information. Finding User Account Information The lookupd daemon acts as an information broker and cache. It is called by various routines in the system framework to find information about user accounts, groups, printers, email aliases and distribution lists, computer names, Internet addresses, and several other kinds of information. You can use it interactively to find out user account information. To query for a user by name: $ lookupd -d > userWithName: admin To see a list of all the different commands that run with lookupd: $ lookupd -d >? To get a description of a specific command that you can run with lookupd: Access the help prompt and enter the command name. $ lookupd -d >help help> [command] See the lookupd man page for more information. Chapter 8 Working with Users and Groups 131 132 Chapter 8 Working with Users and Groups 9 Working with File Services 9 In this chapter you will find commands you can use to create share points and manage file services. Mac OS X Server allows you to set up central network storage that is accessible to clients throughout your organization. Using native protocols, it delivers file services to heterogeneous clients on your network: Apple Filing Protocol (AFP) for Mac, Network File System (NFS) for UNIX and Linux, Server Message Block/Common Internet File System (SMB/CIFS) for Windows, as well as WebDAV and FTP for Internet clients. This chapter covers the commands that are used to configure and manage these file services. Managing Share Points A share point is a folder, hard disk, hard disk partition, CD, or DVD that users can access over the network to share information. Users with access privileges, which are assigned, view share points as mounted volumes. Mac OS X Server supports Microsoft Windows file sharing of any defined share point, not just Shared and Public folders in a user’s home folder. It also supports Windows Internet Naming Service (WINS), which allows Windows clients across multiple subnets to perform name/address resolution. You can use the sharing tool to list, create, and modify share points. See the sharing man page for more information. 133 Listing Share Points To list existing share points: $ sharing -l In the resulting list, there’s a section of properties similar to the following for each share point defined on the server (1 = yes, true, or enabled; 0 = false, no, or disabled). name: path: afp: } ftp: } smb: Share1 /Volumes/100GB { name: Share1 shared: 1 guest access: inherit perms: 0 0 { name: Share1 shared: 1 guest access: 1 { name: Share1 shared: 1 guest access: inherit perms: oplocks: strict locking: directory mask: create mask: 1 0 0 0 493 420 } Creating a Share Point To create a share point: $ sharing -a path [-n customname] [-A afpname] [-F ftpname] [-S smbname] [-s shareflags] [-g guestflags] [-i inheritflags] [-c creationmask] [-d directorymask] [-o oplockflag] [-t strictlockingflag] 134 Parameter Description path The full path to the folder you want to share. customname The name of the share point. If you don’t specify this custom name, it’s set to the name of the folder, the last name in path. afpname The share point name shown to and used by AFP clients. This name is separate from the share point name. ftpname The share point name shown to and used by FTP clients. smbname The share point name shown to and used by SMB/CIFS clients. shareflags A three-digit binary number indicating which protocols are used to share the folder. The digits represent, from left to right, AFP, FTP, and SMB/CIFS. 1=shared, 0=not shared. Chapter 9 Working with File Services Parameter Description guestflags A group of three flags indicating which protocols allow guest access. The flags are written as a three-digit binary number with the digits representing, from left to right, AFP, FTP, and SMB/CIFS. 1=guests allowed, 0=guests not allowed. inheritflags A group of two flags indicating whether new items in AFP or SMB/ CIFS share points inherit the ownership and access permissions of the parent folder. The flags are written as a two-digit binary number with the digits representing, from left to right, AFP and SMB/CIFS. 1=inherit, 0=don’t inherit. creationmask The SMB/CIFS creation mask. Default=0644. directorymask The SMB/CIFS folder mask. Default=0755. oplockflag Specifies whether opportunistic locking is allowed for an SMB/CIFS share point. 1=enable oplocks, 0=disable oplocks. For more information about oplocks, see the file services administration guide. strictlockingflag Specifies whether strict locking is used on an SMB/CIFS share point. 1=enable strict locking, 0=disable. For more information about strict locking, see the file services administration guide. To create a share point that uses AFP, FTP, and SMB/CIFS protocols: Enter the following command, replacing 100GB with the name of the volume containing the share point and Archive with the actual share point name: $ sharing -a /Volumes/100GB/Archive To create a share point that appears differently for different users: Enter the following command, replacing 100GB with the name of the volume containing the share point and Windows with the actual share point name so that it appears as WinDocs for server management purposes, and Documents for SMB/CIFS file service users: $ sharing -a /Volumes/100GB/Windows\ Docs -n WinDocs -S Documents -s 001 -o 1 This share point is shared using only the SMB/CIFS protocol with oplocks enabled. Modifying a Share Point To change share point settings: $ sharing -e sharepointname [-n customname] [-A afpname] [-F ftpname] [-S smbname] [-s shareflags] [-g guestflags] [-i inheritflags] [-c creationmask] [-d directorymask] [-o oplockflag] [-t strictlockingflag] Parameter Description sharepointname The current name of the share point. Other parameters See the parameter descriptions under “Creating a Share Point” on page 134. Chapter 9 Working with File Services 135 Disabling a Share Point To disable a share point: $ sharing -r sharepointname Parameter Description sharepointname The current name of the share point. Managing the AFP Service Apple Filing Protocol (AFP) allows any Mac OS X computer to access shared folders on the server. Mac OS X Server uses Bonjour to provide automatic discovery of AFP file services, and shared disks don’t unmount after extended periods of inactivity. Starting and Stopping AFP Service To start AFP service: $ sudo serveradmin start afp To stop AFP service: $ sudo serveradmin stop afp Checking AFP Service Status To see if AFP service is running: $ sudo serveradmin status afp To see complete AFP status: $ sudo serveradmin fullstatus afp Viewing AFP Settings To list all AFP service settings: $ sudo serveradmin settings afp To list a particular setting: $ sudo serveradmin settings afp setting Parameter Description setting Any of the AFP service settings. For a complete list of settings, enter $ sudo serveradmin settings afp or see “List of AFP Settings” on page 137. To list a group of settings: You can list a group of settings that have part of their names in common by typing only as much of the name as you want, stopping at a colon (:), and typing an asterisk (*) as a wildcard for the remaining parts of the name. For example: $ sudo serveradmin settings afp:loggingAttributes:* 136 Chapter 9 Working with File Services Changing AFP Settings You can change AFP service settings using the serveradmin tool. To change a setting: $ sudo serveradmin settings afp:setting = value Parameter Description setting An AFP service setting. To see a list of available settings, enter $ sudo serveradmin settings afp or see “List of AFP Settings” on page 137. value An appropriate value for the setting. Enclose text strings in double quotes (for example: "text string"). To change several settings: $ sudo serveradmin settings afp:setting = value afp:setting = value afp:setting = value [...] Control-D List of AFP Settings The following table lists AFP settings as they appear using serveradmin. Parameter (afp:) Description activityLog Turn activity logging on or off. Default = no activityLogPath Location of the activity log file. Default = /Library/Logs/AppleFileService/ AppleFileServiceAccess.log activityLogSize Rollover size (in kilobytes) for the activity log. Used only if activityLogTime isn’t specified. Default = 1000 activityLogTime Rollover time (in days) for the activity log. Default = 7 admin31GetsSp Set to yes to force administrator users on Mac OS X to see share points instead of all volumes. Default = yes adminGetsSp Set to yes to force administrator users on Mac OS 9 to see share points instead of all volumes. Default = no afpServerEncoding Encoding used with Mac OS 9 clients. Default = 0 afpTCPPort TCP port used by AFP on server. Default = 548 Chapter 9 Working with File Services 137 Parameter (afp:) Description allowRootLogin Allow user to log in as root. Default = no attemptAdminAuth Allow an administrator user to masquerade as another user. Default = yes authenticationMode Authentication mode. Can be: standard kerberos standard_and_kerberos Default = "standard_and_kerberos" autoRestart Whether the AFP service should restart automatically when abnormally terminated. Default = yes clientSleepOnOff Allow client computers to sleep. Default = yes clientSleepTime Time (in hours) that clients are allowed to sleep. Default = 24 createHomeDir Create home folders. Default = yes errorLogPath The location of the error log. Default = /Library/Logs/AppleFileService/ AppleFileServiceError.log 138 errorLogSize Rollover size (in kilobytes) for the error log. Used only if errorLogTime isn’t specified. Default = 1000 errorLogTime Rollover time (in days) for the error log. Default = 0 guestAccess Allow guest users access to the server. Default = yes idleDisconnectFlag: adminUsers Enforce idle disconnect for administrator users. Default = yes idleDisconnectFlag: guestUsers Enforce idle disconnect for guest users. Default = yes idleDisconnectFlag: registeredUsers Enforce idle disconnect for registered users. Default = yes idleDisconnectFlag: usersWithOpenFiles Enforce idle disconnect for users with open files. Default = yes idleDisconnectMsg The idle disconnect message. Default = "" idleDisconnectOnOff Enable idle disconnect. Default = no Chapter 9 Working with File Services Parameter (afp:) Description idleDisconnectTime Idle time (in minutes) allowed before disconnect. Default = 10 kerberosPrincipal Kerberos server principal name. Default ="afpserver" loggingAttributes: logCreateDir Record folder creations in the activity log. Default = yes loggingAttributes: logCreateFile Record file creations in the activity log. Default = yes loggingAttributes: logDelete Record file deletions in the activity log. Default = yes loggingAttributes: logLogin Record user logins in the activity log. Default = yes loggingAttributes: logLogout Log user logouts in the activity log. Default = yes loggingAttributes: logOpenFork Log file opens in the activity log. Default = yes loginGreeting The login greeting message. Default = "" loginGreetingTime The last time the login greeting was set or updated. maxConnections Maximum number of simultaneous user sessions allowed by the server. Default = -1 (unlimited) maxGuests Maximum number of simultaneous guest users allowed. Default = -1 (unlimited) maxThreads Maximum number of AFP threads. (Must be specified at startup.) Default = 40 noNetworkUsers Indication to client that all users are users on the server. Default = no permissionsModel How permissions are enforced. Can be set to: classic_permissions unix_with_classic_admin_permissions unix_permissions Default = "classic_permissions" recon1SrvrKeyTTLHrs Time-to-live (in hours) for the server key used to generate reconnect tokens. Default = 168 recon1TokenTTLMins Time-to-live (in minutes) for a reconnect token. Default = 10080 Chapter 9 Working with File Services 139 Parameter (afp:) Description reconnectFlag Allow reconnect options. Can be set to: none all no_admin_kills Default = "all" reconnectTTLInMin Time-to-live (in minutes) for a disconnected session waiting reconnection. Default = 1440 registerAppleTalk Advertise the server using AppleTalk NBP. Default = yes registerNSL Advertise the server using Bonjour. Default = yes sendGreetingOnce Send the login greeting only once. Default = no shutdownThreshold Don’t modify. Internal use only. specialAdminPrivs Grant administrator users root user read/write privileges. Default = no SSHTunnel Allow SSH tunneling. Default = yes TCPQuantum TCP message quantum. Default = 262144 tickleTime Frequency of tickles sent to client. Default = 30 updateHomeDirQuota Enforce quotas on the user’s volume. Default = yes useAppleTalk Don’t modify. Internal use only. List of AFP serveradmin Commands In addition to the standard start, stop, status, and settings commands, you can use serveradmin to execute the following service-specific AFP commands. See the examples in the following sections for details on how to use these commands. 140 Command (afp:command=) Description cancelDisconnect Cancel a pending user disconnect. See “Canceling a User Disconnect” on page 143. disconnectUsers Disconnect AFP users. See “Disconnecting AFP Users” on page 142. getConnectedUsers List settings for connected users. See “Listing Connected Users” on this page. getHistory View a periodic record of file data throughput or number of user connections. See “Listing AFP Service Statistics” on page 144. getLogPaths Display the locations of the AFP service activity and error logs. Chapter 9 Working with File Services Command (afp:command=) Description sendMessage Send a text message to connected AFP users. See “Sending a Message to AFP Users” on page 142. syncSharePoints Update share point information after changing settings. writeSettings Equivalent to the standard serveradmin settings command, but also returns a setting indicating whether the service needs to be restarted. See “Using the serveradmin Tool” on page 48. Listing Connected Users You can use the getConnectedUsers command with the serveradmin tool to retrieve information about connected AFP users. In particular, you can use this command to retrieve the session IDs you need to disconnect or send messages to users. To list connected users: $ sudo serveradmin command afp:command = getConnectedUsers The computer will respond with the following array of settings displayed for each connected user: afp:usersArray:_array_index:i:disconnectID = afp://sp.apple.com/Users ajohnson afp:usersArray:_array_index:i:flags = afp:usersArray:_array_index:i:ipAddress = afp:usersArray:_array_index:i:lastUseElapsedTime = afp:usersArray:_array_index:i:loginElapsedTime = afp:usersArray:_array_index:i:minsToDisconnect = afp:usersArray:_array_index:i:name = afp:usersArray:_array_index:i:serviceType = afp:usersArray:_array_index:i:sessionID = afp:usersArray:_array_index:i:sessionType = afp:usersArray:_array_index:i:state = Value returned by getConnectedUsers (afp:usersArray:_array_index: :) Description An integer that identifies this particular disconnect. This will appear once a disconnect has been issued. Indicates the type of user. 1-session belongs to the administrator 2-session belongs to a guest 4-session is sleeping The user’s IP address. Time since the command was last run. The elapsed time since the user connected. The number of minutes between the time the command is issued and the user is disconnected The user’s name. Chapter 9 Working with File Services 141 Value returned by getConnectedUsers (afp:usersArray:_array_index: :) Description The share point the user is accessing. An integer that identifies the user session. State of the service. Sending a Message to AFP Users You can use the sendMessage command with the serveradmin tool to send a text message to connected AFP users. Users are specified by session ID. To send a message: $ sudo serveradmin command afp:command = sendMessage afp:message = "message-text" afp:sessionIDsArray:_array_index:0 = sessionid1 afp:sessionIDsArray:_array_index:1 = sessionid2 afp:sessionIDsArray:_array_index:2 = sessionid3 [...] Control-D Parameter Description message-text The message that appears on client computers. sessionidn The session ID of a user you want to receive the message. To list the session IDs of connected users, use the getConnectedUsers command. See “Listing Connected Users” on page 141. Disconnecting AFP Users You can use the disconnectUsers command with the serveradmin tool to disconnect AFP users. Users are specified by session ID. You can specify a delay time before disconnect and a warning message. To disconnect users: $ sudo serveradmin command afp:command = disconnectUsers afp:message = "message-text" afp:minutes = minutes-until afp:sessionIDsArray:_array_index:0 = sessionid1 afp:sessionIDsArray:_array_index:1 = sessionid2 afp:sessionIDsArray:_array_index:2 = sessionid3 [...] Control-D 142 Parameter Description message-text The text of a message that appears on client computers in the disconnect announcement dialog. Chapter 9 Working with File Services Parameter Description minutes-until The number of minutes between the time the command is executed and the users are disconnected. sessionidn The session ID of a user you want to disconnect. To list the session IDs of connected users, use the getConnectedUsers command. See “Listing Connected Users” on page 141. The computer will repond with the following output: afp:command = "disconnectUsers" afp:messageSent = " " afp:timeStamp = "