WebYaST User Guide

Jakub Friedl

Copyright © 2006–2013 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled GNU Free Documentation License.

For SUSE or Novell trademarks, see the Novell Trademark and Service Mark list http://www.novell.com/company/legal/trademarks/tmlist.html. All other third party trademarks are the property of their respective owners. A trademark symbol (®, ™ etc.) denotes a SUSE or Novell trademark; an asterisk (*) denotes a third party trademark.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, SUSE LINUX Products GmbH, the authors, nor the translators shall be held liable for possible errors or the consequences thereof.


Table of Contents

1. Introduction
Supported Browsers
Additional Documentation and Resources
Reporting Bugs and Feedback
Documentation Conventions
2. Initial System Setup
3. WebYaST Control Panel
The Header
The System Status Area
Rebooting and Shutting Down
The Configuration Area
4. WebYaST Configuration Modules
Configuring Firewall
Configuring Time Settings
Managing System Updates
Monitoring System Status
Setting Status Limits
Managing System Services
System Registration
Configuring Network Settings
Enabling LDAP Authentication
Enabling Kerberos Authentication
Enabling Active Directory Authentication
Managing Software Repositories
Managing Users
Managing Groups
Configuring Mail Settings
Configuring Roles
Configuring Administrator Settings
A. GNU Licenses
GNU Free Documentation License

List of Figures

3.1. WebYaST Control Panel

Chapter 1. Introduction

WebYaST is a Web-based remote console for controlling appliances based on SUSE® Linux Enterprise. WebYaST provides a standardized and user-friendly interface to configure the appliance black box environment. Whereas automation—wherever applicable—is the default procedure in the appliance environment, WebYaST is needed to perform some maintenance tasks that cannot be automated.

The set of available WebYaST modules is a subset of the YaST functionality available on SUSE® Linux Enterprise Server or SUSE® Linux Enterprise Desktop. Some WebYaST modules do not use the same code as the respective YaST modules and their functionality may differ. Besides, WebYaST can provide modules which are not available in YaST on SUSE Linux Enterprise Server or SUSE Linux Enterprise Desktop, for example the WebYaST Status module.

This guide is intended for users who want to access, configure, and monitor their appliances with WebYaST. For information about preparing an appliance equipped with WebYaST and configuring WebYaST capabilities, see the WebYaST Vendor Guide.

Supported Browsers

WebYaST supports the following Web browser clients:

  • Mozilla Firefox, version 10.x

  • Microsoft Internet Explorer, version 9.x

Unsupported Browsers

Unsupported browsers are not blocked. If an unsupported browser is used, the user is warned by a message in his or her browser. It is recommended to update the browser in that case. The message is shown on all WebYaST pages, unless the user acknowledges and disables the message.

Additional Documentation and Resources

Many chapters in this manual contain links to additional documentation resources. These include documentation that is available on the system as well as documentation available on the Internet.

For an overview of the documentation available for your product and the latest documentation updates, refer to http://www.novell.com/documentation.

Reporting Bugs and Feedback

Please ask your appliance vendor how to report bugs and give feedback.

Documentation Conventions

The following typographical conventions are used in this manual:

  • /etc/passwd: directory names and filenames

  • placeholder: replace placeholder with the actual value

  • PATH: the environment variable PATH

  • ls, --help: commands, options, and parameters

  • user: users or groups

  • Alt, Alt+F1: a key to press or a key combination; keys are shown in uppercase as on a keyboard

  • File, File+Save As: menu items, buttons

  • Dancing Penguins (Chapter Penguins, ↑Another Manual): This is a reference to a chapter in another manual.

Chapter 2. Initial System Setup

The first time you log in to an appliance via WebYaST, you need to configure basic settings in a sequence of configuration dialogs to complete the initial system setup. You can always return to the previous screen by clicking the Back button.

Initial System Setup on SLE11

SLE11 systems are typically configured before WebYaST is used. Initial system setup using WebYaST is not performed on those systems.

Custom Setup Sequence

The initial setup sequence can be customized by the vendor. The following workflow is just an example, it can differ from the system setup sequence in your appliance.

