Apple oxs User Manual

Download

Page 1

Mac OS X Server Command-Line Administration

For Version 10.3 or Later

Page 2



Apple Computer, Inc.

The owner or authorized user of a valid copy of Mac OS X Server software may reproduce this publication for the purpose of learning to use such software. No part of this publication may be reproduced or transmitted for commercial purposes, such as selling copies of this publication or for providing paid for support services.

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, AirPort, AppleScript, AppleShare, AppleTalk, ColorSync, FireWire, iMac, Keychain, Mac, Macintosh, Power Mac, Power Macintosh, QuickTime, Sherlock, and WebObjects are trademarks of Apple Computer, Inc., registered in the U.S. and other countries. Extensions Manager and Finder are trademarks of Apple Computer, Inc.

034-2354/10-24-03

Page 3

Preface 11 About This Book

Notation Conventions

11 11 11 12 12

Summary Commands and Other Terminal Text Command Parameters and Options Default Settings Commands Requiring Root Privileges

Chapter 1 13 Typing Commands

Using Terminal

14 14 14 15 16 16 17 17 18 18 19 19 19

Correcting Typing Errors Repeating Commands Including Paths Using Drag-and-Drop Commands Requiring Root Privileges

Sending Commands to a Remote Server

Sending a Single Command Updating SSH Key Fingerprints Notes on Communication Security and

Using Telnet Getting Online Help for Commands Notes About Specific Commands and Tools

serversetup

serveradmin

servermgrd

Chapter 2 21 Installing Server Software and Finishing Basic Setup

Installing Server Software

Automating Server Setup

22 25 25 25

Creating a Configuration File Template Creating Customized Configuration Files from the Template File Naming Configuration Files Storing a Configuration File in an Accessible Location

Changing Server Settings

Page 4

Viewing, Validating, and Setting the Software Serial Number

Updating Server Software

Moving a Server

Chapter 3 29 Restarting or Shutting Down a Server

Restarting a Server

29 29 30 30 30

Examples

Automatic Restart Changing a Remote Server’s Startup Disk Shutting Down a Server

Examples

Chapter 4 31 Setting General System Preferences

Computer Name

31 32 32 32 33 33 33 33

34 34 34

35 35 35 35 35 36 36

Viewing or Changing the Computer Name

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

Energy Saver Settings

Viewing or Changing Sleep Settings

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

Viewing or Changing the Startup Disk Sharing Settings

Viewing or Changing Remote Login Settings

Viewing or Changing Apple Event Response International Settings

Viewing or Changing Language Settings Login Settings

Disabling the Restart and Shutdown Buttons

Chapter 5 37 Network Preferences

Network Interface Information

37 38 38 38 38 38

Viewing Port Names and Hardware Addresses

Viewing or Changing MTU Values

Viewing or Changing Media Settings Network Port Configurations

Creating or Deleting Port Configurations

Activating Port Configurations

Contents

Page 5

39 39 39

41 42 42 42 42 42 43 43 43 43 44 44 44 44 44 44 45 45

Changing Configuration Precedence

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

AppleTalk Settings

Enabling and Disabling AppleTalk

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

AirPort Settings

Viewing or Changing Airport Settings

Computer, Host, and Rendezvous Name

Viewing or Changing the Computer Name Viewing or Changing the Local Host Name Viewing or Changing the Rendezvous Name

Chapter 6 47 Working With Disks and Volumes

Mounting and Unmounting Volumes

47 47 47 48 49 50 50 50

51 51 51 51

Mounting Volumes

Unmounting Volumes Checking for Disk Problems Monitoring Disk Space Reclaiming Disk Space Using Log Rolling Scripts Managing Disk Journaling

Checking to See if Journaling is Enabled

Turning on Journaling for an Existing Volume

Enabling Journaling When You Erase a Disk

Disabling Journaling Erasing, Partitioning, and Formatting Disks

Setting Up a Case-Sensitive HFS+ File System Imaging and Cloning Volumes Using ASR

Chapter 7 53 Working With Users and Groups

Creating Server Administrator Users

Importing Users and Groups

Creating a Character-Delimited User Import File

Contents

Page 6

User Attributes

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

Creating a User’s Home Directory

63 Mounting a User’s Home Directory 63 Creating a Group Folder 63 Checking a User’s Administrator Privileges

Chapter 8 65 Working With File Services

65 Share Points 65 Listing Share Points

66 Creating a Share Point

67 Modifying a Share Point 67 Disabling a Share Point 67 AFP Service 67 Starting and Stopping AFP Service 67 Checking AFP Service Status

67 Viewing AFP Settings 68 Changing AFP Settings 68 List of AFP Settings

72 List of AFP serveradmin Commands

72 Listing Connected Users

73 Sending a Message to AFP Users

73 Disconnecting AFP Users

74 Canceling a User Disconnect

75 Listing AFP Service Statistics

76 Viewing AFP Log Files

76 NFS Service

76 Starting and Stopping NFS Service

76 Checking NFS Service Status

76 Viewing NFS Settings

77 Changing NFS Service Settings

77 FTP Service

77 Starting FTP Service

77 Stopping FTP Service

77 Checking FTP Service Status

77 Viewing FTP Settings

78 Changing FTP Settings

78 FTP Settings

79 List of FTP serveradmin Commands 80 Viewing the FTP Transfer Log 80 Checking for Connected FTP Users 80 Windows (SMB) Service 80 Starting and Stopping SMB Service

Contents

Page 7

80 Checking SMB Service Status

81 Viewing SMB Settings 81 Changing SMB Settings

82 List of SMB Service Settings 84 List of SMB serveradmin Commands 84 Listing SMB Users

85 Disconnecting SMB Users 86 Listing SMB Service Statistics 86 Updating Share Point Information

87 Viewing SMB Service Logs

Chapter 9 89 Working With Print Service

89 Starting and Stopping Print Service 89 Checking the Status of Print Service 89 Viewing Print Service Settings 90 Changing Print Service Settings 90 Print Service Settings

91 Queue Data Array

93 Print Service serveradmin Commands

93 Listing Queues

93 Pausing a Queue 94 Listing Jobs and Job Information 94 Holding a Job

95 Viewing Print Service Log Files

Chapter 10 97 Working With NetBoot Service

97 Starting and Stopping NetBoot Service

97 Checking NetBoot Service Status

97 Viewing NetBoot Settings 98 Changing NetBoot Settings 98 NetBoot Service Settings 98 General Settings 99 Storage Record Array 99 Filters Record Array

10 0 Image Record Array 101 Port Record Array

Chapter 11 103 Working With Mail Service

10 3 Starting and Stopping Mail Service 10 3 Checking the Status of Mail Service 10 3 Viewing Mail Service Settings 10 4 Changing Mail Service Settings 10 4 Mail Service Settings

Contents 7

Page 8

11 6 Mail serveradmin Commands 117 Listing Mail Service Statistics 11 8 Viewing the Mail Service Logs 11 9 Setting Up SSL for Mail Service 11 9 Generating a CSR and Creating a Keychain 121 Obtaining an SSL Certificate

121 Importing an SSL Certificate Into the Keychain 12 2 Creating a Passphrase File 12 2 Setting Up SSL for Mail Service on a Headless Server

Chapter 12 123 Working With Web Technologies

12 3 Starting and Stopping Web Service 12 3 Checking Web Service Status 12 3 Viewing Web Settings 12 4 Changing Web Settings 12 4 serveradmin and Apache Settings 12 4 Changing Settings Using serveradmin 12 5 Web serveradmin Commands 12 5 Listing Hosted Sites 12 5 Viewing Service Logs 12 6 Viewing Service Statistics 12 7 Example Script for Adding a Website

Chapter 13 129 Working With Network Services

12 9 DHCP Service 12 9 Starting and Stopping DHCP Service 12 9 Checking the Status of DHCP Service 12 9 Viewing DHCP Service Settings 13 0 Changing DHCP Service Settings 13 0 DHCP Service Settings

131 DHCP Subnet Settings Array 13 3 Adding a DHCP Subnet 13 4 List of DHCP serveradmin Commands 13 4 Viewing the DHCP Service Log 13 5 DNS Service 13 5 Starting and Stopping the DNS Service 13 5 Checking the Status of DNS Service 13 5 Viewing DNS Service Settings 13 5 Changing DNS Service Settings 13 5 DNS Service Settings 13 5 List of DNS serveradmin Commands 13 5 Viewing the DNS Service Log 13 6 Listing DNS Service Statistics

8 Contents

Page 9

13 6 Firewall Service 13 6 Starting and Stopping Firewall Service 13 7 Checking the Status of Firewall Service 13 7 Viewing Firewall Service Settings 13 7 Changing Firewall Service Settings 13 7 Firewall Service Settings 13 8 Defining Firewall Rules

141 IPFilter Rules Array 141 Firewall serveradmin Commands

14 2 Viewing Firewall Service Log 14 2 Using Firewall Service to Simulate Network Activity 14 2 NAT Service 14 2 Starting and Stopping NAT Service 14 2 Checking the Status of NAT Service 14 2 Viewing NAT Service Settings 14 3 Changing NAT Service Settings 14 3 NAT Service Settings 14 4 NAT serveradmin Commands 14 4 Viewing the NAT Service Log 14 5 VPN Service 14 5 Starting and Stopping VPN Service 14 5 Checking the Status of VPN Service 14 5 Viewing VPN Service Settings 14 5 Changing VPN Service Settings 14 6 List of VPN Service Settings 14 9 List of VPN serveradmin Commands 14 9 Viewing the VPN Service Log 15 0 IP Failover 15 0 Requirements 15 0 Failover Operation

151 Enabling IP Failover 15 2 Configuring IP Failover 15 3 Enabling PPP Dial-In

Chapter 14 155 Working With Open Directory

15 5 General Directory Tools 15 5 Testing Your Open Directory Configuration 15 5 Modifying an Open Directory Node 15 5 Testing Open Directory Plugins 15 6 Registering URLs With Service Location Protocol (SLP) 15 6 Changing Open Directory Service Settings 157 LDAP 157 Configuring LDAP

