SUSE Virtualization with Portworx Enterprise by Everpure in a Two-Node with Arbiter Topology #

Organizations increasingly need to extend their application environments beyond centralized data centers to edge and far-edge locations, where infrastructure constraints, operational complexity, and cost sensitivity are significantly higher. These environments require solutions that deliver enterprise-grade availability and performance within a minimal hardware footprint. This reference configuration addresses these challenges by providing a consolidated architecture that runs both virtualized and containerized workloads on a unified platform, at the edge. This eliminates the separate infrastructure stacks traditional approaches require, reducing costs, operational overhead, and governance complexity while maintaining resilience and scalability.

This document presents a validated reference architecture that combines SUSE Virtualization, Portworx by Everpure, and Supermicro Compact Edge Servers technologies to support modern edge use cases. By leveraging a Two-Node with Arbiter (TNA) topology, the solution delivers high availability using only two primary nodes and a lightweight arbiter node, reducing infrastructure requirements without compromising business continuity.

Organizations are increasingly extending their infrastructure to edge and distributed environments, where they must operate with limited resources while maintaining high availability and consistent performance. These environments introduce challenges related to infrastructure footprint, operational complexity, and the need to efficiently support both virtualized and containerized workloads.

This solution addresses these challenges by providing a unified platform based on SUSE Virtualization, Portworx by Everpure, and Supermicro Compact Edge Servers. This Two-Node with Arbiter (TNA) architecture enables organizations to reduce infrastructure requirements while maintaining resilience and simplifying operations, making it well suited for cost-efficient edge and far-edge deployments.

The solution integrates SUSE Virtualization with Portworx Enterprise by Everpure on a Kubernetes-based platform to provide a unified infrastructure for running both virtualized and containerized workloads in edge and far-edge environments. It uses a Two-Node with Arbiter (TNA) topology, consisting of two worker nodes that provide compute and storage capabilities and serve as Kubernetes control-plane nodes, and a third arbiter (witness) node that participates in cluster quorum without hosting application workloads or storing data.

SUSE Virtualization enables the deployment and management of virtual machines alongside containerized applications within the same platform. Portworx Enterprise by Everpure provides container-native storage services, including persistent volumes, data replication, and high availability storage. Supporting this, Kubernetes orchestrates the deployment, scheduling, and lifecycle management of both workloads and storage services across the cluster.

Infrastructure hardware consists of compact edge servers with local NVMe storage and integrated networking, providing a resilient platform for deploying virtualized and containerized workloads in edge and far-edge environments.

Figure 1: SUSE Virtualization and Portworx Two Node with Arbiter Topology #

 

Note

TNA Quorum Logic: Portworx requires a majority of key-value database (KVDB) members to agree before making cluster state changes.

In a TNA topology, a quorum of two is always achievable as long as either of the following conditions is met:

• Both storage nodes are functioning.

• One storage node and the arbiter node are functioning.

This quorum logic enables the cluster to survive a single storage node failure without split-brain scenarios or data loss.

The TNA topology introduces two implementation details that must be addressed.

Portworx Enterprise by Everpure is a cloud-native storage and data management platform for Kubernetes. It offers native Container Storage Interface (CSI) integration, providing drivers that expose block and file storage systems to workloads running on Kubernetes, such as the containers and virtual machines in the SUSE Virtualization environment. The Portworx Operator is designed to efficiently manage the installation and upgrade workflow of all Portworx components. The following pages provide guidance for configuring and installing Portworx Enterprise via the Portworx Operator.

5.2 Preparing for Portworx installation #

 

Before deploying the Portworx Operator, three preparatory tasks must be completed on each storage worker node: partitioning the disks, wiping residual file system partition signatures, and installing the Augeas binary. These steps address hardware-level disk layout requirements and OS immutability, respectively.

5.2.1 Partitioning the disks #

 

Portworx requires dedicated partitions on each data disk, one small partition for internal KVDB metadata and one large partition for storage pool data. A third minimal partition is created at the start of the disk as a protective alignment buffer. This must be performed on the designated data disk of each storage worker node before Portworx installation.