Procedure 2.1. Logging In and Completing the Initial Setup

  1. Open a browser that is supported by WebYaST and enter the appliance's URL including the port number.

  2. In the Username and Password fields, enter your login credentials for the host and click Login.

  3. If the initial system setup has not been completed yet, the Set up the system button is displayed. Click it to perform the initial setup.

  4. Choose the WebYaST Language and click Next.

  5. Read the end user license agreement (EULA). The English text is shown by default. You can choose from the available translations by changing the current language used by the WebYaST interface.

    If you agree to the terms, choose Yes, I agree to the license agreement. You may be asked to read and accept more than one EULA. If you do not agree to the license terms, you will not be allowed to continue through the basesystem setup workflow.

  6. Click Next to access the Administrator Settings.

    To set the system administrator's password, enter a password into Password and repeat it in Confirm Password. Click Save.

    To configure an e-mail address to forward the administrator's mail to, enter it into Forward mail to and click Save.  

  7. Click Next to access the system's Network settings.

    For automatic configuration using DHCP, select the Automatic option from the Configuration mode drop-down menu. For information about manual configuration, see the section called “Configuring Network Settings”.

    Changing IP Address or Hostname

    The change in network configuration is done immediately after clicking the Next button. If the hostname or IP address is changed, it may be necessary to change the URL in the browser before you can continue.

  8. Click Next to access the system's Time preferences.

    Choose the general Region and the specific Timezone. The lower part of the screen displays the time and date currently set on the system.

    To set time and date manually, select Manually configure time and edit the Time and Date entries.

    To synchronize system time with a network time server, select Synchronize via Network Time Protocol (NTP).

  9. Click Next to access the system's Mail Settings.

    In Outgoing mail server, enter the URL of the SMTP server to be used.

    In Transport Layer Security, choose whether encryption (TLS) should be used.

    Enter your credentials for the SMTP server: Username and Password. Confirm the password by entering it twice.

  10. Click Next to access the system's Registration.

    You are asked for the information the registration server needs. Enter your E-mail address, System Name (a human-readable string describing the system), and your SLES Registration Code.

    To display all information that is sent to the registration server, click Details.

  11. Click Next to finish the initial setup.

Resuming Interrupted Initial Setup

The intermediate settings are stored during the initial setup sequence. If the initial setup is interrupted and resumed later, all previously made settings are remembered.

Chapter 3. WebYaST Control Panel

After performing the initial setup as described in Chapter 2, Initial System Setup, the WebYaST control panel is shown when you log in to an appliance with WebYaST. The control panel contains the following parts:

Figure 3.1. WebYaST Control Panel

WebYaST Control Panel

The Header

The header in the top part of the WebYaST control panel screen shows the name of your appliance, hostname, your username, and the selected WebYaST interface language. You can find the Logout link in the upper right corner for secure logout.

Changing the Interface Language

The language of the WebYaST interface (locale) is automatically selected according to the browser settings. It can be also changed manually by clicking the language name in the header and selecting a new language in the list.

The System Status Area

The overall status of the system is indicated by the big circle to the left. This circle integrates the status information from the two main sections to the right (the circle is green if both sections are green):

System status

The left indicator shows the health of the system. If it is green, the system is healthy. The health information is determined by data from the Status module and the user-defined limits set there. For more information about the Status module, see the section called “Monitoring System Status”.

System updates

The right indicator shows the status of system updates. If it is green, the system is up to date and no action is necessary. If updates are available for installation, the indicator turns red.

To install available updates, click the link showing information about the updates to start the WebYaST Updates module. With this module, you can see the list of available updates and choose which updates to install. For more information about the Updates module, see the section called “Managing System Updates”.

Both fields are periodically updated. The default update interval is 5 minutes.

Changing Status Update Intervals

For changing the default status update intervals, see the vendor documentation.

Rebooting and Shutting Down

You can find buttons for rebooting and shutting down the appliance just right of the system status area of the main screen.

To reboot or shut down the appliance, click Reboot or Shutdown and confirm the action with OK. You will be logged out of the system.

The Configuration Area

In the bottom part of the control panel, icons of WebYaST modules are shown. Click these icons to start individual modules. For more information about individual modules, see Chapter 4, WebYaST Configuration Modules.

When you log in, only frequently used WebYaST modules are shown. To show all available WebYaST modules, click All. You can also show only modules related to system, network or user accounts by clicking the appropriate buttons.

Chapter 4. WebYaST Configuration Modules

