OS X Server: How to edit configuration files
Server documentation may instruct you to create or modify Property Lists (plists) or other text-based configuration files to enable functionality that isn’t exposed in the Server Admin Tools.
If you’re unfamiliar with editing configuration files, read about the following topics.
Choosing an appropriate text editor
TextEdit (in /Applications/) is a familiar graphical text editor. It can be used to edit configuration files in some circumstances, but you must take extra care to save the document in a format that can be used by the system (see below). It is also more difficult to edit files with restrictive permissions in TextEdit than in a command-line text editor.
Using a command-line text editor avoids some of the formatting and permissions pitfalls associated with using TextEdit. The three most full-featured command-line text editors included with OS X are:
nano is a simple command-line based editor. It’s a replacement for the pico editor, so instructions for using the pico editor can be used with nano. If you invoke the pico editor, you actually run nano. Nano is a good introduction to using a command-line based editor as it includes easy-to-follow on-screen help.
vim is a vi-compatible text editor. It has many powerful enhancements for moving around, searching, and editing documents. Basic editing is simple to learn and there is much additional functionality to explore. Most functionality is accessed by typing combinations of keystrokes that trigger certain behavior. Vim, or the editor it’s modeled after, vi, is found in most UNIX-based operating systems. If you’ll be doing lots of editing from the command line, it’s a good editor to learn to use, but if you only use a command-line based editor occasionally, you can get by without learning it.
Emacs is, like vim, an extremely full-featured editor found on most UNIX- based systems. In addition to its editing capabilities, Emacs is extremely customizable, with additional functionality available in modules that let the Emacs interface do much more than just text editing. It’s relatively easy to do basic editing with, and has an incredible depth of functionality for the dedicated user to explore. Like vim, Emacs uses keystroke combinations to access its many different functional behaviors. These require memorization to be most useful, so Emacs is most useful for people who use the command line very often.
If you’re new to using the command line and don’t anticipate using it much for editing, nano is probably your best choice. If you expect to spend a lot of time using the command-line environment, it’s probably worth learning either vim or Emacs. They have very different design philosophies, so spend some time with each of them to determine which works best for you.
You invoke a command-line editor by typing the name of the editor, followed by a space and then the name of the file you want to open. If you want to create a new file, type a name for the file. Here’s an example of using nano to open a new file named "myFile.conf" in your Documents folder:
nano ~/Documents/myFile.conf
Depending on the permissions on the file, you may have to use the sudo command. Here's an example of using nano to edit the ldap.conf file, which can only be changed by the root user:
sudo nano /etc/openldap/ldap.conf
For more information about using nano, vim, or Emacs, see their respective man pages.
Saving text files for system use
When you edit text files for execution by UNIX utilities, you need to save the files properly so that they can be used (or executed) by their calling program. It’s especially important to use plain text and ensure that the privileges are correct.
Using plain text
Many graphical text editors, including TextEdit, save text files in a more complex format than most UNIX programs expect. If you’re using TextEdit to edit text-based configuration files, save them as Plain Text, not the default Rich Text Format. To change the default format of text documents in TextEdit you have two options:
To save all documents as plain text, select "Plain text" under Format in the New Document pane of TextEdit preferences.
To change the format of an individual document, choose "Make Plain Text" from the Format menu.
Although Rich Text Format may appear to be simple text in an editor, it's actually a full specification that describes formatting, colors, fonts, and other information that isn’t contained in the plain text files that most UNIX programs expect. To see what’s actually contained in a Rich Text Format document, save one in TextEdit, and then open the same file in a command-line text editor.
Command-line text editors will automatically save configuration files in plain text.
Permissions
You must have permission to read and write to the configuration file, and you must be sure that the edited file retains its original permissions or the system may not be able to use it.
Many system files can only be edited by the root user. If you open a configuration file with restricted permissions in Text Edit after logging in as a regular user, you may get a message that you don't have permission to save the file. Avoid changing permissions on the file or logging in as the root user to access the file. Instead, log in as an administrator and temporarily assume root privileges by using the sudo command with a command-line editor, as shown above.
Editing property lists
Many preference and configuration files in OS X use property lists (plists) to specify the attributes or properties of an application or process. An example is the Finder’s preferences plist in the Library/Preferences/ folder of a user’s home folder. The file is named com.apple.Finder.plist. The default naming convention for a plist includes the distributor’s reverse DNS name prepended to the application or process name, followed by a ".plist" extension.
Property lists may be in either binary or xml format. You can use a text editor to edit xml property lists, and you can use the following tools to edit property lists in either format.
Xcode and Property List Editor are OS X developer tools that provide a graphical interface for editing property lists. Xcode version 4 or later can edit property lists directly. Previous versions of the developer tools include Property List Editor as a separate standalone application. These tools are most useful if you already understand property lists and their conventions. See http://developer.apple.com/mac for more information.
defaults is a command-line tool that you can use to read and edit property lists. It is efficient to use when you know the specific key and value in a property list that you need to change.
PlistBuddy is another command-line tool for directly reading and modifying values inside a property list. It is more flexible than defaults when you need to make changes a complex plist file.
For information about using defaults and PlistBuddy, see their respective man pages.
Learn more
Back up files before editing
Whenever you edit a configuration file or property list, it is good practice to make a backup of the file before editing it. That way, if you accidentally misconfigure the file you can replace it with a working copy. Since many configuration files are in locations where you have read access, but not write access, you can typically either copy the file to another location using the Finder, or copy it in place using the sudo command. For example, the following command will make a backup copy of the syslog.conf file called syslog.conf.original.
sudo cp /etc/syslog.conf /etc/syslog.conf.original
The following two commands will move aside a misconfigured syslog.conf file and replace it with the backup copy created above.
sudo mv /etc/syslog.conf /etc/syslog.conf.bad
sudo cp /etc/syslog.conf.original /etc/syslog.conf