1. Create the three partitions using parted.

   parted /dev/nvme1n1 \
       mklabel gpt \
       unit MiB \
       mkpart primary 1 2 \
       mkpart primary 2 65538 \
       mkpart primary 65538 100% \
       print \
       quit

2. Inform the kernel of the new partition table.

   partprobe /dev/nvme1n1

3. Verify the partition layout with lsblk.

   lsblk /dev/nvme1n1

   You should see three partitions:

   NAME                               MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
   nvme1n1                            259:0    0 894.3G  0 disk
   ├─nvme1n1p1                        259:1    0     1M  0 part
   ├─nvme1n1p2                        259:2    0    64G  0 part
   └─nvme1n1p3                        259:3    0 830.3G  0 part

This partition layout maps directly to the StorageCluster spec.nodes configuration.

Important

Repeat this partitioning procedure on the designated data disk of each of the other nodes before proceeding. Do not perform this procedure on the OS boot disk. Verify the correct device with lsblk before executing parted.

5.2.2 Wiping partition signatures #

 

After partitioning, wipe any residual file system signatures from the p2 and p3 partitions to ensure Portworx initializes them cleanly.

wipefs -a /dev/nvme1n1p2
wipefs -a /dev/nvme1n1p3

Confirm both partitions are clean (empty output from wipefs indicates no signatures remain):

wipefs /dev/nvme1n1p2 && echo "P2 CLEAN"
P2 CLEAN

wipefs /dev/nvme1n1p3 && echo "P3 CLEAN"
P3 CLEAN

5.2.3 Installing Augeas #

 

SUSE Virtualization features SUSE Linux Micro as the host operating system. This provides an immutable root file system for added security and stability. During installation, the Portworx px-storev2 engine performs a runtime dependency check that attempts to install the augeas package. Since transactional-update is not supported in SUSE Virtualization and /usr/bin is read-only, this action fails and Portworx pods enter a CrashLoopBackOff state.

Resolve this by manually extracting the augeas binary from an openSUSE Tumbleweed RPM and installing it into /usr/local/bin, which is writable on SUSE Virtualization and already included in the system PATH variable.

1. Download the Augeas RPM into a temporary directory.

   cd /tmp
   
   curl -LO \
   https://download.opensuse.org/tumbleweed/repo/oss/x86_64/augeas-<version>.x86_64.rpm

   Be sure to replace <version> in the above command to match the augeas package name.

2. Extract the RPM contents.

   mkdir -p /tmp/augeas-extract
   
   cd /tmp/augeas-extract
   
   rpm2cpio /tmp/augeas-<version>.x86_64.rpm | cpio -idm 2>/dev/null

3. Install the binaries into the writable path.

   for b in augtool augmatch augparse augprint fadot; do
     [ -f /tmp/augeas-extract/usr/bin/$b ] \
       && install -m 0755 /tmp/augeas-extract/usr/bin/$b /usr/local/bin/$b \
       && echo "Installed: $b" \
       || echo "Skipped: $b"
   done
   Installed: augtool

4. Verify the installation.

   which augtool && augtool --version && echo "=== SUCCESS ==="

   /usr/local/bin/augtool
   augtool 1.14.1
   === SUCCESS ===

Important

This installation must be repeated on both storage nodes and the arbiter node before applying the Portworx Operator. The binaries persist across pod restarts but may need to be reinstalled after a SUSE Virtualization OS upgrade. Be sure to include this step in your upgrade runbook.

You can check that the Portworx cluster is operational in the TNA topology with the steps below.

Note

The pxctl status output reports three online Portworx cluster, including the arbiter node. However, the arbiter is a storageless witness node that participates only in KVDB quorum and metadata services. Storage capacity is provided solely by harvone and harvtwo.

6.1 Resilience validation #

 

Validate TNA high availability by testing the following two failure scenarios with active VM workloads.

6.1.1 Scenario 1: Storage Node Failure with Active VMs #

 

1. Create six, Portworx-backed VMs (vm1, vm2, …, vm6) distributed across both nodes, harvone and harvtwo.

2. Launch a heartbeat logger in a VM (vm1) on harvone so that it writes to the Portworx-backed volume every second.

