Hardening SUSE Linux Enterprise Server with STIG

1 What is STIG? #

STIG stands for Security Technical Implementation Guide. The Defense Information Systems Agency (DISA) organization, which is a parent agency of the United States Department of Defense (DoD) , approves and publishes Security Technical Implementation Guides (STIGs) and updates them every 90 days.

STIGs are a set of rules and best practices for configuring systems to defend against potential threats. Each implementation guide is tailored to a specific product and version, defining a configuration standard with cybersecurity requirements for this product and version.

These requirements must be met when the system connects to a DoD network. But Security Technical Implementation Guides are also used outside of the government sector.

2 Benefits #

When a Security Technical Implementation Guide is implemented for a system, the system is hardened. The goals are to minimize attacks and to prevent system access (both physically and via a network) and to define processes for maintenance (applying software updates) and vulnerability patching. Security Technical Implementation Guides can also cover configuration settings, for example, for operating systems, routers, databases, firewall rules, domain name servers and switches.

STIGs are ubiquitous across all systems.

3 Hardening SUSE Linux Enterprise Server with STIG #

There are several ways to harden your systems with the STIG.

During installation with YaST or AutoYaST

Starting with SUSE Linux Enterprise 15 SP4, YaST and AutoYaST let you check certain basic aspects of the system at installation time. You can also enable a full scan or scan and remediation, respectively, at first boot of the system.

For details, see SUSE Linux Enterprise Server Deployment Guide.

With OpenSCAP

You can scan or remediate an existing system to bring it to a compliant state. OpenSCAP can be used to check and remediate local systems as well as remote systems.

With STIG Viewer

You can manually review the rules from DISA and apply them to a dedicated system.

4 Applying a STIG profile #

The contents delivered with the SCAP Security Guide can be used to check or check and remediate systems according to a specific profile.

Regarding STIG, SUSE supports the following SCAP Security Guide profiles:

DISA STIG for SUSE Linux Enterprise 15
DISA STIG for SUSE Linux Enterprise 12

The following sections give certain examples on how to scan SUSE Linux Enterprise with oscap for STIG compliance and how to perform a remediation. For more background on OpenSCAP and the SCAP Security Guide, see the article Hardening SUSE Linux Enterprise with OpenSCAP.

4.1 Scanning a SLE system for STIG compliance #

The following example shows how to scan SUSE Linux Enterprise 15 locally with oscap for vulnerability issues according to the profile DISA STIG for SUSE Linux Enterprise 15. You can save the results in XML format and generate an HTML report.

Example 1: Scanning SUSE Linux Enterprise with oscap #

> sudo oscap xccdf eval1 \
     --profile stig2 \
     --results /tmp/results.xml3 \
     --report /tmp/report.html4 \
     /usr/share/xml/scap/ssg/content/ssg-sle15-ds.xml5

1	Calls the `oscap xccdf` module and tells it to perform an evaluation (vulnerability scan).
2	Specifies the profile to use, in this case, `stig`.
3	Saves the results of the evaluation to /tmp/results.xml.
4	Generates an HTML report called /tmp/report.html in addition to the results in XML.
5	Specifies the `SCAP Security Guide` policy file to use. In this example, we use a policy file in the `DataStream` format that applies to SUSE Linux Enterprise code 15. To list all available policies, run: `ls -1 /usr/share/xml/scap/ssg/content/ssg-*-ds.xml`. For more information about a particular policy, run `oscap info` on the file.

The evaluation process usually takes a few minutes, depending on the number of selected rules.

4.2 Making a SLE system STIG-compliant #

The following examples show how to scan and remediate SUSE Linux Enterprise locally with oscap according to the profile DISA STIG for SUSE Linux Enterprise 15.

4.2.1 Remediating SUSE Linux Enterprise with oscap (on the fly) #

For remediation with oscap on the fly, use the --remediate command-line option.

Example 2: Remediating SLE 15 with oscap (on the fly) #

> sudo oscap xccdf eval --remediate1 \
      --profile stig2 \
      --results /tmp/results.xml3 \
      /usr/share/xml/scap/ssg/content/ssg-sle15-ds.xml4

1	Calls the `oscap xccdf` module and tells it to perform an evaluation plus a remediation of the target system in one go.
2	Specifies the profile to use, in this case, `stig`.
3	Saves the results of the evaluation to /tmp/results.xml.
4	Specifies the `SCAP Security Guide` policy file to use. In this example, we use a policy file in the `DataStream` format that applies to SUSE Linux Enterprise code 15. To list all available policies, run: `ls -1 /usr/share/xml/scap/ssg/content/ssg-*-ds.xml`. For more information about a particular policy, run `oscap info` on the file.