Contents 9

Page 10

157 A Note on Using ldapsearch 15 8 Idle Rebinding Options 15 8 Additional Information About LDAP 15 9 NetInfo 15 9 Configuring NetInfo 15 9 Password Server 15 9 Working With the Password Server 15 9 Viewing or Changing Password Policies 15 9 Enabling or Disabling Authentication Methods 160 Kerberos and Single Sign On

Chapter 15 161 Working With QuickTime Streaming Server

161 Starting QTSS Service

161 Stopping QTSS Service

161 Checking QTSS Service Status 162 Viewing QTSS Settings 162 Changing QTSS Settings 163 QTSS Settings 166 QTSS serveradmin Commands 166 Listing Current Connections 167 Viewing QTSS Service Statistics 168 Viewing Service Logs 168 Forcing QTSS to Re-Read its Preferences 169 Preparing Older Home Directories for User Streaming

Index 171

10 Contents

Page 11

About This Book

Notation Conventions

The following conventions are used throughout this book.

Summary

Notation Indicates

monospaced font A command or other terminal text $ A shell prompt [text_in_brackets] An optional parameter (one|other) Alternative parameters (type one or the other) underlined [...] A parameter that may be repeated <anglebrackets> A displayed value that depends on your server configuration

A parameter you must replace with a value

Preface

Commands and Other Terminal Text

Commands or command parameters that you might type, 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 as you might type it in a Terminal window, it follows a dollar sign that represents the shell prompt. For example,

$ doit

To use this command, type “doit” without the dollar sign at the command prompt in a Terminal window, then press the Return key.

Command Parameters and Options

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

Page 12

Parameters You Must Type as Shown

If you need to type 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 the above example, type the entire line as shown.

Parameter Values You Provide

If you need to supply a value, its placeholder is underlined and has a name that indicates what you need to provide. For example,

$ doit -w later -t hh:mm

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

Optional Parameters

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

$ doit [-w later]

To use the command in the above example, type either doit or doit -w later. The result might vary but the command will be performed either way.

Alternative Parameters

If you need to type 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 the command, you must type 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 other choices you’ve made (such as the name or IP address of your server, for example), it’s enclosed in angle brackets <>.

For example, the default value for the IMAP mail server is the host name of your server. This is indicated by mail:imap:servername = "<hostname>".

Commands Requiring Root Privileges

Throughout this guide, commands that require root privileges begin with sudo.

12 Preface About This Book

Page 13

1 Typing Commands

How to use Terminal to execute commands, connect to a remote server, and view online information about commands and utilities.

To access a UNIX shell command prompt, you open the Terminal application. In Terminal, you can use the ssh command to log in to other servers. You can use the man command to view online documentation for most common commands.

Using Terminal

To enter shell commands or run server command-line tools and utilities, 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 (in /Applications/Utilities).

Terminal presents a prompt when it’s ready to accept a command. The prompt you see depends on Terminal and shell preferences, but often includes the name of the host you’re logged in to, your current working directory, your user name, and a prompt symbol. For example, if you’re using the default bash shell and the prompt is

server1:~ admin$

you’re logged in to a computer named “server1” as the user named “admin” and your current directory is the admin’s home directory (~).

Throughout this manual, wherever a command is shown as you might type it, the prompt is abbreviated as $.

Page 14

To type a command:

Wait for a prompt to appear in the Terminal window, then type the command and press Return.

If you get the message command not found, check your spelling. If the error recurs, the program you’re trying to run might not be in your default search path. Add the path before the program name or change your working directory to the directory that contains the program. For example:

[server:/] admin$ serversetup -getAllPort serversetup: Command not found. [server:/] admin$ /System/Library/ServerSetup/serversetup -getAllPort 1 Built-in Ethernet [server:/] admin$ cd /System/Library/ServerSetup [server:/System/Library/ServerSetup] admin$ ./serversetup -getAllPort 1 Built-in Ethernet [server:/System/Library/ServerSetup] admin$ cd / [server:/] admin$ PATH = "$PATH:/System/Library/ServerSetup" [server:/] admin$ serversetup -getAllPort 1 Built-in Ethernet

Correcting Typing Errors

To correct a typing error before you press Return to issue the command, use the Delete key or press Control-H to erase unwanted characters and retype.

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

Repeating Commands

To repeat a command, press Up-Arrow until you see the command, then press Return.

To repeat a command with modifications, press Up-Arrow until you see the command, press Left-Arrow or Right-Arrow to skip over parts of the command you don’t want to change, press Delete to remove characters, type regular characters to insert them, then press Return to execute the command.

Including Paths Using Drag-and-Drop

To include a fully-qualified file name or directory path in a command, stop typing where the item is required in the command and drag the folder or file from a Finder window into the Terminal window.

14 Chapter 1 Typing Commands

Page 15

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 issue a single command as the root user, begin the command with sudo. 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 type 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.

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 understand clearly what you’re doing. Logging in as an administrative user and using sudo selectively might prevent you from making unintended changes.

Throughout this guide, commands that require root privileges begin with sudo.

Chapter 1 Typing Commands 15

Page 16

Sending Commands to a Remote Server

Secure Shell (SSH) lets you send secure, encrypted commands to a server over the network. You can use the ssh command in Terminal to open a command-line connection to a remote server. While the connection is open, commands you type are performed on the remote server.

Note: You can use any application that supports SSH to connect to Mac OS X Server.

To open a connection to a remote server:

1 Open Terminal.

2 Type the following command to log in to the remote server:

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.

Example: ssh -l admin 10.0.1.2

3 If this is the first time you’ve connected to the server, you’re prompted to continue

connecting after the remote computer’s RSA fingerprint is displayed. Type yes and press Return.

4 When prompted, type the user’s password (the user’s password on the remote server)

and press Return.

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

[10.0.1.2:~] admin$

5 To send a command to the remote server, type the command and press Return.

To close a remote connection

Type logout and press Return.

Sending a Single Command

You can authenticate and send a command using a single typed line by appending the command you want to execute to the basic ssh command.

For example, to delete a file you could type

$ ssh -l admin server1.company.com rm /Users/admin/Documents/report

$ ssh -l admin@server1.company.com "rm /Users/admin/Documents/report"

You’re prompted for the user’s password.

16 Chapter 1 Typing Commands

Page 17

Updating SSH Key Fingerprints

The first time you connect to a remote server using SSH, the local computer asks if it can add the remote server’s “fingerprint” (a security key) to a list of known remote computers. You might see a message like this:

The authenticity of host "server1.company.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)?

Type yes and press Return to finish authenticating.

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

• Perform a clean install of the server software

• Start up from a Mac OS X Server CD

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.

Important: Removing an entry from the known_hosts file bypasses a security

mechanism that helps 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.

Notes on Communication Security and servermgrd

When you use the Server Admin GUI application or the serveradmin command-line tool, you’re communicating with a local or remote servermgrd process.

• servermgrd uses SSL for encryption and client authentication but not for user

authentication, which uses HTTP basic authentication along with Directory Services.

• servermgrd uses a self-signed (test) SSL certificate installed by default in

/etc/servermgrd/ssl.crt/. You can replace this with an actual certificate.

• The default certificate format for SSLeay/OpenSSL is PEM, which actually is Base64

encoded DER with header and footer lines (from www.modssl.org).

• servermgrd checks the validity of the SSL certificate only if the “Require valid digital

signature” option is checked in Server Admin preferences. If this option is enabled, the certificate must be valid and not expired or Server Admin will refuse to connect.

• The SSLOptions and SSLRequire settings determine what SSL encryption options are

used. By default, they’re set as shown below but can be changed at any time by editing /etc/servermgrd/servermgrd.conf, port 311.

SSLCertificateFile /private/etc/servermgrd/ssl.crt/server.crt SSLCertificateKeyFile /private/etc/servermgrd/ssl.key/server.key SSLCipherSuite

ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL

SSLOptions +StdEnvVars

Chapter 1 Typing Commands 17

Page 18

Using Telnet

Because it isn’t as secure as SSH, Telnet access isn’t enabled by default.

To enable Telnet access:

$ service telnet start

To disable Telnet access:

$ service telnet stop

Getting Online Help for Commands

Onscreen help is available for most commands and utilities.

Note: Not all techniques work for all commands, and some commands have no onscreen help.

To view onscreen information about a command, try the following:

• Type the command without any parameters or options. This will often list a summary

of options and parameters you can use with the command. Example:

$ sudo serveradmin

• Type man command, where command is the command you’re curious about. This

usually displays detailed information about the command, its options, parameters, and proper use. Example:

$ man serveradmin

For help using the man command, type:

$ man man

• Type the command followed by a -help, -h, --help, or help parameter.

Examples:

$ hdiutil help $ dig -h $ diff --help

18 Chapter 1 Typing Commands

Page 19

Notes About Specific Commands and Tools

serversetup

The serversetup utility is located in /System/Library/ServerSetup. To run this command, you can type the full path, for example:

$ /System/Library/ServerSetup/serversetup -getAllPort

Or, if you want to use the utility to perform several commands, you can change your working directory and type a shorter command:

$ cd /System/Library/ServerSetup $ ./serversetup -getAllPort $ ./serversetup -getDefaultInfo

or add the directory to your search path for this session and type an even shorter command:

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

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

serveradmin

You can use the serveradmin tool to perform many service-related tasks. You’ll see it used throughout this guide.

Determining Whether a Service Needs to be Restarted

Some services need to be restarted after you change certain settings. If a change you make using a service’s writeSettings command requires that you restart the service, the output from the command includes the setting <svc>:needsRecycleOrRestart with a value of yes.

Important: The needsRecycleOrRestart setting is displayed only if you use the

serveradmin svc:command = writeSettings command to change settings. You

won’t see it if you use the serveradmin settings command.

Chapter 1 Typing Commands 19

Page 20

Page 21

2 Installing Server Software and

Finishing Basic Setup

Commands you can use to install, set up, and update Mac OS X Server software on local or remote computers.

Installing Server Software