This chapter describes all WebYaST configuration modules and their usage. The modules can be accessed from the configuration area of the WebYaST interface, see the section called “The Configuration Area”.

Online Module Description

The question mark icon in the header of every module links to relevant online documentation.

Concurrent Use of Configuration Modules

If a configuration module is used by two or more users at the same time, and one of the users changes and saves the configuration, a warning message is shown to the other users and their configuration is updated.

Configuring Firewall

The WebYaST Firewall module allows you to configure the firewall. The firewall can be turned on and off. Individual services can be blocked or allowed. To configure the firewall, follow these steps:

  1. Log in to the WebYaST interface of the target system and start the Firewall module.

  2. Enable or disable the firewall using the Enabled or Disabled buttons in the header. The green highlighted button indicates the current status of the firewall.

  3. The Allowed services and Blocked services groups show allowed and blocked services. Click any service to move it from one group to another.

    If you want to read a description of any service, pause the mouse pointer over it and wait for two seconds.

  4. Click Save to apply changes.

    Blocking Required WebYaST Services

    If a required service (webyast and webyast-ui) is about to be blocked, a warning message is shown when saving the configuration. This is done to prevent the user from blocking the access to WebYaST itself.

Configuring Time Settings

The WebYaST Time module allows you to configure time and date on the target system. To configure time and date, follow these steps:

  1. Log in to the WebYaST interface of the target system and start the Time module.

  2. Choose the general Region and the specific Timezone from the drop-down lists.

  3. If the system's hardware clock is set to UTC (Universal Time Coordinates), activate the Hardware clock is set to UTC option. If the hardware clock is set to the local time, the option should be inactive.

  4. To set the current time manually, select Manually configure time and edit the Date and Time entries.

    To synchronize the system time with a network time server, select Synchronize via Network Time Protocol (NTP) and enter the hostname or IP address of an NTP server.

  5. Click Save.

Logout After Changing System Time

The login time is limited to 2 hours. Therefore, if you change the system time by a large value, your session will automatically expire.

Managing System Updates

The WebYaST Updates module displays a list of available system updates. Use the list to select the updates you want to install.

To update the system, follow these steps:

  1. Log in to the WebYaST interface of the target system and start the Updates module.

  2. If the system is up to date, click Back.

  3. Use the check boxes to select the updates that you want to install.

  4. Click Update.

Alternatively, you can update your appliance from the command line with ssh and the zypper dup command.

Monitoring System Status

The WebYaST Status module displays status information collected by the collectd daemon, for example: Network, Memory and Disk usage, and CPU load. For each type of information, status icon and name is displayed. Click the name to display detailed status information. The specific data shown may be different in your appliance.

For these numeric data, it is possible to set limits. For more information about limits, see the section called “Setting Status Limits”. If the actual value exceeds these limits, the system is considered unhealthy and the status icon and the health indicator in the control panel turns red, see the section called “The System Status Area”.

The System Messages section shows system logs from the /var/log/messages file. Click System Messages to show the messages. Use the green arrows to navigate through the messages.

Setting Status Limits

 To set the limit values for status data, follow these steps:

  1. Log in to the WebYaST interface of the target system and start the Status module.

  2. Click Edit limits at the bottom of the screen.

  3. Click the type of data you want to edit to expand it.

  4. From the drop-down menus, select the type of limit you want to set and enter the appropriate numeric value to the corresponding field.

  5. Click Save and Back.

Managing System Services

The WebYaST System Services module allows you to manage system services available on the target system. To manage the system services, follow these steps:

Configuring the List of System Services

The list of services available in the System Services module is configurable. For more information, see the vendor documentation.

  1. Log in to the WebYaST interface of the target system and start the System Services module.

  2. A list of available system services is shown. Using the Filter Services drop-down menu, you can limit the list to show only the running, not running, dead, started on boot, or not started on boot services. Using the Quick Search, you can search services according to their names and descriptions.

  3. For each service, a status icon, name and a short description are shown. You can expand the information shown by clicking the little triangle on the left. A longer description, detailed status information and Start/Stop, Restart, and Start on Boot/Do Not Start on Boot buttons are shown in the expanded view.

    To change both the current status and the on-boot status (enable or disable for the current runlevel) press the Start or Stop button.

    To restart a service without changing its on-boot status, press Restart.

    To change only the on-boot status (enable or disable for the current runlevel) press the Start on Boot or Do Not Start on Boot button.

    The result of the requested status change is shown under the status buttons.

  4. If you are finished, click Back.