In the resulting /tmp/results.xml file, the first TestResult element shows the result of the scan before the remediation. The second TestResult element shows the result of the scan after applying the remediation. In the second TestResult element, if the result of a rule is fixed, this means that the fix was successfully applied, and this rule now passes evaluation. If the result of a rule is error, this means that the remediation for this rule was not successful, and the rule still does not pass evaluation.

4.2.2 Remediating SUSE Linux Enterprise with oscap (after scanning) #

In this example, we first execute a scan and then run the remediation as next step.

Example 3: Remediating SLE with oscap (after scanning) #

> sudo oscap xccdf eval1 \
        --profile stig2 \
        --results /tmp/results.xml3 \
        /usr/share/xml/scap/ssg/content/ssg-sle15-ds.xml4

1	Calls the `oscap xccdf` module and tells it to perform an evaluation.
2	Specifies the profile to use, in this case, `stig`.
3	Saves the results of the evaluation as an XCCDF file to /tmp/results.xml.
4	Specifies the `SCAP Security Guide` policy file to use. In this example, we use a policy file in the `DataStream` format that applies to SUSE Linux Enterprise code 15. To list all available policies, run: `ls -1 /usr/share/xml/scap/ssg/content/ssg-*-ds.xml`. For more information about a particular policy, run `oscap info` on the file.

During this step, the system is only evaluated, and the results are stored in a TestResult element in /tmp/results.xml.

> sudo oscap xccdf remediate1 \
        --results /tmp/results.xml2 \
        /tmp/results.xml3

1	Calls the `oscap xccdf` module and tells it to perform a remediation.
2	Saves the results of the remediation to /tmp/results.xml.
3	Uses the /tmp/results.xml XCCDF file from the first step (evaluation) as input file.

During this step, the results file from the first step is used as input for the oscap command. You can safely store the results from the second step in the same file that you use as input file, /tmp/results.xml. During this run, oscap creates a new xccdf:TestResult element in the file. The new element is based on the previous one and inherits all the data. The newly created xccdf:TestResult element differs only in the rule-result elements which failed in the first run. Only for those is the remediation executed.

4.2.3 Remediating a SLE system with Ansible #

You can use the Ansible playbooks provided by the SCAP Security Guide to remediate a local system.

The ansible package is available from SUSE Package Hub. Register your SUSE Linux Enterprise system and enable the SUSE Package Hub extension. For SUSE Linux Enterprise 12, you additionally need to enable the Public Cloud module. Then install the package with sudo zypper in ansible.

Example 4: Remediating SLE 15 with Ansible #

For example, to remediate your system using the STIG Ansible playbook for SUSE Linux Enterprise 15 provided by the SCAP Security Guide, use the following command.

Warning: System configuration changes

The following command alters the configuration of your system immediately. Make sure to test this thoroughly in a non-production system first.

> sudo ansible-playbook -i "localhost," -c local \
      /usr/share/scap-security-guide/ansible/sle15-playbook-stig.yml

After the playbook has finished, you are prompted to log in to your system, which is now compliant to the chosen policy.

GNOME login screen on a STIG-compliant system

5 Using a tailored STIG profile #

The standard or default STIG profile is sufficient for most deployments. In addition, you can create, use for evaluation and apply tailoring files to tailor SCAP Security Guide content. Using tailoring files, you can change the behavior of a profile without directly modifying its standard configurations.

The following sections provide examples of creating tailoring files using either SCAP Workbench or the autotailor command-line utility, and then applying the tailoring file using the ssg-apply command-line utility.

Tip: Generalized tailoring

Although the following sections provide examples of tailoring for the STIG profile, you use a similar procedure for tailoring other profiles that are valid for your target system.

5.1 Creating a tailoring file #

Tailoring files are XML files containing information about the deviation from the standard SCAP Security Guide content for a profile. You create a tailoring file when you override certain default rules of a standard profile, and save that information along with necessary metadata as an XML file. Once created, you can apply the tailoring file using a suitable program such as the ssg-apply utility.

SUSE recommends using any of the following methods of creating a tailoring file:

Manually, using the SCAP Workbench. This method is best suited when you are unsure of the rules that you want to override in the standard content of a profile, and would prefer the convenience of a graphical software.
Automatically, using the autotailor command-line tool which is bundled with the openscap-utils package. This method is best suited when you are sure of all the information that you need to create a tailoring file.