You can use the installer command to install Mac OS X Server or other software on a computer. For more information, see the man page.

Automating Server Setup

Normally, when you install Mac OS X Server on a computer and restart, the Server Assistant opens and asks you to provide the basic information necessary to get the server up and running (for example, the name and password of the administrator user, the TCP/IP configuration information for the server’s network interfaces, and how the server uses directory services). You can automate this initial setup task by providing a configuration file that contains these settings. Servers starting up for the first time look for this file and use it to complete initial server setup without user interaction.

Creating a Configuration File Template

An easy way to prepare configuration files to automate the setup of a group of servers is to start with a file saved using the Server Assistant. You can save the file as the last step when you use the Server Assistant to set up the first server, or you can run the Server Assistant later to create the file. You can then use that first file as a template for creating configuration files for other servers. You can edit the file directly or create scripts to create customized configuration files for any number of servers that use similar hardware.

To save a template configuration file during server setup:

1 In the final pane of the 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.

So you can later edit the file, don’t select “Save in Encrypted Format.”

3 Choose a location to save the file and click Save.

Page 22

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

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

2 In the Welcome pane, choose “Save setup information in a file or directory record” and

click Continue.

3 Enter settings on 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.

So you can later edit the file, don’t select “Save in Encrypted Format.”

5 Choose a location to save the file and click Save.

Creating Customized Configuration Files from the Template File

After you create a template 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 servers.

The file uses XML format to encode the setup information. The name of an XML key reveals the setup parameter it contains.

The following example shows the basic structure and contents of a configuration file for a server with the following configuration:

• An administrative user named “Administrator” (short name “admin”) with a user ID of

501 and the password “secret”

• A computer name and host name of “server1.company.com”

• A single Ethernet network interface set to get its address from DHCP

• No server services set to start automatically

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict>

<key>AdminUser</key> <dict>

<key>exists</key> <false/> <key>name</key> <string>admin</string> <key>password</key> <string>secret</string> <key>realname</key> <string>Administrator</string> <key>uid</key>

<string>501</string> </dict> <key>ComputerName</key> <string>server1.company.com</string>

22 Chapter 2 Installing Server Software and Finishing Basic Setup

Page 23

<key>DSClientInfo</key>

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

network</string>

<key>DSClientType</key>

<key>DSType</key>

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

<key>DefaultFormat</key>

<key>DefaultScript</key>

<key>ResID</key>

<key>ResName</key>

<key>ScriptID</key>

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

<dict>

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

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

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

<key>DHCPClientID</key>

Chapter 2 Installing Server Software and Finishing Basic Setup 23

Page 24

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

</dict> </array> <key>NetworkTimeProtocol</key> <dict>

<key>UsingNTP</key>

<false/> </dict> <key>Rendezvous</key> <dict>

<key>RendezvousEnabled</key>

<true/>

<key>RendezvousName</key>

<string>beasbe3</string> </dict> <key>SerialNumber</key> <string>a-123-bcd-456-efg-789-hij-012-klm-345-n</string> <key>ServicesAutoStart</key> <dict>

<key>Apache</key>

<key>MacManager</key>

<key>Print</key>

<key>WebDAV</key>

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

</dict> </plist>

Note: The actual contents of a configuration file depend on the hardware configuration of the computer on which it’s created. This is one reason you should start from a template configuration file created on a computer similar to those you plan to set up.

24 Chapter 2 Installing Server Software and Finishing Basic Setup

Page 25

Naming Configuration Files

The Server Assistant recognizes configuration files with these names:

• MAC-address-of-server.plist

• IP-address-of-server.plist

• hardware-serial-number-of-server.plist

• full-host-name-of-server.plist

• generic.plist

The Server Assistant uses the file to set up the server with the matching address, name, or serial number. If the Server Assistant cannot find a file named for a particular server, it will use the file named generic.plist.

Storing a Configuration File in an Accessible Location

The Server Assistant looks for configuration files in the following locations:

/Volumes/vol/Auto Server Setup/

where vol is any device volume mounted in the /Volumes directory.

Devices you can use to provide configuration files include

• A partition on one of the server’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 directory

Changing Server Settings

After initial setup, you can use a variety of commands to view or change Mac OS X Server configuration settings.

For information on changing general system preferences, see Chapter 4, “Setting General System Preferences,” on page 31.

For information on changing network settings, see Chapter 5, “Network Preferences,” on page 37.

For information on changing service-specific settings, see the chapter that covers the service.

Chapter 2 Installing Server Software and Finishing Basic Setup 25

Page 26

Viewing, Validating, and Setting the Software Serial Number

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

To display the server’s software serial number:

$ serversetup -getSerialNumber

To set the server software serial number:

$ sudo serversetup -setSerialNumber serialnumber

Parameter Description

serialnumber

A valid Mac OS X Server software serial number, as found on the software packaging that comes with the software.

To validate a server software serial number:

$ serversetup -verifySerialNumber serialnumber

Displays 0 if the number is valid, 1 if it isn’t.

Updating Server Software

You can use the softwareupdate command to check for and install software updates over the web from Apple’s website.

To check for available updates:

$ softwareupdate --list

To install an update:

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

To view command help:

$ softwareupdate --help

26 Chapter 2 Installing Server Software and Finishing Basic Setup

Page 27

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 finalizing 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 directories 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 that other computers depend on.

• Wait to import final user accounts. Limit accounts to test accounts so you minimize

the user-specific network information (such as home directory 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 directories on the server. See “Changing a Server’s IP Address” on page 39. 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.

Chapter 2 Installing Server Software and Finishing Basic Setup 27

Page 28

Page 29

3 Restarting or Shutting Down a

Server

Commands you can use to shut down or restart a local or remote server.

Restarting a Server

You can use the reboot or shutdown -r command to restart a server at a specific time. For more information, see the man pages.

Examples

To restart the local server:

$ shutdown -r now

To restart a remote server immediately:

$ ssh -l root server shutdown -r now

To restart a remote server at a specific time:

$ ssh -l root server shutdown -r hhmm

Parameter Description

server hhmm

The IP address or DNS name of the server.

The hour and minute when the server restarts.

Automatic Restart

You can also use the systemsetup command to set up the server to start automatically after a power failure or system freeze. See “Viewing or Changing Automatic Restart Settings” on page 33.

Page 30

Changing a Remote Server’s Startup Disk

You can change a remote server’s startup disk using SSH.

To change the startup disk:

$ bless -folder "/Volumes/disk/System/Library/CoreServices" -setOF

Parameter Description

disk

The name of the disk that contains the desired startup volume.

For information on using SSH to log in to a remote server, see “Sending Commands to a Remote Server” on page 16.

Shutting Down a Server

You can use the shutdown command to shut down a server at a specific time. For more information, see the man page.

Examples

To shut down a remote server immediately:

$ ssh -l root server shutdown -h now

To shut down the local server in 30 minutes:

$ shutdown -h +30

Parameter Description

server

The IP address or DNS name of the server.

30 Chapter 3 Restarting or Shutting Down a Server

Page 31

4 Setting General System

Preferences

Commands you can use to set system preferences, usually set using the System Preferences GUI application.

Computer Name

You can use the systemsetup command to view or change a server’s 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.

Viewing or Changing the Computer Name

To display the server’s computer name:

$ sudo systemsetup -getcomputername

$ sudo networksetup -getcomputername

To change the computer name:

$ sudo systemsetup -setcomputername computername

$ sudo networksetup -setcomputername computername

Date and Time

You can use the systemsetup or serversetup command to view or change:

• A server’s system date or time

• A server’s time zone

• Whether a server uses a network time server

These settings would otherwise be changed using the Date & Time pane of System Preferences.

Page 32

Viewing or Changing the System Date

To view the current system date:

$ sudo systemsetup -getdate

$ serversetup -getDate

To set the current system date:

$ sudo systemsetup -setdate mm:dd:yy

$ sudo serversetup -setDate mm/dd/yy

Viewing or Changing the System Time

To view the current system time:

$ sudo systemsetup -gettime

$ serversetup -getTime

To change the current system time:

$ sudo systemsetup -settime hh:mm:ss

$ sudo serversetup -setTime hh:mm:ss

Viewing or Changing the System Time Zone

To view the current time zone:

$ sudo systemsetup -gettimezone

$ serversetup -getTimeZone

To view the available time zones:

$ sudo systemsetup -listtimezones

To change the system time zone:

$ sudo systemsetup -settimezone timezone

$ sudo serversetup -setTimeZone timezone

32 Chapter 4 Setting General System Preferences

Page 33

Viewing or Changing Network Time Server Usage

To see if a network time server is being used:

$ sudo systemsetup -getusingnetworktime

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

Energy Saver Settings

You can use the systemsetup command to view or change a server’s energy saver settings, which would otherwise be set 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

Chapter 4 Setting General System Preferences 33

Page 34

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.

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)

Power Management Settings

You can use the pmset command 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

For more information, see the pmset man page.

Startup Disk Settings

You can use the systemsetup command to view or change a server’s computer startup disk, which would otherwise be set using the Startup Disk pane of System Preferences.

Viewing or Changing the Startup Disk

To view the current startup disk:

$ sudo systemsetup -getstartupdisk

To view the available startup disks:

$ sudo systemsetup -liststartupdisks

To change the current startup disk:

$ sudo systemsetup -setstartupdisk path

34 Chapter 4 Setting General System Preferences

Page 35

Sharing Settings

You can use the systemsetup command to view or change settings that would otherwise be set using the Sharing pane of System Preferences.

Viewing or Changing Remote Login Settings

You can use SSH to log in to a remote server if remote login is enabled.

To see if the system is set to allow remote login:

$ sudo systemsetup -getremotelogin

To enable or disable remote login:

$ sudo systemsetup -setremotelogin (on|off)

$ serversetup -enableSSH

Telnet access is disabled by default because it isn’t as secure as SSH. You can, however, enable Telnet access. See “Using Telnet” on page 18.

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)

International Settings

You can use the serversetup command to view or change language settings that would otherwise be set using the Sharing pane of System Preferences.