System Registration

The WebYaST Registration module displays the registration status of your system and allows you to register it. To register the system:

  1. Log in to the WebYaST interface of the target system and start the Registration module.

  2. You are asked for the Mandatory information the registration server needs. The needed information depends on the installed products. You will be asked repeatedly for any missing but needed information until it is supplied.

  3. More detailed information is shown under Details. Not all information sent to the registration server is shown here, usually only architecture, CPU type, and timezone.

  4. Click Save.

Configuring Network Settings

The WebYaST Network module allows you to configure the network on the target system. To configure a physical network interface, follow these steps:

  1. Log in to the WebYaST interface of the target system and start the Network module.

  2. Select an existing network interface and click Configure.

  3. Select the configuration mode. You can choose between DHCP (for automatic configuration via DHCP), Static (for manual configuration) or None (for an unconfigured interface). The selected mode is highlighted in green.

  4. To configure the network automatically via DHCP, select the DHCP configuration mode. Enter the Hostname and Domain. To ensure a static hostname with DHCP, deactivate the Change Hostname by DHCP option.

    To configure the network manually, select the Static configuration mode. Under DNS configuration, enter the Hostname and Domain, and specify the Name servers and Search domains to use.

    Under IP configuration, enter the IP address and Subnet mask/Prefixlen. The prefix should be specified in the CIDR /nn format, where nn is a number between 0 and 32. Specify the Default route.

  5. Click Save.  

    Changing IP Address or Hostname

    The change in network configuration is done immediately after clicking the Next button. If the hostname or IP address is changed, it may be necessary to change the URL in the browser before you can continue.

To configure a new virtual network interface, follow these steps:

  1. Log in to the WebYaST interface of the target system and start the Network module.

  2. Click New virtual interface.

  3. Select the type of virtual interface you want to configure: VLAN, BRIDGE, or BOND. Click Next.

  4. When configuring VLAN, enter the Interface name, select the Physical interface to be used, and enter VLAN ID.

    When configuring network bridge, enter the Interface name, and, in Bridge devices, check the physical and virtual devices to be bridged.

    When configuring bond device, enter the Interface name, Bond driver options, and, in Bond slaves, check the devices to be used.

  5. Select the configuration mode. You can choose between DHCP (for automatic configuration via DHCP), Static (for manual configuration) or None (for an unconfigured interface). The selected mode is highlighted in green.

    To configure the network manually, select the Static configuration mode. Under DNS configuration, enter the Hostname and Domain, and specify the Name servers and Search domains to use.

    Under IP configuration, enter the IP address and Subnet mask/Prefixlen. The prefix should be specified in the CIDR /nn format, where nn is a number between 0 and 32. Specify the Default route.

  6. Click Save.  

    Changing IP Address or Hostname

    The change in network configuration is done immediately after clicking the Next button. If the hostname or IP address is changed, it may be necessary to change the URL in the browser before you can continue.

To delete an existing virtual network interface, follow these steps:

  1. Log in to the WebYaST interface of the target system and start the Network module.

  2. Find the virtual interface to be deleted in the list and click Delete.

Enabling LDAP Authentication

The WebYaST LDAP module allows you to enable authentication via LDAP. Once configured, LDAP users are available in roles management and LDAP users are able to log in to WebYaST. To enable LDAP authentication, follow these steps:

  1. Log in to the WebYaST interface of the target system and start the LDAP module.

  2. Check the Enable LDAP Authentication option.

  3. Set the LDAP Server Address and Base DN as provided by your administrator. It is possible to acquire the Base DN from the server with the Fetch DN button.

  4. Check Secure Connection if a secure connection should be used.

  5. Click Save

  6. If you are using LDAP together with Kerberos, use the WebYaST Kerberosmodule to configure Kerberos. For more information, see the section called “Enabling Kerberos Authentication”.

Enabling Kerberos Authentication

The WebYaST Kerberos module allows you to enable authentication via Kerberos client. To enable Kerberos authentication, follow these steps:

  1. Log in to the WebYaST interface of the target system and start the Kerberos module.

  2. Check the Enable Kerberos Authentication option.

  3. Set the Default Domain, Default Realm, and KDC Server Address as provided by your administrator.

  4. Click Save.