3. Shut down harvone abruptly.

   harvone:~ # shutdown -h now

   When Kubernetes detects harvone as NotReady, it triggers live migration for all VMs that were running on it. Within approximately 2 minutes, you should see all VMs are Running on harvtwo.

4. Verify that harvone is marked as Offline.

   harvetwo:~ # pxctl status

   Status: PX is operational
   Total Nodes: 3 node(s) with storage (2 online)
   
   harvtwo    Online   Up (This node)
   arbiter    Online   No Storage
   harvone    Offline  Down

5. Verify that all VMs are running on harvtwo.

   harvetwo:~ # kubectl get vmi -A -o wide

   NAMESPACE   NAME        PHASE     IP           NODENAME   READY   LIVE-MIGRATABLE
   default     vm1        Running   10.52.1.72   harvtwo    True    True
   default     vm2        Running   10.52.1.73   harvtwo    True    True
   default     vm3        Running   10.52.1.63   harvtwo    True    True
   default     vm4        Running   10.52.1.61   harvtwo    True    True
   default     vm5        Running   10.52.1.69   harvtwo    True    True
   default     vm6        Running   10.52.1.66   harvtwo    True    True

6. Check the heartbeat log from inside vm1 to determine the observed I/O interruption across the entire failover event.

   vm1:~ # awk '...' /root/hbtest/hb.log

   Downtime: 1 seconds
   From 1778873153 to 1778873155
   
   TOTAL downtime: 1 seconds

Note

In the authors’ validation testing, the full recovery timeline from node failure until all VMs were confirmed as Running and Ready on harvtwo was approximately 2 minutes.

6.1.2 Scenario 2: Cascading Failure: Arbiter Then Storage Node #

 

1. With the cluster fully healthy and all six VMs running across both nodes, shut down the arbiter node (arbiter) first. Verify that both storage nodes remain operational and the cluster continues serving workloads normally the two storage nodes together hold majority quorum without the arbiter.

   harvone:~ # kubectl get nodes -o wide

   NAME        STATUS     ROLES                AGE   VERSION
   arbiter     NotReady   etcd                 11d   v1.34.2+rke2r1
   harvone     Ready      control-plane,etcd   11d   v1.34.2+rke2r1
   harvtwo     Ready      control-plane,etcd   11d   v1.34.2+rke2r1

2. With the arbiter already offline, launch a heartbeat logger inside a VM (vm1) running on harvone so that it writes to its Portworx-backed volume every second.

3. Now shut down harvone abruptly, creating the cascading failure condition.

   harvone:~ # shutdown -h now

4. When Kubernetes detects harvone as NotReady, it triggers live migration for all VMs that were running on it. Verify that all VMs are Running on harvtwo.

   harvetwo:~ # kubectl get vmi -A -o wide

   NAMESPACE   NAME        PHASE     IP            NODENAME   READY   LIVE-MIGRATABLE
   default     vm1         Running   10.52.1.112   harvtwo    True    True
   default     vm2         Running   10.52.1.113   harvtwo    True    True
   default     vm3         Running   10.52.1.110   harvtwo    True    True
   default     vm4         Running   10.52.1.111   harvtwo    True    True
   default     vm5         Running   10.52.1.109   harvtwo    True    True
   default     vm6         Running   10.52.1.66    harvtwo    True    True

5. Verify that Portworx remains operational on harvtwo with harvone shown as Offline.

   harvetwo:~ # pxctl status

   Status: PX is operational
   Total Nodes: 3 node(s) with storage (2 online)
   harvtwo    Online   Up (This node)
   arbiter  Offline  No Storage
   harvone    Offline  Down

6. Check the heartbeat log from inside vm1 to determine the observed I/O interruption across the entire cascading failure and recovery window.

   vm1:~ # awk '...' /root/hbtest/hb.log

   Downtime: 1 seconds
   Downtime: 1 seconds
   Downtime: 1 seconds
   Downtime: 1 seconds
   Downtime: 1 seconds
   Downtime: 1 seconds
   Downtime: 1 seconds
   Downtime: 1 seconds
   TOTAL downtime: 8 seconds