Viewing or Changing Language Settings

To view the current primary language:

$ serversetup -getPrimaryLanguage

To view the installed primary language:

$ serversetup -getInstallLanguage

To change the install language:

$ sudo serversetup -setInstallLanguage language

To view the script setting:

$ serversetup -getPrimaryScriptCode

Chapter 4 Setting General System Preferences 35

Page 36

Login Settings

Disabling the Restart and Shutdown Buttons

To disable or enable the Restart and Shutdown buttons in the login dialog:

$ sudo serversetup -setDisableRestartShutdown (0|1)

0 disables the buttons.

1 enables the buttons.

To view the current setting:

$ serversetup -getDisableRestartShutdown

36 Chapter 4 Setting General System Preferences

Page 37

5 Network Preferences

Commands you can use to change a server’s network settings.

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 “Network Port Configurations” on page 38.

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.

Page 38

Viewing or Changing MTU Values

You can use these commands to change the maximum transmission unit (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")

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] [...]

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

38 Chapter 5 Network Preferences

Page 39

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.

To change the order of the port configurations:

$ sudo networksetup -ordernetworkservices config1 config2 [config3] [...]

TCP/IP Settings

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

To change a server’s IP address:

1 Run the changeip tool:

$ changeip [(directory|-)] old-ip new-ip [old-hostname new-hostname]

changeip command.

Parameter Description

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

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

Important: Changing a server’s IP address isn’t as simple as changing the TCP/IP

settings. You must first run the changeip utility to make sure necessary changes are made throughout the system. See “Changing a Server’s IP Address” on page 39.

To list TCP/IP settings for a configuration:

$ sudo networksetup -getinfo "configuration"

Example:

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

40 Chapter 5 Network Preferences

Page 41

Viewing or Changing DNS Servers

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 5 Network Preferences 41

Page 42

Enabling TCP/IP

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.

AppleTalk Settings

Enabling and Disabling 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

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

42 Chapter 5 Network Preferences

Page 43

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)

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 5 Network Preferences 43

Page 44

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

[...]

AirPort Settings

Viewing or Changing 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]

Computer, Host, and Rendezvous Name

Viewing or Changing the Computer Name

To display the server’s computer name:

$ sudo systemsetup -getcomputername

$ sudo networksetup -getcomputername

$ serversetup -getComputername

44 Chapter 5 Network Preferences

Page 45

To change the computer name:

$ sudo systemsetup -setcomputername computername

$ sudo networksetup -setcomputername computername

$ sudo serversetup -setComputername computername

To validate a computer name:

$ serversetup -verifyComputername computername

Viewing or Changing the Local Host Name

To display the server’s local host name:

$ serversetup -getHostname

To change the server’s local host name:

$ sudo serversetup -setHostname hostname

Viewing or Changing the Rendezvous Name

To display the server’s Rendezvous name:

$ serversetup -getRendezvousname

To change the server’s Rendezvous name:

$ sudo serversetup -setRendezvousname rendezvousname

The command displays a 0 if the name was changed.

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

Chapter 5 Network Preferences 45

Page 46

Page 47

6 Working With Disks and Volumes

Commands you can use to prepare, use, and test disks and volumes.

Mounting and Unmounting Volumes

You can use the mount_afp command to mount an AFP volume. For more information, type man mount_afp to see the man page.

Mounting Volumes

You can use the mount command 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) volumes

• mount_udf for Universal Disk Format (UDF) volumes

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

volumes

For more information, see the related man pages.

Unmounting Volumes

You can use the umount command to unmount a volume. For more information, see the man page.

Checking for Disk Problems

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

Page 48

Monitoring Disk Space

When you need more vigilant monitoring of disk space than the log rolling scripts provide, you can use the diskspacemonitor command-line 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. You can enable it by opening a Terminal

window and typing sudo diskspacemonitor on. You may be prompted for your password. Type man diskspacemonitor for more information about the commandline options.

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 thresholds to use for determining when to take the actions in the scripts. By default, disks are checked every 10 minutes, an alert script executed when disks are 75% full, and a recovery script 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 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 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, you can. 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 server using SSH.

48 Chapter 6 Working With Disks and Volumes

Page 49

Reclaiming Disk Space Using Log Rolling Scripts

Three predefined scripts are executed automatically 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

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:

• 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. Refer to 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 command-line tool to reclaim disk space.

Chapter 6 Working With Disks and Volumes 49

Page 50

Managing Disk Journaling

Checking to See if Journaling is Enabled

You can use the mount command to see if journaling is enable 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)

Turning on Journaling for an Existing Volume

You can use the diskutil command 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 command

before you turn on journaling.

To enable journaling:

$ diskutil enableJournal volume

Parameter Description

volume

The volume name or device name of the volume.

Example

$ 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 /dev/disk0s9 on / (local, journaled) /dev/disk0s10 on /Volumes/OS 9.2.2 (local, journaled)

50 Chapter 6 Working With Disks and Volumes

Page 51

Enabling Journaling When You Erase a Disk

You can use the newfs_hfs command 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 device

The name you want the new disk volume to have.

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.

Erasing, Partitioning, and Formatting Disks

You can use the diskutil command to partition, erase, or format a disk. For more information, see the man page.

Setting Up a Case-Sensitive HFS+ File System

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.

To format a Mac OS Extended volume as case-sensitive HFS+:

$ sudo diskutil eraseVolume "Case-sensitive HFS+" newvolname volume

Parameter Description

newvolname volume

For more information, see the man page for diskutil.

The name given to the reformatted, case-sensitive volume.

The path to the existing volume to be reformatted. For example, /Volumes/HFSPlus

Chapter 6 Working With Disks and Volumes 51

Page 52

Imaging and Cloning Volumes Using ASR

You can use Apple Software Restore (ASR) to copy a disk image onto a volume or 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 utility doesn’t create the disk images. You can use hdiutil to create disk images from volumes or folders.

You must run ASR as the root user or with sudo root permissions. You cannot use ASR on read/write disk images.

To image a boot volume:

1 Install and configure Mac OS X on the volume as you want it.

2 Restart from a different volume.

3 Make sure the volume you’re imaging has permissions enabled. 4 Use hditutil to make a read-write disk image of the volume.

5 Mount the disk image.

6 Remove cache files, host-specific preferences, and virtual memory files. You can find

example files to remove on the asr man page.

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

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.

52 Chapter 6 Working With Disks and Volumes

Page 53

7 Working With Users and Groups

Commands you can use to set up and manage users and groups in Mac OS X Server.

Creating Server Administrator Users

You can use the serversetup command to create administrator users for a server. To create regular users, see “Importing Users and Groups” on page 54.

To create a user:

$ serversetup -createUser fullname shortname password

The name, short name, and password must be typed in the order shown. If the full name includes spaces, type it in quotes.

The command displays a 1 if the full name or short name is already in use.

To create a user with a specific UID:

$ serversetup -createUserWithID fullname shortname password userid

The name, short name, password, and UID must be typed in the order shown. If the full name includes spaces, type it in quotes.

The command displays a 1 if the full name, short name, or UID is already in use or if the UID you specified is less than 100.

To create a user with a specific UID and home directory:

$ serversetup -createUserWithIDIP fullname shortname password userid

homedirpath

The name, short name, password, and UID must be typed in the order shown. If the full name includes spaces, type it in quotes.

The command displays a 1 if the full name, short name, or UID is already in use or if the UID you specified is less than 100.

Page 54

Importing Users and Groups

You can use the dsimportexport command to import user and group accounts.

Note: Despite its name, dsimportexport can’t be used to export user records.

The utility is in /Applications/Server/Workgroup Manager.app/Contents/Resources.

For information on the formats of the files you can import, see “Creating a CharacterDelimited User Import File” on page 55.

$ dsimportexport (-g|-s|-p) file directory user password (O|M|I|A) [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 version6.x file directory

user password O|M|I|A Specifies how user data is handled if a record for an imported user

options Additional command options. To see available options, execute the

The path of the file to import.

The path to the Open Directory node where the records will be added.

The name of the directory administrator.

The password of the directory administrator.

already exists in the directory:

O: Overwrite the matching record. M: Merge the records. Empty attributes in the directory assume

values from the imported record.

I: Ignore imported record and leave existing record unchanged. A: Append data from import record to existing record.

dsimportexport 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 55.

Open Directory supports up to 100,000 records. For local NetInfo databases, make sure the file contains no more than 10,000 records.

2 Log in as the administrator of the directory domain into which you want to import

accounts.

54 Chapter 7 Working With Users and Groups

Page 55

3 Open the Terminal application and type the dsimportexport command. The tool is

located in /Applications/Utilities/Workgroup Manager.app/Contents/Resources.

To include the space in the path name, precede it with a backslash (\). For example:

/Applications/Utilities/Workgroup\ Manager.app/Contents/Resources

/dsimportexport -h

4 If you want, use the createhomedir tool to create home directories for imported users.

See “Creating a User’s Home Directory” on page 63.

Creating a Character-Delimited User Import File

You can 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

• 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)

Chapter 7 Working With Users and Groups 55

Page 56

In addition, you can include

• UserShell (the default shell)

• NFSHomeDirectory (the path to the user’s home directory on the user’s computer)

• Other user data types, described under “User Attributes” on page 57

For group accounts, the list of attributes must include

• RecordName (the group name)

• PrimaryGroupID (the group ID)

• GroupMembership

Here is an example of a record description:

0x0A 0x5C 0x3A 0x2C DSRecTypeStandard:Users 7 RecordName Password UniqueID PrimaryGroupID RealName NFSHomeDirectory UserShell

Here is an example of a record encoded using the above description:

jim:Adl47E$:408:20:J. Smith, Jr.,

M.D.:/Network/Servers/somemac/Homes/jim:/bin/csh

The record consists of values, delimited by colons. Use a double colon (::) to indicate a value is missing.

Here 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:: 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.

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

56 Chapter 7 Working With Users and Groups

Page 57

An example user account looks like this:

jim:Adl47E$:408:20:J. Smith, Jr.,

M.D.:/Network/Servers/somemac/Homes/jim:/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

Here is an example of a record encoded using the description:

students:Ad147:88:jones,alonso,smith,wong

User Attributes

The following table lists standard XML data structures for attributes in user records.

Attribute Format Sample values

RecordName:

A list of names associated with a user; the first is the user’s short name, which is also the name of the user’s home directory

Important: All attributes used for authentication must map to RecordName.

RealName:

A single name, usually the user’s full name; not used for authentication

UniqueID:

A unique user identifier, used for access privilege management

PrimaryGroupID: A user’s primary group

association

NFSHomeDirectory:

Local file system path to the user’s home directory

First value: ASCII characters A–Z, a–z, 0–9, _,-

Second value: UTF-8 Roman text

UTF-8 text David L. MacSmith, Jr.

Signed 32-bit ASCII string of digits 0–9

Unsigned 32-bit ASCII string of digits 0–9

UTF-8 text /Network/Servers/example/Users/

Dave David Mac DMacSmith

Non-zero length, 1 to 16 values. Maximum 255 bytes (85 triple-byte to 255 single-byte characters) per instance. First value must be 1 to 30 bytes for clients using Macintosh Manager, or 1 to 8 bytes for clients using Mac OS X version 10.1 and earlier.

Non-zero length, maximum 255 bytes (85 triple-byte to 255 single-byte characters).

Range is 100 to 2,147,483,648. Values below 100 are typically used for system

accounts. Zero is reserved for use by the system. Normally unique among entire population of users, but sometimes can be duplicated.

Warning: A non-integer value is interpreted as 0, which is the UniqueID of the root user.

Range is 1 to 2,147,483,648. Normally unique among entire population of group

records. If blank, 20 is assumed.

K-M/Tom King

Non-zero length. Maximum 255 bytes.

Chapter 7 Working With Users and Groups 57

Page 58

Attribute Format Sample values

HomeDirectory:

The location of an AFP-based home directory

HomeDirectoryQuota:

The disk quota for the user’s home directory

MailAttribute:

A user’s mail service configuration (refer to “Mail Attributes in User Records” on page 60 for information on individual fields in this structure)

PrintServiceUserData

A user’s print quota statistics

Structured UTF-8 text

Text for the number of bytes allowed

Structured text

UTF-8 XML plist, single value

<home_dir> <url> afp://server/sharepoint </url> <path> usershomedirectory </path> </home_dir>

In the following example, Tom King’s home directory is K-M/Tom King, which resides beneath the share point directory, Users:

<home_dir> <url> afp://example.com/Users </url> <path> K-M/Tom King </path> </home_dir>

If the quota is 10MB, the value will be the text string

1048576.

<dict> <key>kAttributeVersion</key> <string>Apple Mail 1.0</string> <key>kAutoForwardValue</key> <string>user@example.com</string> <key>kIMAPLoginState</key> <string>IMAPAllowed</string> <key>kMailAccountLocation</key> <string>domain.example.com</string> <key>kMailAccountState</key> <string>Enabled</string> <key>kNotificationState</key> <string>NotificationStaticIP</string> <key>kNotificationStaticIPValue</key> <string>[1.2.3.4]</string> <key>kPOP3LoginState</key> <string>POP3Allowed</string> <key>kSeparateInboxState</key> <string>OneInbox</string> <key>kShowPOP3InboxInIMAP</key> <string>HidePOP3Inbox</string> </dict>

58 Chapter 7 Working With Users and Groups

Page 59

Attribute Format Sample values

MCXFlags:

If present, MCXSettings is loaded; if absent, MCXSettings isn’t loaded; required for a managed user.

MCXSettings: A user’s managed

preferences

AdminLimits

The privileges allowed by Workgroup Manager to a user that can administer the directory domain

Password: The user’s password

Picture: File path to a recognized

graphic file to be used as a display picture for the user

Comment: Any documentation you like

UserShell: The location of the default

shell for command-line interactions with the server

Authentication Authority:

Describes the user’s authentication methods, such as Open Directory or crypt password; not required for a user with only a crypt password; absence of this attribute signifies legacy authentication (crypt with Authentication Manager, if it’s available).

AuthenticationHint: Text set by the user to be

displayed as a password reminder

UTF-8 XML plist, single value

UNIX crypt

UTF-8 text Maximum 32,676 bytes.

UTF-8 text John is in charge of product

marketing.

Path name /bin/tcsh

/bin/sh

None (this value prevents users with accounts in the directory domain from accessing the server remotely via a command line)

Non-zero length.

ASCII text Values describe the user’s authentication methods.

Can be multivalued (for example, basic and ShadowHash).

Each value has the format vers; tag; data (where vers and data may be blank).

Crypt password: ;basic; Open Directory

authentication: ;ApplePasswordServer; HexID, server’s public key IPaddress:port

Shadow password (local directory domain only): ;ShadowHash;

UTF-8 text Your guess is as good as mine.

Maximum 255 bytes.

Chapter 7 Working With Users and Groups 59

Page 60

Mail Attributes in User Records

The following table lists the standard XML data structures for a user mail attribute, part of a standard user record.

MailAttribute field Description Sample values

AttributeVersion A required case-insensitive value that

must be set to AppleMail 1.0.

MailAccountState A required case-insensitive keyword

describing the state of the user’s mail. It must be set to one of these values: Off, Enabled, or Forward.

POP3LoginState A required case-insensitive keyword

indicating whether the user is allowed to access mail via POP. It must be set to one of these values:

POP3Allowed or POP3Deny.

IMAPLoginState A required case-insensitive keyword

indicating whether the user is allowed to access mail using IMAP. It must be set to one of these values:

IMAPAllowed or IMAPDeny.

MailAccountLocation A required value indicating the

domain name or IP address of the ProductName responsible for storing the user’s mail.

AutoForwardValue A required field only if

MailAccountState has the value Forward. The value must be a valid RFC 822 email address.

<key> kAttributeVersion </key> <string> AppleMail 1.0 </string>

<key> kMailAccountState </key> <string> Enabled </string>

<key> kPOP3LoginState </key> <string> POP3Deny </string>

<key> kIMAPLoginState </key> <string> IMAPAllowed </string>

<key> kMailAccountLocation </key> <string> domain.example.com </string>

<key> kAutoForwardValue </key> <string> user@example.com </string>

60 Chapter 7 Working With Users and Groups

Page 61

MailAttribute field Description Sample values

NotificationState An optional keyword describing

whether to notify the user whenever new mail arrives. If provided, it must be set to one of these values: NotificationOff,

NotificationLastIP, or NotificationStaticIP.

If this field is missing,

NotificationOff is assumed.

NotificationStaticIP Value

SeparateInboxState An optional case-insensitive keyword

ShowPOP3InboxInIMAP An optional case-insensitive keyword

An optional IP address, in bracketed, dotted decimal format ([xxx.xxx.xxx.xxx]).

If this field is missing, NotificationState is interpreted as NotificationLastIP. The field is used only when NotificationState has the value NotificationStaticIP.

indicating whether the user manages POP and IMAP mail using different inboxes. If provided, it must be set to one of these values: OneInbox or DualInbox.

If this value is missing, the value OneInbox is assumed.

indicating whether POP messages are displayed in the user’s IMAP folder list. If provided, it must be set to one of these values: ShowPOP3Inbox or HidePOP3Inbox.

If this field is missing, the value

ShowPOP3Inbox is assumed.

<key> kNotificationState </key> <string> NotificationOff </string>

<key> kNotificationStatic IPValue </key> <string> [1.2.3.4] </string>

<key> kSeparateInboxState </key> <string> OneInbox </string>

<key> kShowPOP3InboxInIMAP </key> <string> HidePOP3Inbox </string>

Chapter 7 Working With Users and Groups 61

Page 62

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.

Note: These tasks only apply to the local directory on the server.

To see if a full name is already in use:

$ serversetup -verifyRealName "longname"

The command displays a 1 if the name is already in the directory, 0 if it isn’t.

To see if a short name is already in use:

$ serversetup -verifyName shortname

The command displays a 1 if the name is already in the directory, 0 if it isn’t.

To see if a UID is already in use:

$ serversetup -verifyUID userid

The command displays a 1 if the UID is already in the directory, 0 if it isn’t.

To test a user’s password:

$ serversetup -verifyNamePassword shortname password

The command displays a 1 if the password is good, 0 if it isn’t.

To view the names associated with a UID:

$ serversetup -getNamesByID userid

No response means UID not valid.

To generate the default UNIX short name for a user long name:

$ serversetup -getUNIXName "longname"

62 Chapter 7 Working With Users and Groups

Page 63

Creating a User’s Home Directory

Normally, you can create a user's home directory by clicking the Create Home Now button on the Homes pane of Workgroup Manager. You can also create home directory folders using the createhomedir tool. Otherwise, Mac OS X Server creates the user’s home directory when the user logs in for the first time.

You can use createhomedir to create

• A home directory for a particular user (-u option)

• Home directories for all users in a directory domain (-n or -l option)

• Home directories for all users in all domains in the directory search path (-a option)

For more information, type man createhomedir to view the man page.

In all cases, the home directories are created on the server where you run the tool.

To create a home directory for a particular user:

$ createhomedir [(-a|-l|-n domain)] -u userid

To create a home directory for users in the local domain:

$ createhomedir -l

To create a home directory for users in the local domain:

$ createhomedir [(-a|-l|-n domain)] -u userid

You can also create a user’s home directory using the serversetup tool.

To create a home directory for a particular user:

$ serversetup -createHomedir userid

The command displays a 1 if the user ID you specify doesn’t exist.

Mounting a User’s Home Directory

You can use the mnthome command to mount a user’s home directory. For more information, see the man page.

Creating a Group Folder

You can use the CreateGroupFolder command to set up group folders. For more information see the man page.

Checking a User’s Administrator Privileges

To see if a user is a server administrator:

$ serversetup -isAdministrator shortname

The command displays a 0 if the user has administrator privileges, 0 if the user doesn’t.