5.1.1 Creating tailoring files using SCAP Workbench #

This section provides an example procedure for creating a tailoring file based on the standard STIG profile, using the SCAP Workbench graphical software. You can use a similar procedure to create tailoring files for any other valid profile.

As a prerequisite, ensure that you have installed the necessary packages, as described in the section https://documentation.suse.com/compliance/all/html/SLES-openscap/index.html#openscap-installation.

Start SCAP Workbench by invoking it in the terminal:
```
> scap-workbench
```
Depending on whether you are using SUSE Linux Enterprise 15 or SUSE Linux Enterprise 12, select either SLe15 or SLe12 from the Select content to load drop-down list. In this example procedure, we select SLe15.
Figure 1: SCAP Workbench—select content to load #
Click Load Content.
In the next window, titled Guide to the Secure Configuation of SUSE Linux Enterprise 15, perform the following steps:
1. From the Profile drop-down list, select the profile that you want to customize. In this example, we select DISA STIG for SUSE Linux Enterprise 15 (242). The number within parenthesis at the end of the profile name represents the number of rules that comprise your selected profile. For example, DISA STIG for SUSE Linux Enterprise 15 has 242 rules.
2. Optionally, if your target is a remote system, select the Remote Machine (over SSH) and provide necessary information.
  In this example procedure, we assume that the target system is your Local Machine.
  Figure 2: SCAP Workbench—DISA STIG profile #
3. Click Customize, edit the New Profile ID field if necessary, and click OK. The default New Profile ID provided by SCAP Workbench for the selected profile is xccdf_org.ssgproject.content_profile_stig_customized.
  Figure 3: SCAP Workbench—customize STIG profile #
In the next window titled Customizing "DISA STIG for SUSE Linux Enterprise 15 [CUSTOMIZED]"—SCAP Workbench, perform the following steps:
1. Override the default rules by selecting or deselecting them. For example, we select the checkbox next to the rule Limit Users' SSH Access to further harden the target system's access over SSH. You can select or deselect multiple rules.
  Tip: When unsure, read the rule's description
  Before selecting or deselecting the checkbox next to the rule, you can click the rule and read the Description provide at the right pane of the window.
  Figure 4: SCAP Workbench—select rule #
2. When you are sure about the override of rules, click OK.
On returning to the home window of SCAP Workbench, notice that the Customization field has changed to (unsaved changes).
Using the menu at the top left of the window, save the customization by clicking File › Save Customization Only and choosing the path of the tailoring file as /tmp/ssg-sle15-ds-tailoring.xml.
When saved, the Customization field displays the path to the tailoring file. In addition, the name of the new Profile contains the suffix (243), which indicates that an additional rule has been selected, as compared to the default of 242 rules.
Figure 5: SCAP Workbench—save tailoring file #

Optionally, inspect the tailoring file by opening it with a text editor of your choice. Based on the example override of rules, the tailoring file contains the following information.

<?xml version="1.0" encoding="UTF-8"?>
<xccdf:Tailoring xmlns:xccdf="http://checklists.nist.gov/xccdf/1.2" id="xccdf_scap-workbench_tailoring_default">
  <xccdf:benchmark href="/tmp/scap-workbench-sbgnfq/ssg-sle15-ds.xml"/>
  <xccdf:version time="2024-01-25T07:21:34">1</xccdf:version>
  <xccdf:Profile id="xccdf_org.ssgproject.content_profile_stig_customized" extends="xccdf_org.ssgproject.content_profile_stig">
    <xccdf:title xmlns:xhtml="http://www.w3.org/1999/xhtml" xml:lang="en-US" override="true">DISA STIG for SUSE Linux Enterprise 15 [CUSTOMIZED]</xccdf:title>
    <xccdf:description xmlns:xhtml="http://www.w3.org/1999/xhtml" xml:lang="en-US" override="true">This profile contains configuration checks that align to the
DISA STIG for SUSE Linux Enterprise 15 V1R4.</xccdf:description>
    <xccdf:select idref="xccdf_org.ssgproject.content_rule_sshd_limit_user_access" selected="true"/>
  </xccdf:Profile>
</xccdf:Tailoring>

5.1.2 Creating tailoring files using `autotailor` #

There might be deployments where installing a graphical software such as SCAP Workbench is not suitable. In even more sensitive deployments, the customization of a remote target machine over SSH from a client machine running SCAP Workbench might also not be an option.