Note

In the authors' validation testing, the total observed I/O interruption across the cascading failure event was 8 seconds. The additional interruption compared to Scenario 1 reflects the time required for etcd to detect the second failure and for harvtwo to re-establish leadership without the arbiter.

During this period, the Kubernetes API server briefly reported etcdserver: no leader while leadership was being re-established. This is expected behaviour in a cascading failure scenario. Once harvtwo assumed sole etcd authority, the API server recovered and all VM workloads resumed normally on harvtwo. The two storage nodes together hold majority quorum (2 of 3 KVDB members) and can continue operating without the arbiter.

Lifecycle management is an important consideration to ensure continuous platform interoperability, maintain data availability for stateful workloads, and close critical security gaps. The components of this solution run natively on a unified Kubernetes-based control plane, making coordinated lifecycle management essential for maintaining compatibility and operational stability.

Proper lifecycle management impacts this solution across several key operational areas:

This document provides a reference design with step-by-step, implementation guidance for integrating SUSE Virtualization and Portworx Enterprise by Everpure in a Two-Node with Arbiter (TNA) topology on Supermicro Compact Edge Servers. The architecture delivers highly available, enterprise-grade storage at the edge using only two full storage nodes and one lightweight arbiter node to dramatically reduce hardware costs while preserving production-level resilience.

Organizations extending workloads beyond centralized data centers face a familiar dilemma: how do you maintain high availability, minimize hardware expenditure, and operate with limited on-site expertise. Traditional storage HA mandates at least three full storage nodes. The TNA architecture dissolves this constraint by leveraging an arbiter node, carrying no workload data while participating only in quorum decisions. This can dramatically cut hardware costs at scale while retaining full fault-tolerance.

By combining SUSE Virtualization, Portworx, and Supermicro Compact Edge Servers in this TNA topology, organizations create a scalable, resilient, and cost-efficient solution for edge and other use cases.

The following sections provide additional information and resources.

12.1 Sample files and output #

 

12.1.1 Sample StorageCluster manifest for TNA #

 

apiVersion: core.libopenstorage.org/v1
kind: StorageCluster
metadata:
  name: px-cluster-tna-gk
  namespace: portworx
  annotations:
    portworx.io/install-source: "https://install.portworx.com/3.6?operator=true&mc=false&kbver=1.34.2&ns=portworx&b=true&kvdbtls=true&certmgr=true&dmthin=true&node1Name=harveone&node1Device=%2Fdev%2Fnvme0n1&node1ClusterDomain=Node1&node2Name=harvetwo&node2Device=%2Fdev%2Fnvme1n1&node2ClusterDomain=Node2&arbiterNode=arbiter&kvdbDevice=%2Fdev%2Fnvme1n1&node3ClusterDomain=witness&iop=6&c=px-cluster-tna&stork=true&csi=true&mon=true&aut=true&tel=true&st=k8s&promop=true"
    portworx.io/health-check: "skip"
    portworx.io/preflight-check: "skip"
    portworx.io/misc-args: "-rt_opts small_conf=1 -T px-storev2"