Chapter 7 Working With Users and Groups 63

Page 64

Page 65

8 Working With File Services

Commands you can use to create share points and manage AFP, NFS, Windows (SMB), and FTP services in Mac OS X Server.

Share Points

You can use the sharing tool to list, create, and modify share points.

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: Share1 path: /Volumes/100GB afp: { name: Share1 shared: 1 guest access: 0 inherit perms: 0 } ftp: { name: Share1 shared: 1 guest access: 1 } smb: { name: Share1 shared: 1 guest access: 1 inherit perms: 0 oplocks: 0 strict locking: 0 directory mask: 493 create mask: 420 }

Page 66

Creating a Share Point

To create a share point:

$ sharing -a path [-n customname] [-A afpname] [-F ftpname]

[-S smbname [-c creationmask [-t strictlockingflag

Parameter Description

path customname

afpname

ftpname smbname shareflags

guestflags

inheritflags

creationmask directorymask oplockflag

strictlockingflag

] [-s shareflags] [-g guestflags] [-i inheritflags]

] [-d directorymask] [-o oplockflag]

]

The full path to the directory you want to share.

The name of the share point. If you don’t specify this custom name, it’s set to the name of the directory, the last name in path

The share point name shown to and used by AFP clients. This name is separate from the share point name.

The share point name shown to and used by FTP clients.

The share point name shown to and used by SMB clients.

A three-digit binary number indicating which protocols are used to share the directory. The digits represent, from left to right, AFP, FTP, and SMB. 1=shared, 0=not shared.

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. 1=guests allowed, 0=guests not allowed.

A group of two flags indicating whether new items in AFP or SMB 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. 1=inherit, 0=don’t inherit.

The SMB creation mask. Default=0644. The SMB directory mask. Default=0755.

Specifies whether opportunistic locking is allowed for an SMB share point. 1=enable oplocks, 0=disable oplocks. For more information on oplocks, see the file services administration guide.

Specifies whether strict locking is used on an SMB share point. 1=enable strict locking, 0=disable. For more information on strict locking, see the file services administration guide.

Examples

$ sharing -a /Volumes/100GB/Art

Creates a share point named Art, shared using AFP, FTP, and SMB, and using the name Art for all three types of clients.

$ sharing -a /Volumes/100GB/Windows\ Docs -n WinDocs -S Documents -s

001 -o 1

66 Chapter 8 Working With File Services

Page 67

Shares the directory named Windows Docs on the disk 100GB. The share point is named WinDocs for server management purposes, but SMB users see it as Documents. It’s shared using only the SMB protocol with oplocks enabled.

Modifying a Share Point

To change share point settings:

$ sharing -e sharepointname [-n customname] [-A afpname] [-F ftpname]

[-S smbname [-c creationmask [-t strictlockingflag

Parameter Description

sharepointname

Other parameters See the parameter descriptions under “Creating a Share Point” on

] [-s shareflags] [-g guestflags] [-i inheritflags]

] [-d directorymask] [-o oplockflag]

]

The current name of the share point.

page 66.

Disabling a Share Point

To disable a share point:

$ sharing -r sharepointname

Parameter Description

sharepointname

The current name of the share point.

AFP Service

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

Chapter 8 Working With File Services 67

Page 68

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, type

serveradmin settings afp

or see “List of AFP Settings” on this page.

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

Changing AFP Settings

You can change AFP service settings using the serveradmin command.

To change a setting:

$ sudo serveradmin settings afp:setting = value

Parameter Description

setting

value

An AFP service setting. To see a list of available settings, type

$ sudo serveradmin settings afp

or see “List of AFP Settings” on this page.

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 afp:setting = value afp:setting = value [...] Control-D

= value

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.

activityLogPath Location of the activity log file.

68 Chapter 8 Working With File Services

Default = no

Default = /Library/Logs/AppleFileService/

AppleFileServiceAccess.log

Page 69

Parameter (afp:) Description

activityLogSize Rollover size (in kilobytes) for the activity log. Only used if

activityLogTime isn’t specified. Default = 1000

activityLogTime Rollover time (in days) for the activity log.

Default = 7

admin31GetsSp Set to true to force administrative users on Mac OS X to see

share points instead of all volumes. Default = yes

adminGetsSp Set to true to force administrative 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

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

Default = yes

errorLogPath The location of the error log.

Default = /Library/Logs/AppleFileService/

AppleFileServiceError.log

errorLogSize Rollover size (in kilobytes) for the error log. Only used if

errorLogTime isn’t specified. Default = 1000

errorLogTime Rollover time (in days) for the error log.

Default = 0

Chapter 8 Working With File Services 69

Page 70

Parameter (afp:) Description

guestAccess Allow guest users access to the server.

Default = yes

idleDisconnectFlag: adminUsers

idleDisconnectFlag: guestUsers

idleDisconnectFlag: registeredUsers

idleDisconnectFlag: usersWithOpenFiles

idleDisconnectMsg The idle disconnect message.

idleDisconnectOnOff Enable idle disconnect.

idleDisconnectTime Idle time (in minutes) allowed before disconnect.

kerberosPrincipal Kerberos server principal name.

loggingAttributes: logCreateDir

loggingAttributes: logCreateFile

loggingAttributes: logDelete

loggingAttributes: logLogin

loggingAttributes: logLogout

loggingAttributes: logOpenFork

loginGreeting The login greeting message.

loginGreetingTime The last time the login greeting was set or updated. maxConnections Maximum number of simultaneous user sessions allowed by

maxGuests Maximum number of simultaneous guest users allowed.

Enforce idle disconnect for administrative users. Default = yes

Enforce idle disconnect for guest users. Default = yes

Enforce idle disconnect for registered users. Default = yes

Enforce idle disconnect for users with open files. Default = yes

Default = ""

Default = no

Default = 10

Default = "afpserver"

Record directory creations in the activity log. Default = yes

Record file creations in the activity log. Default = yes

Record file deletions in the activity log. Default = yes

Record user logins in the activity log. Default = yes

Log user logouts in the activity log. Default = yes

Log file opens in the activity log. Default = yes

Default = ""

the server. Default = -1 (unlimited)

Default = -1 (unlimited)

70 Chapter 8 Working With File Services

Page 71

Parameter (afp:) Description

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

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

Default = yes

sendGreetingOnce Send the login greeting only once.

Default = no

shutdownThreshold Don’t modify. Internal use only. specialAdminPrivs Grant administrative users super 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 users volume.

Default = yes

Chapter 8 Working With File Services 71

Page 72

Parameter (afp:) Description

useAppleTalk Don’t modify. Internal use only. useHomeDirs Default = no

List of AFP serveradmin Commands

In addition to the standard start, stop, status, and settings commands, you can use serveradmin to issue the following service-specific AFP commands.

Command (afp:command=) Description

cancelDisconnect Cancel a pending user disconnect. See “Canceling a User

Disconnect” on page 74.

disconnectUsers Disconnect AFP users. See “Disconnecting AFP Users” on page 73. 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 75.

getLogPaths Display the locations of the AFP service activity and error logs. sendMessage Send a text message to connected AFP users. See “Sending a

Message to AFP Users” on page 73.

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 “Determining Whether a Service Needs to be Restarted” on page 19.

Listing Connected Users

You can use the serveradmin getConnectedUsers command 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:

$serveradmin command afp:command = getConnectedUsers

Output

The following array of settings is displayed for each connected user:

afp:usersArray:_array_index:i:disconnectID = <disconnectID> afp:usersArray:_array_index:i:flags = <flags> afp:usersArray:_array_index:i:ipAddress = <ipAddress> afp:usersArray:_array_index:i:lastUseElapsedTime = <lastUseElapsed> afp:usersArray:_array_index:i:loginElapsedTime = <loginElapsedTime> afp:usersArray:_array_index:i:minsToDisconnect = <minsToDisconnect> afp:usersArray:_array_index:i:name = <name> afp:usersArray:_array_index:i:serviceType = <serviceType> afp:usersArray:_array_index:i:sessionID = <sessionID> afp:usersArray:_array_index:i:sessionType = <sessionType> afp:usersArray:_array_index:i:state = <state>

72 Chapter 8 Working With File Services

Page 73

Sending a Message to AFP Users

You can use the serveradmin sendMessage command 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 sessionid

n The session ID of a user you want to receive the message. To list the

The message that appears on client computers.

session IDs of connected users, use the getConnectedUsers command. See “Listing Connected Users” on page 72.

Disconnecting AFP Users

You can use the serveradmin disconnectUsers command 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

Parameter Description

message-text

minutes-until

sessionid

Chapter 8 Working With File Services 73

n The session ID of a user you want to disconnect. To list the session

The text of a message that appears on client computers in the disconnect announcement dialog.

The number of minutes between the time the command is issued and the users are disconnected.

IDs of connected users, use the getConnectedUsers command. See “Listing Connected Users” on page 72.

Page 74

Output

afp:command = "disconnectUsers" afp:messageSent = "<message>" afp:timeStamp = "< afp:timerID = <disconnectID> <user listing> afp:status

Value Description

<message> The message sent to users in the disconnect announcement dialog. <time> The time when the command was issued. <disconnectID> An integer that identifies this particular disconnect. You can use

<user listing> A standard array of user settings for each user scheduled for

<status> A command status code:

= <status>

time>"

this ID with the cancelDisconnect command to cancel the disconnect.

disconnect. For a description of these settings, see “Listing Connected Users” on page 72.

0 = command successful

Canceling a User Disconnect

You can use the serveradmin cancelDisconnect command to cancel a

disconnectUsers command. Users receive an announcement that they’re no longer

scheduled to be disconnected.

To cancel a disconnect:

$ sudo serveradmin command afp:command = cancelDisconnect afp:timerID = timerID Control-D

Parameter Description

timerID

The integer value of the afp:timerID parameter output when you issued the disconnectUsers command.

You can also find this number by listing any user scheduled to be disconnected and looking at the value of the disconnectID setting for the user.

Output

afp:command = "cancelDisconnect" afp:timeStamp = "< afp:status