In such situations, the autotailor command-line tool that comes bundled with the openscap-utils is a suitable choice. However, you must be sure of all the information necessary for creating the tailoring file.

To create a tailoring file with autotailor, use the following syntax:

> autotailor \
  --select RULE_ID1 \
  --unselect RULE_ID2 \
  --var-value VAR=VALUE3 \
  --output TAILORING_FILE4 \
  --new-profile-id NEW_PROFILE_ID5 \
  DS_FILENAME6 \
  BASE_PROFILE_ID7

1	`--select RULE_ID` adds a rule with RULE_ID. To select multiple rules, you can use this argument multiple times.
2	`--unselect RULE_ID` discards a rule with RULE_ID. To discard multiple rules, you can use this argument multiple times.
3	`--var-value VAR=VALUE` specifies modification of the XCCDF value in the form VARIABLE=VALUE.
4	TAILORING_FILE specifies the path of the tailoring file, which is the final output of the `autotailor` tool.
5	Specifies the ID of the new customized profile that you want to create.
6	Specifies the path to the SCAP source data stream that is tailored.
7	Specifies the original or base profile ID that you want to customize.

As an example, run the following command to generate a tailoring file that is similar to the one created by using SCAP Workbench in the previous section:

> autotailor \
  --select sshd_limit_user_access1 \
  --output /tmp/ssg-sle15-ds-tailoring.xml2 \
  --new-profile-id stig_customized3 \
  /usr/share/xml/scap/ssg/content/ssg-sle15-ds.xml4 \
  stig5

1	The ID of the Limit Users' SSH Access rule.
2	The path to the tailoring file, which is the output.
3	The ID of the new customized profile.
4	The path to the SCAP Security Guide content of the original STIG profile.
5	The name of the original STIG profile.

For more information about the autotailor tool, read its help information by running autotailor -h or refer to its man page by running man autotailor.

5.2 Scanning using a tailoring file #

You can use a tailoring file and the oscap command-line tool to scan and evaluate your target system based on a customized data stream.

To evaluate your target system using a tailoring file created earlier, perform the following steps:

List the profiles in the tailoring file by running the following command:

> oscap info /tmp/ssg-sle15-ds-tailoring.xml1
Document type: XCCDF Tailoring
Imported: TIMESTAMP
Benchmark Hint: /tmp/scap-workbench-VIdbAj/ssg-sle15-ds.xml
Profiles:
	Title: DISA STIG for SUSE Linux Enterprise 15 [CUSTOMIZED]
		Id: xccdf_org.ssgproject.content_profile_stig_customized

1	The path to the tailoring file created earlier, using either SCAP Workbench or `autotailor`.

Evaluate the target system based on the tailoring file by running the following command:

> oscap xccdf eval \
 --profile xccdf_org.ssgproject.content_profile_stig_customized1 \
 --tailoring-file /tmp/ssg-sle15-ds-tailoring.xml2 \
 --results /tmp/results.xml3 \
 /usr/share/xml/scap/ssg/content/ssg-sle15-ds.xml4

1	The ID reference of the new customized profile.
2	The path to the tailoring file created earlier.
3	The path to store the results of the evaluation in a machine-readable XML format.
4	The path to the SCAP Security Guide content for the standard STIG profile.

Note: Redirection of results

Apart from storing the results of the scan in an XML file, oscap displays the results of the evaluation in a human-readable format on the screen. If you redirect the stream of human-readable results to a file, the debug logs are displayed on the screen.

5.3 Applying a tailoring file #

After you create a tailoring file either using SCAP Workbench or autotailor, you must apply the custom profile to harden your target system. SUSE recommends using the ssg-apply command-line tool.

5.3.1 Applying tailoring file using `ssg-apply` #

ssg-apply is a command-line tool maintained by SUSE and is part of the ssg-apply package. You can install it by running the following command:

> sudo zypper install -y ssg-apply

For detailed information on ssg-apply, refer to /usr/share/doc/packages/ssg-apply/README.

To apply the tailoring file that you have already created using SCAP Workbench or autotailor, perform the following steps:

As a best practice, create a copy of /etc/ssg-apply/default.conf with the name /etc/ssg-apply/override.conf. The new file must contain information pointing to the overridden or customized configuration.
```
> sudo cp /etc/ssg-apply/default.conf /etc/ssg-apply/override.conf
```