spec:
  image: docker.io/portworx/oci-monitor:3.6.0
  imagePullPolicy: Always

  kvdb:
    internal: true
    enableTLS: false

  secretsProvider: k8s

  nodes:
    - clusterDomain: "Node1"
      selector:
        nodeName: "harvone"
      storage:
        systemMetadataDevice: /dev/nvme1n1p1
        devices:
          - /dev/nvme1n1p2
        useAll: false

    - clusterDomain: "Node2"
      selector:
        nodeName: "harvtwo"
      storage:
        systemMetadataDevice: /dev/nvme1n1p1
        devices:
          - /dev/nvme1n1p2
        useAll: false

    - clusterDomain: "witness"
      selector:
        nodeName: "arbiter"
      storage:
        kvdbDevice: /dev/nvme1n1p2
        useAll: false

  placement:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
          - matchExpressions:
              - key: px/enabled
                operator: NotIn
                values:
                  - "false"
    tolerations:
      - key: "node-role.kubernetes.io/etcd"
        operator: "Exists"
        effect: "NoExecute"
      - key: "node-role.kubernetes.io/control-plane"
        operator: "Exists"
        effect: "NoSchedule"
      - key: "node-role.kubernetes.io/master"
        operator: "Exists"
        effect: "NoSchedule"

  stork:
    enabled: true
    args:
      webhook-controller: "true"

  autopilot:
    enabled: true
    prometheusAlerts: true
    providers:
      - name: default
        type: prometheus
        params:
          url: http://px-prometheus:9090

  runtimeOptions:
    default-io-profile: "6"

  csi:
    enabled: true
    installSnapshotController: true

  monitoring:
    telemetry:
      enabled: true
      metricsCollector:
        enabled: true
    prometheus:
      enabled: true
      exportMetrics: true

  certManager:
    enabled: false

  deleteStrategy:
    type: UninstallAndWipe
    ignoreVolumes: true

  revisionHistoryLimit: 10
  startPort: 9001

  updateStrategy:
    rollingUpdate:
      disruption:
        allow: true
      maxUnavailable: 1
    type: RollingUpdate

Note

The sample configuration explicitly defines the storage devices used by each node by setting useAll: false and specifying the metadata and data devices. If you want Portworx to automatically consume all available storage devices on a node, set useAll: true and omit the explicit device list. Review the available storage devices carefully before enabling this option.

12.2 Server hardware specifications #

 

All three nodes in this reference deployment are built on the Supermicro SYS-E403-14B-FRN2T, a compact IoT/Edge SuperServer from Supermicro’s Compact Edge Server product line. This platform was selected for its short-depth form factor, NVMe storage support, and suitability for edge and far-edge environments where rack space and power budgets are constrained.

Component	Specification	Qty	Notes
Server Platform	Supermicro SYS-E403-14B-FRN2T	3	2x Storage Workers (harveone, harvetwo) + 1x Arbiter (arbiter)
Form Factor	Compact / Short-Depth (10.5" x 4.62" x 16")	—	Wall-mountable; suitable for shallow racks and edge cabinets
CPU	Intel Xeon 6700/6500 Series (P-core or E-core)	1/node	Up to 300W TDP with air cooling
RAM	DDR5 RDIMM, 8 DIMM slots per node	—	Up to 2TB per node; configured per workload requirements
NVMe Drive Bays	2x Front Hot-swap 2.5" NVMe	2/node	One bay for OS; one bay for Portworx data disk
SATA Drive Bays	2x Internal Fixed 2.5" SATA	2/node	Available for additional storage; not used in this deployment
Network Ports	2x 10GbE RJ45 LAN	2/node	One port for cluster/storage traffic; one for management
Management Port	Dedicated IPMI / BMC	1/node	Out-of-band management for remote recovery at edge sites
PCIe Expansion	3x PCIe 5.0 x16 FHFL	—	Available for GPU/NIC expansion; not used in this deployment
Display / USB	1x VGA, 4x USB 3.2 Gen1, 2x USB 2.0	—	Local console access during initial setup

Note

The arbiter node participates only in KVDB quorum and does not host workloads or contribute to storage capacity. Therefore, it can be sized smaller than the storage nodes. However, it must still meet the minimum supported hardware requirements for SUSE Virtualization.

Copyright © 2006–2026 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".

SUSE, the SUSE logo and YaST are registered trademarks of SUSE LLC in the United States and other countries. For SUSE trademarks, see https://www.suse.com/company/legal/.

Linux is a registered trademark of Linus Torvalds. All other names or trademarks mentioned in this document may be trademarks or registered trademarks of their respective owners.

Documents published as part of the series SUSE Technical Reference Documentation have been contributed voluntarily by SUSE employees and third parties. They are meant to serve as examples of how particular actions can be performed. They have been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. SUSE cannot verify that actions described in these documents do what is claimed or whether actions described have unintended consequences. SUSE LLC, its affiliates, the authors, and the translators may not be held liable for possible errors or the consequences thereof.

Copyright © 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.

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.

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.

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.

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.

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:

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.

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

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.

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.

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.

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.

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.

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.