Value Description

<time> The time at which the command was issued. <status> A command status code:

74 Chapter 8 Working With File Services

= <status>

time>"

0 = command successful

Page 75

Listing AFP Service Statistics

You can use the serveradmin getHistory command to display a log of periodic samples of the number of connections and the data throughput. Samples are taken once each minute.

To list samples:

$ sudo serveradmin command afp:command = getHistory afp:variant = statistic afp:timeScale = scale Control-D

Parameter Description

statistic

scale

Output

afp:nbSamples = <samples> afp:samplesArray:_array_index:0:v afp:samplesArray:_array_index:0:t = <time> afp:samplesArray:_array_index:1:v afp:samplesArray:_array_index:1:t = <time> [...] afp:samplesArray:_array_index: afp:samplesArray:_array_index:

Legend = "<legend>"

afp:v afp:currentServerTime = <servertime>

The value you want to display. Valid values:

v1 - number of connected users (average during sampling period) v2 - throughput (bytes/sec)

The length of time in seconds, ending with the current time, for which you want to see samples. For example, to see 30 minutes of data, you would specify afp:timeScale = 1800.

= <sample>

i:vn

= <sample>

:t = <time>

Value displayed by getHistory Description

<samples> The total number of samples listed. <legend> A textual description of the selected statistic.

"CONNECTIONS" for v1 "THROUGHPUT" for v2

<sample> The numerical value of the sample.

For connections (v1), this is integer average number of users. For throughput, (v2), this is integer bytes per second.

<time> The time at which the sample was measured. A standard UNIX time

(number of seconds since Sep 1, 1970.) Samples are taken every 60 seconds.

Chapter 8 Working With File Services 75

Page 76

Viewing AFP Log Files

You can use tail or any other file listing tool to view the contents of the AFP service logs.

To view the latest entries in a log:

$ tail log-file

You can use the serveradmin getLogPaths command to see where the current AFP error and activity logs are located.

To display the log paths:

$ sudo serveradmin command afp:command = getLogPaths

Output

afp:accesslog = <access-log> afp:errorlog = <error-log>

Value Description

<access-log> The location of the AFP service access log. Default =

/Library/Logs/AppleFileService/ AppleFileServiceAccess.log

<error-log> The location of the AFP service error log. Default =

/Library/Logs/AppleFileService/ AppleFileServiceError.log

NFS Service

Starting and Stopping NFS Service

NFS service is started automatically when a share point is exported using NFS. The NFS daemons that satisfy client requests continue to run until there are no more NFS exports and the server is restarted.

Checking NFS Service Status

To see if NFS service and related processes are running:

$ sudo serveradmin status nfs

To see complete NFS status:

$ sudo serveradmin fullstatus nfs

Viewing NFS Settings

To list all NFS service settings:

$ sudo serveradmin settings nfs

To list a particular setting:

$ sudo serveradmin settings nfs:setting

76 Chapter 8 Working With File Services

Page 77

Changing NFS Service Settings

Use the following parameters with the serveradmin command to change settings for the NFS service.

Parameter (nfs:) Description

nbDaemons Default = 6

To reduce the number of daemons, you must restart the server after changing this value.

useTCP Default = yes

You must restart the server after changing this value.

useUDP Default = yes

You must restart the server after changing this value.

FTP Service

Starting FTP Service

To start FTP service:

$ sudo serveradmin start ftp

Stopping FTP Service

To stop FTP service:

$ sudo serveradmin stop ftp

Checking FTP Service Status

To see if FTP service is running:

$ sudo serveradmin status ftp

To see complete FTP status:

$ sudo serveradmin fullstatus ftp

Viewing FTP Settings

To list all FTP service settings:

$ sudo serveradmin settings ftp

To list a particular setting:

$ sudo serveradmin settings ftp:setting

To list a group of settings:

$ sudo serveradmin settings ftp:logCommands:*

Chapter 8 Working With File Services 77

Page 78

Changing FTP Settings

You can change FTP service settings using the serveradmin application.

To change a setting:

$ sudo serveradmin settings ftp:setting = value

Parameter Description

setting

value

An FTP service setting. To see a list of available settings, type

$ sudo serveradmin settings ftp

or see “FTP Settings” on this page.

An appropriate value for the setting.

To change several settings:

$ sudo serveradmin settings ftp:setting ftp:setting = value ftp:setting = value [...] Control-D

= value

FTP Settings

Use the following parameters with the serveradmin command to change settings for the FTP service.

Parameter (ftp:)

administratorEmailAddress Default = "user@hostname" anonymous-root Default = "/Library/FTPServer/FTPRoot" anonymousAccessPermitted Default = no authLevel Default = "STANDARD" bannerMessage Default = "This is the "Banner"

message for the Mac OS X Server's FTP server process.

FTP clients will receive this message immediately before being prompted for a name and password.

PLEASE NOTE: Some FTP clients may exhibit problems if you make this file too long.

----------------------------------" chrootType Default = "STANDARD" enableMacBinAndDmgAutoConversion Default = yes ftpRoot Default = "/Library/FTPServer/FTPRoot"

78 Chapter 8 Working With File Services

Page 79

Parameter (ftp:)

logCommands:anonymous Default = no logCommands:guest Default = no logCommands:real Default = no loginFailuresPermitted Default = 3 logSecurity:anonymous Default = no logSecurity:guest Default = no logSecurity:real Default = no logToSyslog Default = no logTransfers:anonymous:inbound Default = yes logTransfers:anonymous:outbound Default = yes logTransfers:guest:inbound Default = no logTransfers:guest:outbound Default = no logTransfers:real:inbound Default = yes logTransfers:real:outbound Default = yes maxAnonymousUsers Default = 50 maxRealUsers Default = 50 showBannerMessage Default = yes showWelcomeMessage Default = yes welcomeMessage Default = "This is the "Welcome"

message for the Mac OS X Server's FTP server process.

FTP clients will receive this message right after a successful log in.

----------------------------------"

List of FTP serveradmin Commands

You can use the following commands with the serveradmin application to manage FTP service.

ftp:command= Description

getConnectedUsers List connected users. See “Checking for Connected FTP Users” on

page 80.

Chapter 8 Working With File Services 79

Page 80

ftp:command= Description

getLogPaths Show location of the FTP transfer log file. See “Viewing the FTP

Transfer Log” on this page.

writeSettings Equivalent to the standard serveradmin settings command,

but also returns a setting indicating whether the service needs to be restarted. See “Determining Whether a Service Needs to be Restarted” on page 19.

Viewing the FTP Transfer Log

You can use tail or any other file listing tool to view the contents of the FTP transfer log.

To view the latest entries in the transfer log:

$ tail log-file

The default location of log-file is /Library/Logs/FTP.transger.log. You can use the

serveradmin getLogPaths command to see where the current transfer log is located.

To display the log path:

$ sudo serveradmin command ftp:command = getLogPaths

Checking for Connected FTP Users

To see how many FTP users are connected:

$ ftpcount

$ sudo serveradmin command ftp:command = getConnectedUsers

Windows (SMB) Service

Starting and Stopping SMB Service

To start SMB service:

$ sudo serveradmin start smb

To stop SMB service:

$ sudo serveradmin stop smb

Checking SMB Service Status

To see if SMB service is running:

$ sudo serveradmin status smb

To see complete SMB status:

$ sudo serveradmin fullstatus smb

80 Chapter 8 Working With File Services

Page 81

Viewing SMB Settings

To list all SMB service settings:

$ sudo serveradmin settings smb

To list a particular setting:

$ sudo serveradmin settings smb:setting

Parameter Description

setting

An SMB service setting. To see a list of available settings, type

$ sudo serveradmin settings smb

or see “List of SMB Service Settings” on page 82.

To list a group of settings:

$ sudo serveradmin settings smb:adminCommands:*

Changing SMB Settings

You can change SMB service settings using the serveradmin command.

To change a setting:

$ sudo serveradmin settings smb:setting = value

Parameter Description

setting

value

An SMB service setting. To see a list of available settings, type

$ sudo serveradmin settings smb

or see “List of SMB Service Settings” on page 82.

An appropriate value for the setting. For a list of values that correspond to GUI controls in the Server Admin application, see “List of SMB Service Settings” on page 82.

To change several settings:

$ sudo serveradmin settings smb:setting smb:setting = value smb:setting = value [...] Control-D

= value

Chapter 8 Working With File Services 81

Page 82

List of SMB Service Settings

Use the following parameters with the serveradmin command to change settings for the SMB service.

Parameter (smb:) Description

adminCommands:homes Whether home directories are mounted automatically when

Windows users log in so you don’t have to set up individual share points for each user. Can be set to:

yes | no Corresponds to the “Enable virtual share points” checkbox in

the Advanced pane of Window service settings in the Server Admin GUI application.

adminCommands:serverRole The authentication role played by the server. Can be set to:

"standalone" "domainmember" "primarydomaincontroller"

Corresponds to the Role pop-up menu in the General pane of Windows service settings in the Server Admin GUI application.

domain master Whether the server is providing domain master browser

service. Can be set to: yes | no Corresponds to the Domain Master Browser checkbox in the

Advanced pane of Window service settings in the Server Admin GUI application.

dos charset The code page being used. Can be set to:

CP437 (Latin US) CP737 (Greek) CP775 (Baltic) CP850 (Latin1) CP852 (Latin2) CP861 (Icelandic) CP866 (Cyrillic) CP932 (Japanese SJIS) CP936 (Simplified Chinese) CP949 (Korean Hangul) CP950 (Traditional Chinese) CP1251 (Windows Cyrillic)

Corresponds to the Code Page pop-up menu on the Advanced pane of Windows service settings in the Server Admin GUI application.

82 Chapter 8 Working With File Services

Page 83

Parameter (smb:) Description

local master Whether the server is providing workgroup master browser

service. Can be set to: yes | no Corresponds to the Workgroup Master Browser checkbox in

the Advanced pane of Window service settings in the Server Admin GUI application.

log level The amount of detail written to the service logs. Can be set to:

0 (Low: errors and warnings only) 1 (Medium: service start and stop, authentication failures,

browser name registrations, and errors and warnings) 2 (High: service start and stop, authentication failures,

browser name registration events, log file access, and errors and warnings)

Corresponds to the Log Detail pop-up menu in the Logging pane of Window service settings in the Server Admin GUI application

map to guest Whether guest access is allowed. Can be set to:

"Never" (No guest access) "Bad User" (Allow guest access)

Corresponds to the “Allow Guest access” checkbox in the Access pane of Window service settings in the Server Admin GUI application

max smbd processes The maximum allowed number of smb server processes. Each

connection uses its own smbd process, so this is the same as specifying the maximum number of SMB connections.

0 means unlimited. This corresponds to the “maximum” client connections field in

the Access pane of the Windows service settings in the Server Admin GUI application.

netbios name The server’s NetBIOS name. Can be set to a maximum of 15

bytes of UTF-8 characters. Corresponds to the Computer Name field in the General pane

of the Windows service settings in the Server Admin GUI application.

server string Text that helps identify the server in the network browsers of

client computers. Can be set to a maximum of 15 bytes of UTF-8 characters.

Corresponds to the Description field in the General pane of the Windows service settings in the Server Admin GUI application.

wins support Whether the server provides WINS support. Can be set to:

yes | no

Corresponds to the WINS Registration “Off” and “Enable WINS server” selections in the Advanced pane of the Windows service settings in the Server Admin GUI application.

Chapter 8 Working With File Services 83

Page 84

Parameter (smb:) Description

wins server The name of the WINS server used by the server.

Corresponds to the WINS Registration “Register with WINS server” selection and field in the Advanced pane of the Windows service settings in the Server Admin GUI application.

workgroup The server’s workgroup. Can be set to a maximum of 15 bytes

of UTF-8 characters. Corresponds to the Workgroup field in the General pane of the

Windows service settings in the Server Admin GUI application.

List of SMB serveradmin Commands

You can use these commands with the serveradmin tool to manage SMB service.

smb:command= Description

disconnectUsers Disconnect SMB users. See “Disconnecting SMB Users” on page 85. getConnectedUsers List users currently connected to an SMB service. See “Listing SMB

Users” on this page.

getHistory List connection statistics. See “Listing SMB Service Statistics” on

page 86.

getLogPaths Show location of service log files. See “Viewing SMB Service Logs”

on page 87.

syncPrefs Update the service to recognize changes in share points. See

“Updating Share Point Information” on page 86.

writeSettings Equivalent to the standard serveradmin settings command,

but also returns a setting indicating whether the service needs to be restarted. See “Determining Whether a Service Needs to be Restarted” on page 19.

Listing SMB Users

You can use the serveradmin getConnectedUsers command to retrieve information about connected SMB users. For example, you can use this command to retrieve the session IDs you need to disconnect users.

To list connected users:

$serveradmin command smb:command = getConnectedUsers

84 Chapter 8 Working With File Services

Page 85

Output

The following array of settings is displayed for each connected user:

smb:usersArray:_array_index:i:disconnectID = <disconnectID> smb:usersArray:_array_index:i:sessionID = <sessionID> smb:usersArray:_array_index:i:connectAt = <connect-time> smb:usersArray:_array_index:i:service = <service> smb:usersArray:_array_index:i:loginElapsedTime = <login-elapsed-time> smb:usersArray:_array_index:i:name = "<name>" smb:usersArray:_array_index:i:ipAddress = "<ip-address>"

Value returned by getConnectedUsers

(smb:usersArray:_array_index:<

<sessionID> An integer that identifies the user session. <connect-time> The date and time when the user connected to

<service> The share point the user is accessing. <login-elapsed-time> The elapsed time since the user connected. <name> The user’s name. <ip-address> The user’s IP address.

>:) Description

the server.

Disconnecting SMB Users

You can use the serveradmin disconnectUsers command to disconnect SMB users. Users are specified by session ID.

To disconnect users:

$ sudo serveradmin command smb:command = disconnectUsers smb:sessionIDsArray:_array_index:0 = sessionid1 smb:sessionIDsArray:_array_index:1 = sessionid2 smb:sessionIDsArray:_array_index:2 = sessionid3 [...] Control-D

Parameter Description

sessionid

n The session ID of a user you want to disconnect. To list the session

IDs of connected users, use the getConnectedUsers command. See “Listing SMB Users” on page 84.

Output

smb:command = "disconnectUsers" smb:status

Value Description

<status> A command status code:

Chapter 8 Working With File Services 85

= <status>

0 = command successful

Page 86

Listing SMB Service Statistics

You can use the serveradmin getHistory command to display a log of periodic samples of the number of SMB connections. Samples are taken once each minute.

To list samples:

$ sudo serveradmin command smb:command = getHistory smb:variant = v1 smb:timeScale = scale Control-D

Parameter Description

v1 The number of connected users (average during sampling period). scale

Output

smb:nbSamples = <samples> smb:samplesArray:_array_index:0:v smb:samplesArray:_array_index:0:t = <time> smb:samplesArray:_array_index:1:v smb:samplesArray:_array_index:1:t = <time> [...] smb:samplesArray:_array_index: smb:samplesArray:_array_index: smb:v1Legend = "CONNECTIONS" smb:currentServerTime = <servertime>

The length of time in seconds, ending with the current time, for which you want to see samples. For example, to see 30 minutes of data, you would specify smb:timeScale = 1800.

= <sample>

i:vn

= <sample>

:t = <time>

Value displayed by getHistory Description

<samples> The total number of samples listed. <legend> A textual description of the selected statistic.

"CONNECTIONS" for v1 "THROUGHPUT" for v2

<sample> The numerical value of the sample.

For connections (v1), this is integer average number of users. For throughput, (v2), this is integer bytes per second.

<time> The time at which the sample was measured. A standard UNIX time

(number of seconds since Sep 1, 1970.) Samples are taken every 60 seconds.

Updating Share Point Information

After you make a change to an SMB share point using the sharing tool, you need to update the SMB service information.

To update SMB share point information:

$ sudo serveradmin command smb:command = syncPrefs

86 Chapter 8 Working With File Services

Page 87

Viewing SMB Service Logs

You can use tail or any other file listing tool to view the contents of the SMB service logs.

To view the latest entries in a log:

$ tail log-file

You can use the serveradmin getLogPaths command to see where the current SMB logs are located.

To display the log paths:

$ sudo serveradmin command smb:command = getLogPaths

Output

smb:fileServiceLog = <smb-log> smb:nameServiceLog = <name-log>

Value Description

<smb-log> The location of the SMB service log. Default =

/var/log/samba/log.smbd

<name-log> The location of the name service log. Default =

/var/log/samba/log.nmbd

Chapter 8 Working With File Services 87

Page 88

Page 89

9 Working With Print Service

Commands you can use to manage the Print service in Mac OS X Server.

Starting and Stopping Print Service

To start Print service:

$ sudo serveradmin start print

To stop Print service:

$ sudo serveradmin stop print

Checking the Status of Print Service

To see summary status of Print service:

$ sudo serveradmin status print

To see detailed status of Print service:

$ sudo serveradmin fullstatus print

Viewing Print Service Settings

To list Print service configuration settings:

$ sudo serveradmin settings print

To list a particular setting:

$ sudo serveradmin settings print:setting

To list a group of settings:

$ sudo serveradmin settings print:queuesArray:_array_id:queue-id:*

where queue-id is an id such as 66F66AdA-060B-5603-9024-FCB57AAB24B1.

Page 90

Changing Print Service Settings

To change a setting:

$ sudo serveradmin settings print:setting = value

Parameter Description

setting

value

A Print service setting. To see a list of available settings, type

$ sudo serveradmin settings print

or see “Print Service Settings” on this page.

An appropriate value for the setting.

To change several settings:

$ sudo serveradmin settings print:setting print:setting = value print:setting = value [...] Control-D

= value

Print Service Settings

Use the following parameters with the serveradmin command to change settings for the Print service.

Parameter (print:) Description

serverLogArchiveIntervalDays Default = 7 <queue arrays> See “Queue Data Array” on page 91. serverLogArchiveEnable Default = no jobLogArchiveIntervalDays Default = 7 jobLogArchiveEnable Default = no

90 Chapter 9 Working With Print Service

Page 91

Queue Data Array

Print service settings include an array of values for each existing print queue. The array is a set of 14 parameters that define values for each queue.

<id> is the queue ID, for example, 29D3ECF3-17C8-16E5-A330-84CEC733F249.

Parameter (print:) Description

queuesArray:_array_id:<id>: quotasEnforced

queuesArray:_array_id:<id>: sharingList:_array_index:0: service

queuesArray:_array_id:<id>: sharingList:_array_index:0: sharingEnable

queuesArray:_array_id:<id>: sharingList:_array_index:1: service

queuesArray:_array_id:<id>: sharingList:_array_index:1: sharingEnable

queuesArray:_array_id:<id>: sharingList:_array_index:2: service

queuesArray:_array_id:<id>: sharingList:_array_index:2: sharingEnable

queuesArray:_array_id:<id>: shareable

queuesArray:_array_id:<id>: defaultJobPriority

queuesArray:_array_id:<id>: printerName

queuesArray:_array_id:<id>: defaultJobState

queuesArray:_array_id:<id>: printerURI

queuesArray:_array_id:<id>: registerRendezvous

queuesArray:_array_id:<id>: printerKind

queuesArray:_array_id:<id>: sharingName

Default = no

Default = "LPR"

Default = no

Default = "SMB"

Default = no

Default = "PAP"

Default = no

Default = yes. Cannot be changed.

Not used. Default = "NORMAL"

Default = "<printer-name>" Cannot be changed using serveradmin.

Not used. Default = "PENDING"

Default = <uri> Format depends on type of printer. Cannot be changed using serveradmin.

Default = yes

Default = "<type>" Cannot be changed using serveradmin.

Default = "<name>"

Chapter 9 Working With Print Service 91

Page 92