# Configuration Editor Manual

2004
Sun Microsystems
2009
Philip Withnall (philip@tecnocode.co.uk)
GNOME Documentation Project

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation Licence (GFDL), Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You can find a copy of the GFDL at this link or in the file COPYING-DOCS distributed with this manual.

This manual is part of a collection of GNOME manuals distributed under the GFDL. If you want to distribute this manual separately from the collection, you can do so by adding a copy of the licence to the manual, as described in section 6 of the licence.

Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and the members of the GNOME Documentation Project are made aware of those trademarks, then the names are in capital letters or initial capital letters.

DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED UNDER THE TERMS OF THE GNU FREE DOCUMENTATION LICENCE WITH THE FURTHER UNDERSTANDING THAT:

1. DOCUMENT IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS FREE OF DEFECTS MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE QUALITY, ACCURACY, AND PERFORMANCE OF THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS WITH YOU. SHOULD ANY DOCUMENT OR MODIFIED VERSION PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL WRITER, AUTHOR OR ANY CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS LICENCE. NO USE OF ANY DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS AUTHORISED HEREUNDER EXCEPT UNDER THIS DISCLAIMER; AND

2. UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER IN TORT (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL THE AUTHOR, INITIAL WRITER, ANY CONTRIBUTOR, OR ANY DISTRIBUTOR OF THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT, OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO ANY PERSON FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR LOSSES ARISING OUT OF OR RELATING TO USE OF THE DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT, EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES.

Sun
GNOME Documentation Team
Sun Microsystems
Angela
Boyle
GNOME Documentation Project
Shaun
McCance
GNOME Documentation Project

Configuration Editor can be used to change configuration options used by applications that may not be available through Preference dialogues.

Version 2.8
September 2004

GNOME Documentation Project

GNOME Documentation Project

unreviewed

Version 2.1
August 2004

Sun GNOME Documentation Team

GNOME Documentation Project

Version 2.0.1
January 2004

Sun GNOME Documentation Team

GNOME Documentation Project

This manual describes version 2.8 of Configuration Editor.

## Feedback

To report a bug or make a suggestion regarding the Configuration Editor application or this manual, follow the directions in the GNOME Feedback Page.

## Introduction

The GNOME Desktop and many applications use GConf to store user preferences and system configuration data. GConf provides a central storage location for preferences, simplifying configuration management for users and system administrators. More information about GConf can be found in the GNOME System Administrator's Guide.

Configuration Editor allows users to modify their preferences for the entire GNOME Desktop and any applications which use GConf. Additionally, system administrators can use Configuration Editor to set default and mandatory settings which will affect all users.

Preferences are stored in GConf in a hierarchy of keys. Each key has an associated value which specifies your setting for that preference. For instance, the key `/apps/glines/preferences/ball_theme` stores which theme you use in the game Five or More.

Configuration Editor enables you to modify your configuration source directly. If you are not an experienced user, do not use Configuration Editor to set preferences for the GNOME Desktop. Instead, use the preference tools in the GNOME Desktop. For information about how to use preference tools, see the latest version of the GNOME Desktop User Guide for your platform.

## Getting Started

### To Start Configuration Editor

You can start Configuration Editor in the following ways:

Applications menu

  Choose System Tools Configuration Editor.

  Some distributions hide this menu. In this case, use the second method described below.

Command line

  Execute the following command: `gconf-editor`

### When You Start Configuration Editor

When you start Configuration Editor, the following window is displayed.

#### Configuration Editor Window

Shows Configuration Editor window. Callouts: Tree pane, Modification pane, Documentation pane.

The Configuration Editor window contains the following panes:

Tree pane

  Enables you to navigate the hierarchy of keys in GConf. Use this pane to display the keys that you want to modify in the modification pane. The tree pane is on the left side of the window.

Modification pane

  Displays the keys in the selected GConf location in the tree pane. Use this pane to select keys that you want to modify and to modify the values of keys. The modification pane is in the upper part of the right side of the window.

  The icons beside the keys in the modification pane indicate what type of value you can enter for the key. For example, the check mark icon beside the `/system/http_proxy/use_http_proxy` key indicates that you can enter a Boolean value (true or false) for the key. See for more information on each icon.

Documentation pane

  Displays documentation for the currently selected key. Use this pane to read more information about the GConf preference keys.

Results pane (not shown)

  Enables you to view the results of a search or to search through the list of your recently viewed key names. The rest of the window will show the information for whichever key you have selected in this pane. The results pane will appear on the bottom of the window when you list the recent keys or perform a search.

## Working with Windows

### Opening New Windows

There are a three types of window you can open in Configuration Editor: Settings, Defaults, and Mandatory. What values Configuration Editor sets depends on what type of window you have open. You can open each type of window with the appropriate item under the File menu.

Since the settings in Defaults and Mandatory windows affect all users of the computer, only a system administrator can use these types of windows. To change your preferences, you should use the Settings window.

Settings

  You can use the Settings window to set your personal preferences. Changes made in the Settings window only affect your desktop. You cannot change the settings that the system administrator has made mandatory.

Defaults

  If you are a system administrator, you can use the Defaults window to edit the default settings for all users. If a user does not set the value of a key explicitly, the value will be taken from the default settings. Users can always override the default settings.

Mandatory

  If you are a system administrator, you can use the Mandatory window to edit the mandatory settings for all users. When a mandatory value is set for a key, users are not able to change that value. This can be used to lock down certain options.

### Closing and Quitting

You can close a Configuration Editor window by selecting File Close Window in that window. To close all Configuration Editor windows and quit the application completely, select File Quit in any Configuration Editor window.

## Working with Keys

Keys are a way of looking up a value. Every preference stored in GConf is assigned to a key. Applications which use GConf access the values of keys to determine how to look and behave. When you change something in the Preferences of an application, you are changing the value associated to a key in GConf.

### Copying a Key Name

To copy a key name to the clipboard, select the key name you want to copy in the modification pane. Choose Edit Copy Key Name. You can paste the key name into any other application.

### Viewing Recent Key Names

To view recent key names, choose Edit List Recent Keys. This action will open the results pane at the bottom of the current window. You can move through the results list by scrolling up and down with the scroll bar or the arrow keys. The information for the selected key or folder will appear in the rest of the window.

Viewing recent keys is useful if you need to get back to a key you just changed and don't remember where it is.

### Modifying the Value of a Key

The icons next to the key name show what kind of value that key can take. See for more information on each icon. To modify the value of a key, perform the following steps:

1. Use the tree pane to display the key that you want to modify in the modification pane.

2. Select the key to modify in the modification pane.

3. To change the value of an integer key or a string key, click in the Value column of the key. Type the new value for the key. Alternatively, right-click on the key and select Edit Key from the popup menu.

   To change the value of a Boolean key, click in the Value column of the key to select or deselect the check box. Alternatively, right-click on the key and select Edit Key from the popup menu.

   To change the value of a list key, right-click on the key and select Edit Key from the popup menu. The Edit Key dialogue provides a list of the values associated to that key. You can use this dialogue to edit each particular value in the list, add or remove values from the list, and move each value up or down in the list.

Your system administrator may have locked down certain keys by providing mandatory values. If the selected key has a mandatory value set, you will not be able to edit the value. The documentation pane will display the label This key is not writable if you are not allowed to edit the value of that key.

## Finding Keys Quickly

To locate keys quickly, Configuration Editor allows you to search the key names in GConf. Additionally, you can use bookmarks to find directories of keys that you need to access frequently.

### Using Bookmarks

To access a directory location in your bookmarks, choose the location from the Bookmarks menu. You can add and remove directory locations to your Bookmarks menu.

To add a bookmark, select the location that you want to bookmark in the tree pane. Choose Bookmarks Add Bookmark.

To delete a bookmark, perform the following steps:

1. Choose Bookmarks Edit bookmarks.

2. Select the bookmark in the Edit bookmarks dialogue, then click Delete.

3. Click Close.

### Searching for Keys

To search for keys, perform the following steps:

1. Choose Edit Find.

2. Enter the keyword you want to search for in the Search for field. You can also select the optional check boxes Search also in key names and Search also in key values. If these check boxes are not selected, the search will only be performed on folder names. Selecting these boxes will expand the search parameters.

3. Click Find.

The results from the search will appear in the results pane. To move through the results list, first select that pane. Then you can move through the results with the scroll bar or the arrow keys. The information for the selected key or folder will appear in the rest of the window.

## Default and Mandatory Settings

If you are a system administrator, you can set default and mandatory settings in GConf which will affect all users. Default settings are used when the user has not set a value explicitly, and users can always override them. Mandatory settings are always used for all users, and they cannot override them.

You can use the Defaults and Mandatory windows to edit and remove default and mandatory settings. The Defaults and Mandatory windows will only show you those settings which have already been made default or mandatory. You cannot use these windows to create new default and mandatory settings. Instead, you can set settings from the Settings window to be default or mandatory.

To open a Defaults window, choose File New Defaults Window. To open a Mandatory window, choose File New Mandatory Window.

### Creating Default Settings

To create a default setting, perform the following steps:

1. In the Settings window, use the tree pane to display the key that you want to set as default.

2. Right-click on the key and select Set as Default from the popup menu.

### Creating Mandatory Settings

To create a mandatory setting, perform the following steps:

1. In the Settings window, use the tree pane to display the key that you want to set as mandatory.

2. Right-click on the key and select Set as Mandatory from the popup menu.

### Modifying and Removing Default and Mandatory Settings

You can use the Defaults and Mandatory windows to modify and remove default and mandatory settings. To modify a default or mandatory setting, use the appropriate window and modify the key as you would for keys in the Settings window. See for more information on modifying keys.

To remove a default or mandatory key, perform the following steps:

1. In the appropriate window, use the tree pane to display the key that you want to remove from the default or mandatory settings.

2. Right-click on the key and select Unset Key from the popup menu.

## Icons and Key Types

The icons beside the keys in the modification pane indicate what type of value you can enter for the key. The following list shows the possible icons and what types of values they represent.

Boolean key

  Can be either true or false. Configuration Editor will provide a check box for this type of key.

Number key

  Can hold numbers. These can be either integer or floating point (fractional) numbers.

String key

  Can hold any string of text.

Schema key

  Used for documenting other keys. The documentation for each key is provided by a separate key, typically under the `/schemas` directory. Users and system administrators usually will not need to work with schema keys directly.

List key

  Lists of arbitrary length. Each element of the list must be of the same type, and one of the primitive types of boolean, number, or string.

Pair key

  Can hold exactly two values. The two values must be one of the primitive types, but they do not have to be the same type. Currently, Configuration Editor is unable to edit pair keys.

Blank

  Used when Configuration Editor does not understand the type of key. The blank icon is also currently used for pair keys.