Enabling Active Directory Authentication

The WebYaST Active Directory module allows you to enable authentication of Active Directory users. Once configured, Active Directory users are available in roles management and Active Directory users are able to log in to WebYaST. To enable Active Directory authentication, follow these steps:

  1. Before setting Active Directory authentication, ensure that the system time is correct, preferably by NTP synchronization. Ensure that the hostname does not change—either configure DHCP to not change hostnames for a given IP address or set a fixed hostname in the network settings.

  2. Log in to the WebYaST interface of the target system and start the Active Directory module.

  3. Check the Enable Authentication of AD users option.

  4. Enter the Active Directory Domain to be used. If the machine is not a member of the given domain, you will be asked for an Administrator Username, Password and Machine Account.

  5. Click Save.

Managing Software Repositories

The WebYaST Software Repositories module allows you to manage software repositories. You can view the list of software repositories, edit them, or add new repositories.

To view the list of software repositories, edit or delete them, follow these steps:

  1. Log in to the WebYaST interface of the target system and start the Software Repositories module.

  2. The list of available software repositories is shown. For each repository, its status icon, name and URL are shown. Using the Filter repositories drop-down menu, you can limit the list to enabled, disabled, or all repositories. You can also limit the repositories shown in the list by entering a string in Quick Search.

  3. Click any repository in the list to view detailed information.

    Detailed view contains the Alias, Name, and URL of the repository. The latter two fields are editable. The status of the repository and of its autorefresh are shown. Both can be enabled or disabled. You can also enable or disable keeping of downloaded packages.

  4. To save the changes, click Save. To delete the selected repository, click Delete.

To add a new repository, follow these steps:

  1. Log in to the WebYaST interface of the target system and start the Software Repositories module.

  2. Click New Repository.

  3. Enter the Alias, Name, and URL of the repository to be added. Select whether the repository should be enabled, whether its autorefresh should be enabled, and whether downloaded packages should be kept.

  4. To save the changes, click Save.

Managing Users

The WebYaST Users module allows you to manage local non-system users. You can view the list of users, edit them, or add new users.

To view the list of users, edit or delete users, follow these steps:

  1. Log in to the WebYaST interface of the target system and start the Users module.

  2. The list of local non-system users is shown. For each user, its username and full name is shown. You can limit the users shown in the list by entering a string in Filter.

  3. Click any user in the list to view detailed information.

    In the Login Settings tab, you can view and edit the user's Full Name and Login Name. You can also edit the user's Password. The new password must be confirmed in Confirm Password.

    In the Groups tab, you can view and edit Groups and the Default Group that the selected user belongs to. You can edit groups manually or select them using the Manage Groups and Select Default Group buttons.

    In the Advanced tab, you can view and edit the user's Home Directory, Login Shell, and UID Number.

    In the Roles tab, you can manage the user's roles. Click the Manage Roles button and click individual roles to move them between Selected Roles (active) and Available Roles (inactive).

  4. To save the changes, click Save. To delete the selected user, click Delete.

To create a new user, follow these steps:

  1. Log in to the WebYaST interface of the target system and start the Users module.

  2. Click New User.

  3. In the Login Settings enter the user's Full Name, Login Name, and Password. The password strength is indicated by the color bar. The password must be confirmed in Confirm Password.

    In the Groups tab, you can add Groups and the Default Group that the new user belongs to. You can add groups manually or select them using the Manage Groups and Select Default Group buttons. If not edited, the default group users is used.

    In the Advanced tab, you can edit the user's Home Directory, Login Shell, and UID Number. If not edited, default values are used.

    In the Roles tab, you can manage the user's roles. Click the Manage Roles button and click individual roles to move them between Selected Roles (active) and Available Roles (inactive).

  4. To save the changes, click Save.

Using the Manage Groups link, you can access the WebYaST Groups module directly.

Managing Groups

The WebYaST Groups module allows you to manage local user groups (bot system and non-system). You can view the list of groups, edit them, or add new groups.