Edit the /etc/ssg-apply/override.conf file to make its content similar to the following:

 #
 # This is the configuration file for the ssg-apply executable.
 #

 #
 # content-file - scap-security-guide content to be used for eval/remediation
 #
 content-file=/usr/share/xml/scap/ssg/content/ssg-sle15-ds.xml

 #
 # profile - profile as specified in content-file
 #
 profile=stig

 #
 # remediation setting - Take care before changing this setting to "yes",
 # as enabling remediation will likely make changes to the system.
 #
 remediate=no

 #
 # tailoring-file - tailoring file to disable specific rules
 #
 tailoring-file=/tmp/ssg-sle15-ds-tailoring.xml1

1	The path to the tailoring file created using SCAP Workbench or `autotailor`.

Apply the tailoring file by running the following command:
```
> ssg-apply
```
Optionally, after running ssg-apply, you can observe the following:
1. The output of OpenSCAP in the /var/log/ssg-apply/ssg-apply-TIMESTAMP.out files.
  For example, you can find the line number containing the mention of the Limit Users' SSH Access rule using the following command:
```
> cat /var/log/ssg-apply/ssg-apply-TIMESTAMP.out | grep -n sshd_limit_user_access
1180:xccdf_org.ssgproject.content_rule_sshd_limit_user_access
```
  Then you can locate the lines containing the status of the Limit Users' SSH Access rule in the /var/log/ssg-apply/ssg-apply-TIMESTAMP.out file:
```
1179	Limit Users' SSH Access
1180	xccdf_org.ssgproject.content_rule_sshd_limit_user_access
1181	CCE-91343-4
1182	faillt
```
2. The debug logs in the /var/log/ssg-apply/ssg-apply-TIMESTAMP.log files.

6 Working with checklists in DISA STIG Viewer #

DISA STIG Viewer is a Java-based graphical user interface to open content and create checklists for managing the STIG security settings on your system or network.

6.1 Installing DISA STIG Viewer #

The DISA STIG Viewer application is available as a ZIP archive from https://public.cyber.mil/stigs/stig-viewing-tools/. Download the Linux version of the DISA STIG Viewer.

To install DISA STIG Viewer, unpack the ZIP archive. In the directory with the extracted files, start the DISA STIG Viewer with ./STIGViewer.

Figure 6: DISA STIG Viewer—main window #

6.2 Using DISA STIG Viewer #

To view a Security Technical Implementation Guide for SUSE Linux Enterprise, you have the following two options.

Procedure 1: Importing from a ZIP archive #

You can download a ZIP archive with the STIG checklist for your SUSE Linux Enterprise version (12 or 15).

Go to https://public.cyber.mil/stigs/downloads/.
In the Search field, enter SUSE and select and download the Security Technical Implementation Guide checklist that matches the SUSE Linux Enterprise system you want to harden.
In DISA STIG Viewer, click File › Import STIG and select the downloaded ZIP archive.
Enable the checkbox beneath the entry in the STIG Explorer panel to show the individual rules in the middle panel and details for each rule on the right-hand side.

Procedure 2: Importing from XCCDF XML #

Use the oscap command-line tool to generate an XCCDF XML file that can be opened with DISA STIG Viewer.

> sudo oscap xccdf eval1 \
      --profile stig2 \
      --stig-viewer /tmp/results_stig.xml3 \
      /usr/share/xml/scap/ssg/content/ssg-sle15-ds.xml4

1	Calls the `oscap xccdf` module and tells it to perform an evaluation (vulnerability scan).
2	Tells `oscap` to use the `stig` profile for the scan.
3	Saves the results of the evaluation to /tmp/results_stig.xml. This is an XCCDF XML file that can be imported into DISA STIG Viewer.
4	Specifies the `SCAP Security Guide` policy file to use. In this example, we use a policy file in the `DataStream` format that applies to SUSE Linux Enterprise code 15.

In DISA STIG Viewer, click File › Import STIG and select the XML file you generated.
Enable the checkbox beneath the entry in the STIG Explorer panel to show the individual rules in the middle panel.

For more information about DISA STIG Viewer, refer to the comprehensive STIG Viewer 2.x User Guide, which is available for download at https://public.cyber.mil/stigs/downloads/, or the README file that you can access from within DISA STIG Viewer by selecting Help › View Readme.

7 Legal Notice #

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 trademarks, see https://www.suse.com/company/legal/. All third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.

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

8 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 non-commercially. 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 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 non-commercially, 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:

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.
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.
State on the Title page the name of the publisher of the Modified Version, as the publisher.
Preserve all the copyright notices of the Document.
Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
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.
Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
Include an unaltered copy of this License.
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.
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.
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.
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.
Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.
Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.
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 https://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.