To view the list of groups, edit or delete groups, follow these steps:

  1. Log in to the WebYaST interface of the target system and start the Groups module.

  2. The list of local user groups is shown. You can limit the groups shown in the list by entering a string in Filter.

  3. Click any group in the list to view detailed information. You can view and edit the Group Name, Group ID, and comma-separated list of Members.

    To edit the list of members, you can use the Manage Members button. It shows a dialog with two lists of users: Selected Members and Available Members. Click any member to move it from one list to another. Save the changes with OK.

  4. To save the changes, click Save. To delete the selected group, click Delete.

To create a new user group, follow these steps:

  1. Log in to the WebYaST interface of the target system and start the Groups module.

  2. Click New Group.

  3. Enter the Group Name and comma-separated list of Members.

    To edit the list of members, you can use the Manage Members button. It shows a dialog with two lists of users: Selected Members and Available Members. Click any member to move it from one list to another. Save the changes with OK.

  4. To save the changes, click Save.

Using the Manage Users link, you can access the WebYaST Users module directly.

Configuring Mail Settings

The WebYaST Mail Settings module allows you to configure a server for outgoing mail (SMTP). To configure the SMTP server, follow these steps:

  1. Log in to the WebYaST interface of the target system and start the Mail Settings module.

  2. In Outgoing mail server, enter the URL of the SMTP server to be used.

  3. In Use secure connection (TLS), choose whether encryption (TLS) should be used. The available options are: Disabled, If available, and Always.

  4. Enter your credentials for the SMTP server: Username and Password. Confirm the password by entering it in Confirm password.

  5. You can test the mail settings by entering an e-mail address in Send test mail to and pressing Send Mail. The test mail will be also sent when clicking Save.

  6. Click Save

Configuring Roles

The WebYaST Roles module allows you to view and configure user roles. To create and configure roles and to assign users to roles, follow these steps:

  1. Log in to the WebYaST interface of the target system and start the Roles module.

  2. On the Assign Permissions tab, a table showing all available permissions and roles is shown. Permissions are in rows; roles are in columns. You can click permissions to collapse or expand detailed permissions. You can collapse all permissions with Collapse all.

  3. To create a new role, click Create Role, enter its desired Name, and click the Create Role button.

  4. Assign individual permissions to roles by checking them in the Assign Permissions table.

  5. On the Assign Users tab, you can assign users to specific roles. The role containers are on the left. The alphabetically sorted list of users is on the right. To assign a user to a specific role, drag the username to be assigned from the right to a role container on the left. Users can have more than one role; in such a case, a user is granted union of all permissions granted by his roles.

    To remove a user from a role, move the cursor over the username in a role container and click the little cross.

    You can search for specific users in the list using the search bar in the header.

  6. Click Save to save the changes.

Changing User Rights

After user rights are changed in the role management you should log out and log in again to ensure that all changes take effect.

Configuring Administrator Settings

The WebYaST Administrator Settings module allows you to to set a password and an e-mail address for the system administrator (root). To configure administrator settings, follow these steps:

  1. Log in to the WebYaST interface of the target system and start the Administrator Settings module.

  2. To change the administrator password enter it in New Password and repeat it in Confirm Password. Click Save.

  3. To configure an e-mail address to forward administrator's mail to, enter it in Forward system mail to and click Save.

  4. To change only the administrator's e-mail address, click Save Mail Only. To change both the administrator's password and the e-mail address, or the password only, press Save.

Appendix A. GNU Licenses

This appendix contains the GNU Free Documentation License version 1.2.

GNU Free Documentation License

Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.

The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

3. COPYING IN QUANTITY

If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

  1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.

  2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.

  3. State on the Title page the name of the publisher of the Modified Version, as the publisher.

  4. Preserve all the copyright notices of the Document.

  5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.

  6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.

  7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.

  8. Include an unaltered copy of this License.

  9. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.

  10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.

  11. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.

  12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.

  13. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.

  14. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.

  15. Preserve any Warranty Disclaimers.

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements".

6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

8. TRANSLATION

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

   Copyright (c) YEAR YOUR NAME.
   Permission is granted to copy, distribute and/or modify this document
   under the terms of the GNU Free Documentation License, Version 1.2
   or any later version published by the Free Software Foundation;
   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
   A copy of the license is included in the section entitled “GNU
   Free Documentation License”.
  

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this:

   with the Invariant Sections being LIST THEIR TITLES, with the
   Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
  

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.