Merge pull request #1996 from ogayot/2063124-document

DESIGN.md: document what happens to the API when the server restarts

.github/workflows/automatic-doc-checks.yml

@@ -0,0 +1,22 @@
+name: Main Documentation Checks
+
+on:
+  pull_request:
+    paths:
+      - 'doc/**'
+  push:
+    paths:
+      - 'doc/**'
+  workflow_dispatch:
+    paths:
+      - 'doc/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true  
+
+jobs:
+  documentation-checks:
+    uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
+    with:
+      working-directory: 'doc'

.github/workflows/ci.yaml

@@ -1,6 +1,12 @@
 name: CI
 
-on: [push, pull_request]
+on:
+  push:
+    paths-ignore:
+      - 'doc/**'
+  pull_request:
+    paths-ignore:
+      - 'doc/**'
 
 jobs:
   test:
@@ -9,10 +15,9 @@ jobs:
       fail-fast: false
       matrix:
         image:
-          - ubuntu-daily:focal
           - ubuntu-daily:jammy
-          - ubuntu-daily:lunar
           - ubuntu-daily:mantic
+          - ubuntu-daily:noble
     steps:
     - uses: actions/checkout@v4
     - name: run
@@ -24,15 +29,15 @@ jobs:
       fail-fast: false
       matrix:
         image:
-          - ubuntu-daily:jammy    # match the core snap we're running against
-          - ubuntu-daily:mantic   # latest
+          - ubuntu-daily:jammy   # match the core snap we're running against
+          # - ubuntu-daily:noble   # latest
     steps:
     - uses: actions/checkout@v4
     - name: lint
       run: sudo ./scripts/test-in-lxd.sh ${{ matrix.image }} "make lint"
 
   format-black:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-20.04
     steps:
       - uses: actions/checkout@v4
       - uses: psf/black@stable
@@ -41,7 +46,7 @@ jobs:
           src: "console_conf subiquity subiquitycore system_setup"
 
   format-isort:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-20.04
     steps:
       - uses: actions/checkout@v4
       - uses: isort/isort-action@v1
@@ -52,7 +57,7 @@ jobs:
   static-typing:
     # In this job, we compare the output of mypy before and after the PR.
     if: github.event_name == 'pull_request'
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-22.04  # minimimum 22.04 for python3-typeshed
     steps:
       - name: Install mypy and typeshed
         run: sudo apt-get install -y python3-mypy python3-typeshed

.github/workflows/snap.yaml

@@ -1,10 +1,16 @@
-name: CI
+name: Snap
 
-on: [push, pull_request]
+on:
+  push:
+    paths-ignore:
+      - 'doc/**'
+  pull_request:
+    paths-ignore:
+      - 'doc/**'
 
 jobs:
   snap-build:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-20.04
     steps:
     - uses: actions/checkout@v4
     - uses: snapcore/action-build@v1

.pre-commit-config.yaml

@@ -1,11 +1,21 @@
-files: "(console_conf|subiquity|subiquitycore|system_setup)"
+files: "(console_conf|subiquity|subiquitycore|system_setup|doc)"
 repos:
   - repo: https://github.com/psf/black
     rev: 23.7.0
     hooks:
       - id: black
+        files: "(console_conf|subiquity|subiquitycore|system_setup)"
   - repo: https://github.com/pycqa/isort
     rev: 5.12.0
     hooks:
       - id: isort
         name: isort
+        files: "(console_conf|subiquity|subiquitycore|system_setup)"
+  - repo: local
+    hooks:
+      - id: doc-spelling
+        name: doc-spelling
+        language: system
+        entry: make -C doc spelling
+        files: "doc/.*rst"
+        pass_filenames: false

CONTRIBUTING.md

@@ -1,13 +1,40 @@
 
-Thank you for considering a contribution to Subiquity.  Here's what we like to
-see:
+Thank you for considering a contribution to Subiquity.  Here are some things to
+note:
 
-* Contributors will need to have signed the
-  [CLA](https://ubuntu.com/legal/contributors/agreement).
-* Format, lint, unit, integration, and API tests should be passing.
-  * format - either run `make format` or `pre-commit install`.
-    See [pre-commit](https://pre-commit.com/#install) for more details on that
-    tool.
+## Code of Conduct
+
+This project is subject to the [Ubuntu Code of Conduct](https://ubuntu.com/community/code-of-conduct)
+to foster an open and welcoming place to contribute. By participating in the
+project (in the form of code contributions, issues, comments, and other
+activities), you agree to abide by its terms.
+
+## Contributor License Agreement
+
+This project is subject to the
+[Canonical contributor license agreement](https://ubuntu.com/legal/contributors),
+please make sure you have [signed it](https://ubuntu.com/legal/contributors/agreement)
+before (or shortly after) submitting your first pull request.
+
+A github workflow will verify that your GitHub username or email address is
+associated with a contributor license agreement signature, but it may take
+some time after your initial signature for the check to see it. If you're
+part of [@canonical](https://github.com/canonical), you will also need to make
+sure your canonical.com email address is associated with your GitHub account.
+
+## Bugs
+Bugs are tracked on [Launchpad](https://bugs.launchpad.net/subiquity). It is
+recommended you use `ubuntu-bug` (or similar) to let apport collect relevant
+logs which are helpful for the debug process, instead of filing one directly.
+
+## Pull Requests
+Changes to this project should be proposed as pull requests on GitHub at:
+[https://github.com/canonical/subiquity/](https://github.com/canonical/subiquity/)
+
+
+ Format, lint, unit, integration, and API tests should be passing.
+  * format - run either `make format` or `pre-commit install`.
+    * Install pre-commit with `sudo apt install pre-commit`.
   * all the rest - `make lint check`.
-    Prerequisites for running these locally can be installed with
+    * Prerequisites for running these locally can be installed with
     `make aptdeps`.

DESIGN.md

@@ -171,6 +171,12 @@ which will not return until the check has completed (or failed). In a similar
 vein, `meta.status.GET()` takes an argument indicating what the client
 thinks the application state currently is and will block until that changes.
 
+In some scenarios (e.g., after updating the installer), the server process will
+automatically restart. In such an event, every open socket will automatically
+get closed. As a consequence, ongoing long polling requests will not receive a
+response. To handle this scenario gracefully, the client should catch the
+error and retry the long polling request after a short time.
+
 ### Examples and common patterns
 
 Adding a typical screen requires:
@@ -270,10 +276,10 @@ class ExampleController(SubiquityTuiController):
         return ExampleView(self, thing)
 
     def cancel(self):
-        self.app.prev_screen()
+        self.app.request_prev_screen()
 
     def done(self, thing):
-        self.app.next_screen(self.endpoint.POST(thing))
+        self.app.request_next_screen(self.endpoint.POST(thing))
 ```
 
 Setting `endpoint_name` means that self.client gets set to an implementation of
@@ -521,7 +527,7 @@ Tests (and lint checks) are run by github actions using lxd.  See
 `.github/workflows/build.yaml` and `./scripts/test-in-lxd.sh` and so
 on.
 
-For "real" testing, you need to make a snap (`snapcraft snap`), mash
+For "real" testing, you need to make a snap (`snapcraft pack`), mash
 it into an existing ISO using `./scripts/inject-subiquity-snap.sh`,
 and boot the result in a VM. There is an even hackier pair of scripts
 (`./scripts/slimy-update-snap.sh` and

LICENSE

@@ -1,662 +1,8 @@
-                    GNU AFFERO GENERAL PUBLIC LICENSE
-                       Version 3, 19 November 2007
+The subiquity/ directory is licensed under the GNU Affero General Public
+License version 3 or later.
 
- Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-                            Preamble
-
-  The GNU Affero General Public License is a free, copyleft license for
-software and other kinds of works, specifically designed to ensure
-cooperation with the community in the case of network server software.
-
-  The licenses for most software and other practical works are designed
-to take away your freedom to share and change the works.  By contrast,
-our General Public Licenses are intended to guarantee your freedom to
-share and change all versions of a program--to make sure it remains free
-software for all its users.
-
-  When we speak of free software, we are referring to freedom, not
-price.  Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-them if you wish), that you receive source code or can get it if you
-want it, that you can change the software or use pieces of it in new
-free programs, and that you know you can do these things.
-
-  Developers that use our General Public Licenses protect your rights
-with two steps: (1) assert copyright on the software, and (2) offer
-you this License which gives you legal permission to copy, distribute
-and/or modify the software.
-
-  A secondary benefit of defending all users' freedom is that
-improvements made in alternate versions of the program, if they
-receive widespread use, become available for other developers to
-incorporate.  Many developers of free software are heartened and
-encouraged by the resulting cooperation.  However, in the case of
-software used on network servers, this result may fail to come about.
-The GNU General Public License permits making a modified version and
-letting the public access it on a server without ever releasing its
-source code to the public.
-
-  The GNU Affero General Public License is designed specifically to
-ensure that, in such cases, the modified source code becomes available
-to the community.  It requires the operator of a network server to
-provide the source code of the modified version running there to the
-users of that server.  Therefore, public use of a modified version, on
-a publicly accessible server, gives the public access to the source
-code of the modified version.
-
-  An older license, called the Affero General Public License and
-published by Affero, was designed to accomplish similar goals.  This is
-a different license, not a version of the Affero GPL, but Affero has
-released a new version of the Affero GPL which permits relicensing under
-this license.
-
-  The precise terms and conditions for copying, distribution and
-modification follow.
-
-                       TERMS AND CONDITIONS
-
-  0. Definitions.
-
-  "This License" refers to version 3 of the GNU Affero General Public License.
-
-  "Copyright" also means copyright-like laws that apply to other kinds of
-works, such as semiconductor masks.
-
-  "The Program" refers to any copyrightable work licensed under this
-License.  Each licensee is addressed as "you".  "Licensees" and
-"recipients" may be individuals or organizations.
-
-  To "modify" a work means to copy from or adapt all or part of the work
-in a fashion requiring copyright permission, other than the making of an
-exact copy.  The resulting work is called a "modified version" of the
-earlier work or a work "based on" the earlier work.
-
-  A "covered work" means either the unmodified Program or a work based
-on the Program.
-
-  To "propagate" a work means to do anything with it that, without
-permission, would make you directly or secondarily liable for
-infringement under applicable copyright law, except executing it on a
-computer or modifying a private copy.  Propagation includes copying,
-distribution (with or without modification), making available to the
-public, and in some countries other activities as well.
-
-  To "convey" a work means any kind of propagation that enables other
-parties to make or receive copies.  Mere interaction with a user through
-a computer network, with no transfer of a copy, is not conveying.
-
-  An interactive user interface displays "Appropriate Legal Notices"
-to the extent that it includes a convenient and prominently visible
-feature that (1) displays an appropriate copyright notice, and (2)
-tells the user that there is no warranty for the work (except to the
-extent that warranties are provided), that licensees may convey the
-work under this License, and how to view a copy of this License.  If
-the interface presents a list of user commands or options, such as a
-menu, a prominent item in the list meets this criterion.
-
-  1. Source Code.
-
-  The "source code" for a work means the preferred form of the work
-for making modifications to it.  "Object code" means any non-source
-form of a work.
-
-  A "Standard Interface" means an interface that either is an official
-standard defined by a recognized standards body, or, in the case of
-interfaces specified for a particular programming language, one that
-is widely used among developers working in that language.
-
-  The "System Libraries" of an executable work include anything, other
-than the work as a whole, that (a) is included in the normal form of
-packaging a Major Component, but which is not part of that Major
-Component, and (b) serves only to enable use of the work with that
-Major Component, or to implement a Standard Interface for which an
-implementation is available to the public in source code form.  A
-"Major Component", in this context, means a major essential component
-(kernel, window system, and so on) of the specific operating system
-(if any) on which the executable work runs, or a compiler used to
-produce the work, or an object code interpreter used to run it.
-
-  The "Corresponding Source" for a work in object code form means all
-the source code needed to generate, install, and (for an executable
-work) run the object code and to modify the work, including scripts to
-control those activities.  However, it does not include the work's
-System Libraries, or general-purpose tools or generally available free
-programs which are used unmodified in performing those activities but
-which are not part of the work.  For example, Corresponding Source
-includes interface definition files associated with source files for
-the work, and the source code for shared libraries and dynamically
-linked subprograms that the work is specifically designed to require,
-such as by intimate data communication or control flow between those
-subprograms and other parts of the work.
-
-  The Corresponding Source need not include anything that users
-can regenerate automatically from other parts of the Corresponding
-Source.
-
-  The Corresponding Source for a work in source code form is that
-same work.
-
-  2. Basic Permissions.
-
-  All rights granted under this License are granted for the term of
-copyright on the Program, and are irrevocable provided the stated
-conditions are met.  This License explicitly affirms your unlimited
-permission to run the unmodified Program.  The output from running a
-covered work is covered by this License only if the output, given its
-content, constitutes a covered work.  This License acknowledges your
-rights of fair use or other equivalent, as provided by copyright law.
-
-  You may make, run and propagate covered works that you do not
-convey, without conditions so long as your license otherwise remains
-in force.  You may convey covered works to others for the sole purpose
-of having them make modifications exclusively for you, or provide you
-with facilities for running those works, provided that you comply with
-the terms of this License in conveying all material for which you do
-not control copyright.  Those thus making or running the covered works
-for you must do so exclusively on your behalf, under your direction
-and control, on terms that prohibit them from making any copies of
-your copyrighted material outside their relationship with you.
-
-  Conveying under any other circumstances is permitted solely under
-the conditions stated below.  Sublicensing is not allowed; section 10
-makes it unnecessary.
-
-  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
-
-  No covered work shall be deemed part of an effective technological
-measure under any applicable law fulfilling obligations under article
-11 of the WIPO copyright treaty adopted on 20 December 1996, or
-similar laws prohibiting or restricting circumvention of such
-measures.
-
-  When you convey a covered work, you waive any legal power to forbid
-circumvention of technological measures to the extent such circumvention
-is effected by exercising rights under this License with respect to
-the covered work, and you disclaim any intention to limit operation or
-modification of the work as a means of enforcing, against the work's
-users, your or third parties' legal rights to forbid circumvention of
-technological measures.
-
-  4. Conveying Verbatim Copies.
-
-  You may convey verbatim copies of the Program's source code as you
-receive it, in any medium, provided that you conspicuously and
-appropriately publish on each copy an appropriate copyright notice;
-keep intact all notices stating that this License and any
-non-permissive terms added in accord with section 7 apply to the code;
-keep intact all notices of the absence of any warranty; and give all
-recipients a copy of this License along with the Program.
-
-  You may charge any price or no price for each copy that you convey,
-and you may offer support or warranty protection for a fee.
-
-  5. Conveying Modified Source Versions.
-
-  You may convey a work based on the Program, or the modifications to
-produce it from the Program, in the form of source code under the
-terms of section 4, provided that you also meet all of these conditions:
-
-    a) The work must carry prominent notices stating that you modified
-    it, and giving a relevant date.
-
-    b) The work must carry prominent notices stating that it is
-    released under this License and any conditions added under section
-    7.  This requirement modifies the requirement in section 4 to
-    "keep intact all notices".
-
-    c) You must license the entire work, as a whole, under this
-    License to anyone who comes into possession of a copy.  This
-    License will therefore apply, along with any applicable section 7
-    additional terms, to the whole of the work, and all its parts,
-    regardless of how they are packaged.  This License gives no
-    permission to license the work in any other way, but it does not
-    invalidate such permission if you have separately received it.
-
-    d) If the work has interactive user interfaces, each must display
-    Appropriate Legal Notices; however, if the Program has interactive
-    interfaces that do not display Appropriate Legal Notices, your
-    work need not make them do so.
-
-  A compilation of a covered work with other separate and independent
-works, which are not by their nature extensions of the covered work,
-and which are not combined with it such as to form a larger program,
-in or on a volume of a storage or distribution medium, is called an
-"aggregate" if the compilation and its resulting copyright are not
-used to limit the access or legal rights of the compilation's users
-beyond what the individual works permit.  Inclusion of a covered work
-in an aggregate does not cause this License to apply to the other
-parts of the aggregate.
-
-  6. Conveying Non-Source Forms.
-
-  You may convey a covered work in object code form under the terms
-of sections 4 and 5, provided that you also convey the
-machine-readable Corresponding Source under the terms of this License,
-in one of these ways:
-
-    a) Convey the object code in, or embodied in, a physical product
-    (including a physical distribution medium), accompanied by the
-    Corresponding Source fixed on a durable physical medium
-    customarily used for software interchange.
-
-    b) Convey the object code in, or embodied in, a physical product
-    (including a physical distribution medium), accompanied by a
-    written offer, valid for at least three years and valid for as
-    long as you offer spare parts or customer support for that product
-    model, to give anyone who possesses the object code either (1) a
-    copy of the Corresponding Source for all the software in the
-    product that is covered by this License, on a durable physical
-    medium customarily used for software interchange, for a price no
-    more than your reasonable cost of physically performing this
-    conveying of source, or (2) access to copy the
-    Corresponding Source from a network server at no charge.
-
-    c) Convey individual copies of the object code with a copy of the
-    written offer to provide the Corresponding Source.  This
-    alternative is allowed only occasionally and noncommercially, and
-    only if you received the object code with such an offer, in accord
-    with subsection 6b.
-
-    d) Convey the object code by offering access from a designated
-    place (gratis or for a charge), and offer equivalent access to the
-    Corresponding Source in the same way through the same place at no
-    further charge.  You need not require recipients to copy the
-    Corresponding Source along with the object code.  If the place to
-    copy the object code is a network server, the Corresponding Source
-    may be on a different server (operated by you or a third party)
-    that supports equivalent copying facilities, provided you maintain
-    clear directions next to the object code saying where to find the
-    Corresponding Source.  Regardless of what server hosts the
-    Corresponding Source, you remain obligated to ensure that it is
-    available for as long as needed to satisfy these requirements.
-
-    e) Convey the object code using peer-to-peer transmission, provided
-    you inform other peers where the object code and Corresponding
-    Source of the work are being offered to the general public at no
-    charge under subsection 6d.
-
-  A separable portion of the object code, whose source code is excluded
-from the Corresponding Source as a System Library, need not be
-included in conveying the object code work.
-
-  A "User Product" is either (1) a "consumer product", which means any
-tangible personal property which is normally used for personal, family,
-or household purposes, or (2) anything designed or sold for incorporation
-into a dwelling.  In determining whether a product is a consumer product,
-doubtful cases shall be resolved in favor of coverage.  For a particular
-product received by a particular user, "normally used" refers to a
-typical or common use of that class of product, regardless of the status
-of the particular user or of the way in which the particular user
-actually uses, or expects or is expected to use, the product.  A product
-is a consumer product regardless of whether the product has substantial
-commercial, industrial or non-consumer uses, unless such uses represent
-the only significant mode of use of the product.
-
-  "Installation Information" for a User Product means any methods,
-procedures, authorization keys, or other information required to install
-and execute modified versions of a covered work in that User Product from
-a modified version of its Corresponding Source.  The information must
-suffice to ensure that the continued functioning of the modified object
-code is in no case prevented or interfered with solely because
-modification has been made.
-
-  If you convey an object code work under this section in, or with, or
-specifically for use in, a User Product, and the conveying occurs as
-part of a transaction in which the right of possession and use of the
-User Product is transferred to the recipient in perpetuity or for a
-fixed term (regardless of how the transaction is characterized), the
-Corresponding Source conveyed under this section must be accompanied
-by the Installation Information.  But this requirement does not apply
-if neither you nor any third party retains the ability to install
-modified object code on the User Product (for example, the work has
-been installed in ROM).
-
-  The requirement to provide Installation Information does not include a
-requirement to continue to provide support service, warranty, or updates
-for a work that has been modified or installed by the recipient, or for
-the User Product in which it has been modified or installed.  Access to a
-network may be denied when the modification itself materially and
-adversely affects the operation of the network or violates the rules and
-protocols for communication across the network.
-
-  Corresponding Source conveyed, and Installation Information provided,
-in accord with this section must be in a format that is publicly
-documented (and with an implementation available to the public in
-source code form), and must require no special password or key for
-unpacking, reading or copying.
-
-  7. Additional Terms.
-
-  "Additional permissions" are terms that supplement the terms of this
-License by making exceptions from one or more of its conditions.
-Additional permissions that are applicable to the entire Program shall
-be treated as though they were included in this License, to the extent
-that they are valid under applicable law.  If additional permissions
-apply only to part of the Program, that part may be used separately
-under those permissions, but the entire Program remains governed by
-this License without regard to the additional permissions.
-
-  When you convey a copy of a covered work, you may at your option
-remove any additional permissions from that copy, or from any part of
-it.  (Additional permissions may be written to require their own
-removal in certain cases when you modify the work.)  You may place
-additional permissions on material, added by you to a covered work,
-for which you have or can give appropriate copyright permission.
-
-  Notwithstanding any other provision of this License, for material you
-add to a covered work, you may (if authorized by the copyright holders of
-that material) supplement the terms of this License with terms:
-
-    a) Disclaiming warranty or limiting liability differently from the
-    terms of sections 15 and 16 of this License; or
-
-    b) Requiring preservation of specified reasonable legal notices or
-    author attributions in that material or in the Appropriate Legal
-    Notices displayed by works containing it; or
-
-    c) Prohibiting misrepresentation of the origin of that material, or
-    requiring that modified versions of such material be marked in
-    reasonable ways as different from the original version; or
-
-    d) Limiting the use for publicity purposes of names of licensors or
-    authors of the material; or
-
-    e) Declining to grant rights under trademark law for use of some
-    trade names, trademarks, or service marks; or
-
-    f) Requiring indemnification of licensors and authors of that
-    material by anyone who conveys the material (or modified versions of
-    it) with contractual assumptions of liability to the recipient, for
-    any liability that these contractual assumptions directly impose on
-    those licensors and authors.
-
-  All other non-permissive additional terms are considered "further
-restrictions" within the meaning of section 10.  If the Program as you
-received it, or any part of it, contains a notice stating that it is
-governed by this License along with a term that is a further
-restriction, you may remove that term.  If a license document contains
-a further restriction but permits relicensing or conveying under this
-License, you may add to a covered work material governed by the terms
-of that license document, provided that the further restriction does
-not survive such relicensing or conveying.
-
-  If you add terms to a covered work in accord with this section, you
-must place, in the relevant source files, a statement of the
-additional terms that apply to those files, or a notice indicating
-where to find the applicable terms.
-
-  Additional terms, permissive or non-permissive, may be stated in the
-form of a separately written license, or stated as exceptions;
-the above requirements apply either way.
-
-  8. Termination.
-
-  You may not propagate or modify a covered work except as expressly
-provided under this License.  Any attempt otherwise to propagate or
-modify it is void, and will automatically terminate your rights under
-this License (including any patent licenses granted under the third
-paragraph of section 11).
-
-  However, if you cease all violation of this License, then your
-license from a particular copyright holder is reinstated (a)
-provisionally, unless and until the copyright holder explicitly and
-finally terminates your license, and (b) permanently, if the copyright
-holder fails to notify you of the violation by some reasonable means
-prior to 60 days after the cessation.
-
-  Moreover, your license from a particular copyright holder is
-reinstated permanently if the copyright holder notifies you of the
-violation by some reasonable means, this is the first time you have
-received notice of violation of this License (for any work) from that
-copyright holder, and you cure the violation prior to 30 days after
-your receipt of the notice.
-
-  Termination of your rights under this section does not terminate the
-licenses of parties who have received copies or rights from you under
-this License.  If your rights have been terminated and not permanently
-reinstated, you do not qualify to receive new licenses for the same
-material under section 10.
-
-  9. Acceptance Not Required for Having Copies.
-
-  You are not required to accept this License in order to receive or
-run a copy of the Program.  Ancillary propagation of a covered work
-occurring solely as a consequence of using peer-to-peer transmission
-to receive a copy likewise does not require acceptance.  However,
-nothing other than this License grants you permission to propagate or
-modify any covered work.  These actions infringe copyright if you do
-not accept this License.  Therefore, by modifying or propagating a
-covered work, you indicate your acceptance of this License to do so.
-
-  10. Automatic Licensing of Downstream Recipients.
-
-  Each time you convey a covered work, the recipient automatically
-receives a license from the original licensors, to run, modify and
-propagate that work, subject to this License.  You are not responsible
-for enforcing compliance by third parties with this License.
-
-  An "entity transaction" is a transaction transferring control of an
-organization, or substantially all assets of one, or subdividing an
-organization, or merging organizations.  If propagation of a covered
-work results from an entity transaction, each party to that
-transaction who receives a copy of the work also receives whatever
-licenses to the work the party's predecessor in interest had or could
-give under the previous paragraph, plus a right to possession of the
-Corresponding Source of the work from the predecessor in interest, if
-the predecessor has it or can get it with reasonable efforts.
-
-  You may not impose any further restrictions on the exercise of the
-rights granted or affirmed under this License.  For example, you may
-not impose a license fee, royalty, or other charge for exercise of
-rights granted under this License, and you may not initiate litigation
-(including a cross-claim or counterclaim in a lawsuit) alleging that
-any patent claim is infringed by making, using, selling, offering for
-sale, or importing the Program or any portion of it.
-
-  11. Patents.
-
-  A "contributor" is a copyright holder who authorizes use under this
-License of the Program or a work on which the Program is based.  The
-work thus licensed is called the contributor's "contributor version".
-
-  A contributor's "essential patent claims" are all patent claims
-owned or controlled by the contributor, whether already acquired or
-hereafter acquired, that would be infringed by some manner, permitted
-by this License, of making, using, or selling its contributor version,
-but do not include claims that would be infringed only as a
-consequence of further modification of the contributor version.  For
-purposes of this definition, "control" includes the right to grant
-patent sublicenses in a manner consistent with the requirements of
-this License.
-
-  Each contributor grants you a non-exclusive, worldwide, royalty-free
-patent license under the contributor's essential patent claims, to
-make, use, sell, offer for sale, import and otherwise run, modify and
-propagate the contents of its contributor version.
-
-  In the following three paragraphs, a "patent license" is any express
-agreement or commitment, however denominated, not to enforce a patent
-(such as an express permission to practice a patent or covenant not to
-sue for patent infringement).  To "grant" such a patent license to a
-party means to make such an agreement or commitment not to enforce a
-patent against the party.
-
-  If you convey a covered work, knowingly relying on a patent license,
-and the Corresponding Source of the work is not available for anyone
-to copy, free of charge and under the terms of this License, through a
-publicly available network server or other readily accessible means,
-then you must either (1) cause the Corresponding Source to be so
-available, or (2) arrange to deprive yourself of the benefit of the
-patent license for this particular work, or (3) arrange, in a manner
-consistent with the requirements of this License, to extend the patent
-license to downstream recipients.  "Knowingly relying" means you have
-actual knowledge that, but for the patent license, your conveying the
-covered work in a country, or your recipient's use of the covered work
-in a country, would infringe one or more identifiable patents in that
-country that you have reason to believe are valid.
-
-  If, pursuant to or in connection with a single transaction or
-arrangement, you convey, or propagate by procuring conveyance of, a
-covered work, and grant a patent license to some of the parties
-receiving the covered work authorizing them to use, propagate, modify
-or convey a specific copy of the covered work, then the patent license
-you grant is automatically extended to all recipients of the covered
-work and works based on it.
-
-  A patent license is "discriminatory" if it does not include within
-the scope of its coverage, prohibits the exercise of, or is
-conditioned on the non-exercise of one or more of the rights that are
-specifically granted under this License.  You may not convey a covered
-work if you are a party to an arrangement with a third party that is
-in the business of distributing software, under which you make payment
-to the third party based on the extent of your activity of conveying
-the work, and under which the third party grants, to any of the
-parties who would receive the covered work from you, a discriminatory
-patent license (a) in connection with copies of the covered work
-conveyed by you (or copies made from those copies), or (b) primarily
-for and in connection with specific products or compilations that
-contain the covered work, unless you entered into that arrangement,
-or that patent license was granted, prior to 28 March 2007.
-
-  Nothing in this License shall be construed as excluding or limiting
-any implied license or other defenses to infringement that may
-otherwise be available to you under applicable patent law.
-
-  12. No Surrender of Others' Freedom.
-
-  If conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License.  If you cannot convey a
-covered work so as to satisfy simultaneously your obligations under this
-License and any other pertinent obligations, then as a consequence you may
-not convey it at all.  For example, if you agree to terms that obligate you
-to collect a royalty for further conveying from those to whom you convey
-the Program, the only way you could satisfy both those terms and this
-License would be to refrain entirely from conveying the Program.
-
-  13. Remote Network Interaction; Use with the GNU General Public License.
-
-  Notwithstanding any other provision of this License, if you modify the
-Program, your modified version must prominently offer all users
-interacting with it remotely through a computer network (if your version
-supports such interaction) an opportunity to receive the Corresponding
-Source of your version by providing access to the Corresponding Source
-from a network server at no charge, through some standard or customary
-means of facilitating copying of software.  This Corresponding Source
-shall include the Corresponding Source for any work covered by version 3
-of the GNU General Public License that is incorporated pursuant to the
-following paragraph.
-
-  Notwithstanding any other provision of this License, you have
-permission to link or combine any covered work with a work licensed
-under version 3 of the GNU General Public License into a single
-combined work, and to convey the resulting work.  The terms of this
-License will continue to apply to the part which is the covered work,
-but the work with which it is combined will remain governed by version
-3 of the GNU General Public License.
-
-  14. Revised Versions of this License.
-
-  The Free Software Foundation may publish revised and/or new versions of
-the GNU Affero General Public 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.
-
-  Each version is given a distinguishing version number.  If the
-Program specifies that a certain numbered version of the GNU Affero General
-Public License "or any later version" applies to it, you have the
-option of following the terms and conditions either of that numbered
-version or of any later version published by the Free Software
-Foundation.  If the Program does not specify a version number of the
-GNU Affero General Public License, you may choose any version ever published
-by the Free Software Foundation.
-
-  If the Program specifies that a proxy can decide which future
-versions of the GNU Affero General Public License can be used, that proxy's
-public statement of acceptance of a version permanently authorizes you
-to choose that version for the Program.
-
-  Later license versions may give you additional or different
-permissions.  However, no additional obligations are imposed on any
-author or copyright holder as a result of your choosing to follow a
-later version.
-
-  15. Disclaimer of Warranty.
-
-  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
-APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
-HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
-OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
-THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
-IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
-ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
-
-  16. Limitation of Liability.
-
-  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
-THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
-GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
-USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
-DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
-PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
-EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
-SUCH DAMAGES.
-
-  17. Interpretation of Sections 15 and 16.
-
-  If the disclaimer of warranty and limitation of liability provided
-above cannot be given local legal effect according to their terms,
-reviewing courts shall apply local law that most closely approximates
-an absolute waiver of all civil liability in connection with the
-Program, unless a warranty or assumption of liability accompanies a
-copy of the Program in return for a fee.
-
-                     END OF TERMS AND CONDITIONS
-
-            How to Apply These Terms to Your New Programs
-
-  If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these terms.
-
-  To do so, attach the following notices to the program.  It is safest
-to attach them to the start of each source file to most effectively
-state the exclusion of warranty; and each file should have at least
-the "copyright" line and a pointer to where the full notice is found.
-
-    <one line to give the program's name and a brief idea of what it does.>
-    Copyright (C) <year>  <name of author>
-
-    This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU Affero General Public License as published
-    by the Free Software Foundation, either version 3 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU Affero General Public License for more details.
-
-    You should have received a copy of the GNU Affero General Public License
-    along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-Also add information on how to contact you by electronic and paper mail.
-
-  If your software can interact with users remotely through a computer
-network, you should also make sure that it provides a way for users to
-get its source.  For example, if your program is a web application, its
-interface could display a "Source" link that leads users to an archive
-of the code.  There are many ways you could offer source, and different
-solutions will be better for different programs; see section 13 for the
-specific requirements.
-
-  You should also get your employer (if you work as a programmer) or school,
-if any, to sign a "copyright disclaimer" for the program, if necessary.
-For more information on this, and how to apply and follow the GNU AGPL, see
-<http://www.gnu.org/licenses/>.
+All other content is licensed under the GNU General Public License version 3
+(only).
 
+It is likely that a future version of this repository will all be licensed
+under the GNU General Public License version 3 (only).

LICENSE.AGPL-3

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public 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.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

LICENSE.GPL-3

@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public 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.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

README.md

@@ -59,10 +59,41 @@ an ISO. Rather than building one from scratch, it's much easier to
 install your version of subiquity into the daily image. Here's how to
 do this:
 
-1. Build your change into a snap:
+## Commit your changes locally
+
+If you are only making a change in Subiquity itself, running `git add <modified-file...>`
+and then `git commit` should be enough.
+
+Otherwise, if you made any modification to curtin or probert, you need to ensure that:
+
+* The modification is committed inside the relevant repository (i.e., `git add` + `git commit`).
+* The relevant `source` property in snapcraft.yaml points to the local
+  repository instead of the upstream repository.
+* The relevant `source-commit` property in snapcraft.yaml is updated to reflect
+  your new revision (one must use the full SHA-1 here).
+* The above modifications to snapcraft.yaml are committed.
+
+Example:
+```
+parts:
+  curtin:
+    plugin: nil
+
+    # Comment out the original source property, pointing to the upstream repository
+    #source: https://git.launchpad.net/curtin
+    # Instead, specify the name of the directory where curtin is checked out
+    source: curtin
+    source-type: git
+    # Update the below so it points to the commit ID within the curtin repository
+    source-commit: 7c18bf6a24297ed465a341a1f53875b61c878d6b
+```
+
+## Build and inject your changes into an ISO
+
+1. Build your changes into a snap:
 
    ```
-   $ snapcraft snap --output subiquity_test.snap
+   $ snapcraft pack --output subiquity_test.snap
    ```
 
 2. Grab the current version of the installer:
@@ -94,3 +125,15 @@ do this:
    ```
 
 The first three steps are bundled into the script ./scripts/test-this-branch.sh.
+
+# Contributing
+
+Please see our [contributing guidelines](CONTRIBUTING.md).
+
+# Documentation
+
+Subiquity's documentation is hosted at
+[https://canonical-subiquity.readthedocs-hosted.com/en/latest/](https://canonical-subiquity.readthedocs-hosted.com/en/latest/).
+
+The documentation source can be found in the [doc/](doc/) folder, which
+contains instructions for building a local preview.

apt-deps.txt

@@ -25,7 +25,9 @@ python3-async-timeout
 python3-attr
 python3-bson
 python3-coverage
+python3-debian
 python3-dev
+python3-distro-info
 python3-distutils-extra
 python3-flake8
 python3-gi
@@ -41,6 +43,7 @@ python3-pytest
 python3-pytest-xdist
 python3-pyudev
 python3-requests
+python3-requests-mock
 python3-requests-unixsocket
 python3-setuptools
 python3-systemd

autoinstall-schema.json

@@ -6,6 +6,12 @@
             "minimum": 1,
             "maximum": 1
         },
+        "interactive-sections": {
+            "type": "array",
+            "items": {
+                "type": "string"
+            }
+        },
         "early-commands": {
             "type": "array",
             "items": {

autoinstall-system-setup-schema.json

@@ -6,6 +6,12 @@
             "minimum": 1,
             "maximum": 1
         },
+        "interactive-sections": {
+            "type": "array",
+            "items": {
+                "type": "string"
+            }
+        },
         "early-commands": {
             "type": "array",
             "items": {

bin/console-conf-wrapper

@@ -26,7 +26,7 @@ fi
 if [ -e "/var/lib/snapd/modeenv" ]; then
     mode="$(sed -n 's/mode=\([^[:space:]]*\)/\1/p' /var/lib/snapd/modeenv)"
 else
-    mode="$(sed 's/.*snapd_recovery_mode=\([^[:space:]]*\)[[:space:]].*/\1/' /proc/cmdline))"
+    mode="$(sed 's/.*snapd_recovery_mode=\([^[:space:]]*\)[[:space:]].*/\1/' /proc/cmdline)"
 fi
 
 if [ "${mode}" = "install" ]; then
@@ -84,7 +84,13 @@ if [ "$(snap managed)" = "true" ]; then
     exit 0
 fi
 
-cat /usr/share/subiquity/console-conf-wait
+# if there is NOT console-conf snap, exit gracefully
+if [ ! -e "/snap/console-conf" ]; then
+  touch /var/lib/console-conf/complete
+  exit 0
+fi
+
+snap run console-conf.wait
 read REPLY
 # start the console-conf routine in snapd to delay any new refreshes, and wait
 # for current refreshes to complete, this will print off messages if there are
@@ -92,4 +98,12 @@ read REPLY
 if snap routine console-conf-start --help >/dev/null 2>/dev/null; then
     snap routine console-conf-start
 fi
-exec console-conf "$@"
+# preapre host finger prints for console-conf as it cannot access sshd or host keys
+mkdir -p /run/console-conf
+/usr/share/subiquity/console-conf-write-login-details --host-fingerprints > /run/console-conf/host-fingerprints.txt
+snap run console-conf "$@"
+rval=$?
+if [ ! ${rval} -eq 0 ]; then
+  echo "console-conf exited with: ${rval}"
+  exit ${rval}
+fi

console_conf/__init__.py

@@ -1,16 +1,15 @@
 # Copyright 2015 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 """ Console-Conf """

console_conf/cmd/tui.py

@@ -2,16 +2,15 @@
 # Copyright 2015 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 import argparse

console_conf/cmd/write_login_details.py

@@ -2,16 +2,15 @@
 # Copyright 2015 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 import logging

console_conf/controllers/__init__.py

@@ -1,16 +1,15 @@
 # Copyright 2015 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 """ console-conf controllers """

console_conf/controllers/chooser.py

@@ -1,16 +1,15 @@
 # Copyright 2020 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 import logging
 
@@ -70,7 +69,7 @@ class RecoveryChooserController(RecoveryChooserBaseController):
 
     def select(self, system, action):
         self.model.select(system, action)
-        self.app.next_screen()
+        self.app.request_next_screen()
 
     def more_options(self):
         self._current_view = self._all_view
@@ -96,4 +95,4 @@ class RecoveryChooserConfirmController(RecoveryChooserBaseController):
 
     def back(self):
         self.model.unselect()
-        self.app.prev_screen()
+        self.app.request_prev_screen()

console_conf/controllers/identity.py

@@ -1,19 +1,17 @@
 # Copyright 2015 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-import json
 import logging
 import os
 import pwd
@@ -21,10 +19,11 @@ import shlex
 import sys
 
 from console_conf.ui.views import IdentityView, LoginView
+from subiquitycore import snap
 from subiquitycore.snapd import SnapdConnection
 from subiquitycore.ssh import get_ips_standalone, host_key_info
 from subiquitycore.tuicontroller import TuiController
-from subiquitycore.utils import disable_console_conf, run_command
+from subiquitycore.utils import disable_console_conf
 
 log = logging.getLogger("console_conf.controllers.identity")
 
@@ -51,9 +50,8 @@ def get_core_version():
     return version
 
 
-def get_managed():
+def get_managed(con):
     """Check if device is managed"""
-    con = SnapdConnection("", "/run/snapd.socket")
     return con.get("v2/system-info").json()["result"]["managed"]
 
 
@@ -65,9 +63,8 @@ def get_realname(username):
     return info.pw_gecos.split(",", 1)[0]
 
 
-def get_device_owner():
+def get_device_owner(con):
     """Get device owner, if any"""
-    con = SnapdConnection("", "/run/snapd.socket")
     for user in con.get("v2/users").json()["result"]:
         if "username" not in user:
             continue
@@ -102,7 +99,7 @@ Personalize your account at https://login.ubuntu.com.
 """
 
 
-def write_login_details(fp, username, ips):
+def write_login_details(fp, username, ips, state_dir=None):
     sshcommands = "\n"
     for ip in ips:
         sshcommands += "    ssh %s@%s\n" % (username, ip)
@@ -116,10 +113,11 @@ def write_login_details(fp, username, ips):
         )
     else:
         first_ip = ips[0]
+        key_info = host_key_info(runtime_state_dir=state_dir)
         fp.write(
             login_details_tmpl.format(
                 sshcommands=sshcommands,
-                host_key_info=host_key_info(),
+                host_key_info=key_info,
                 tty_name=tty_name,
                 first_ip=first_ip,
                 version=version,
@@ -128,7 +126,9 @@ def write_login_details(fp, username, ips):
 
 
 def write_login_details_standalone():
-    owner = get_device_owner()
+    # running in standalone mode
+    con = SnapdConnection("/", "/run/snapd.socket")
+    owner = get_device_owner(con)
     ips = get_ips_standalone()
     if len(ips) == 0:
         if owner is None:
@@ -142,7 +142,13 @@ def write_login_details_standalone():
     if owner is None:
         print("device managed without user @ {}".format(", ".join(ips)))
     else:
-        write_login_details(sys.stdout, owner["username"], ips)
+        if snap.is_snap() and snap.is_snap_strictly_confined():
+            # normally this is set by the application context, but here we are
+            # executing standalone
+            runtime_state = os.path.join("/run", snap.snap_name())
+        else:
+            runtime_state = None
+        write_login_details(sys.stdout, owner["username"], ips, state_dir=runtime_state)
     return 0
 
 
@@ -152,13 +158,10 @@ class IdentityController(TuiController):
         self.model = app.base_model.identity
 
     def make_ui(self):
-        if get_managed():
-            device_owner = get_device_owner()
+        if get_managed(self.app.snapdcon):
+            device_owner = get_device_owner(self.app.snapdcon)
             if device_owner:
                 self.model.add_user(device_owner)
-                key_file = os.path.join(device_owner["homedir"], ".ssh/authorized_keys")
-                cp = run_command(["ssh-keygen", "-lf", key_file])
-                self.model.user.fingerprints = cp.stdout.replace("\r", "").splitlines()
             return self.make_login_view()
         else:
             return IdentityView(self.model, self)
@@ -173,34 +176,36 @@ class IdentityController(TuiController):
             login_details_path = self.opts.output_base + "/login-details.txt"
         else:
             self.app.urwid_loop.draw_screen()
-            cp = run_command(["snap", "create-user", "--sudoer", "--json", email])
-            if cp.returncode != 0:
+            user_action = {"action": "create", "email": email, "sudoer": True}
+            res = self.app.snapdcon.post("v2/users", body=user_action)
+            if res.json()["status"] != "OK":
                 if isinstance(self.ui.body, IdentityView):
                     self.ui.body.snap_create_user_failed(
-                        "Creating user failed:", cp.stderr
+                        "Creating user failed:", res.json()["result"]["message"]
                     )
                 return
             else:
-                data = json.loads(cp.stdout)
+                username = res.json()["result"][0]["username"]
                 result = {
                     "realname": email,
-                    "username": data["username"],
+                    "username": username,
                 }
-                os.makedirs("/run/console-conf", exist_ok=True)
-                login_details_path = "/run/console-conf/login-details.txt"
+                login_details_path = self.app.state_path("login-details.txt")
                 self.model.add_user(result)
         ips = []
         net_model = self.app.base_model.network
         for dev in net_model.get_all_netdevs():
             ips.extend(dev.actual_global_ip_addresses)
         with open(login_details_path, "w") as fp:
-            write_login_details(fp, result["username"], ips)
+            write_login_details(
+                fp, result["username"], ips, state_dir=self.app.state_dir
+            )
         self.login()
 
     def cancel(self):
         # You can only go back if we haven't created a user yet.
         if self.model.user is None:
-            self.app.prev_screen()
+            self.app.request_prev_screen()
 
     def make_login_view(self):
         title = "Configuration Complete"

console_conf/controllers/tests/test_chooser.py

@@ -1,16 +1,15 @@
 # Copyright 2020 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 import unittest
 from unittest import mock
@@ -74,7 +73,7 @@ class TestChooserConfirmController(unittest.TestCase):
         c.back()
         app.respond.assert_not_called()
         app.exit.assert_not_called()
-        app.prev_screen.assert_called()
+        app.request_prev_screen.assert_called()
         c.model.unselect.assert_called()
 
     def test_confirm(self):
@@ -106,7 +105,7 @@ class TestChooserController(unittest.TestCase):
         )
         self.assertEqual(c.model.selection, exp)
 
-        app.next_screen.assert_called()
+        app.request_next_screen.assert_called()
         app.respond.assert_not_called()
         app.exit.assert_not_called()
 
@@ -148,9 +147,10 @@ class TestChooserController(unittest.TestCase):
         # go back now
         c.back()
         c.ui.set_body.assert_called_with("current")
+        c.ui.set_body.reset_mock()
         # nothing
         c.back()
-        c.ui.set_body.not_called()
+        c.ui.set_body.assert_not_called()
 
     @mock.patch(
         "console_conf.controllers.chooser.ChooserCurrentSystemView",
@@ -169,7 +169,7 @@ class TestChooserController(unittest.TestCase):
         self.assertEqual(v, "current")
         # going back does nothing
         c.back()
-        c.ui.set_body.not_called()
+        c.ui.set_body.assert_not_called()
 
     @mock.patch(
         "console_conf.controllers.chooser.ChooserCurrentSystemView",

console_conf/controllers/tests/test_identity.py

@@ -0,0 +1,121 @@
+# Copyright 2024 Canonical, Ltd.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+import os.path
+import tempfile
+import unittest
+from unittest.mock import MagicMock, patch
+
+from console_conf.controllers.identity import IdentityController
+from console_conf.ui.views import IdentityView, LoginView
+from subiquitycore.models.network import NetworkDev
+from subiquitycore.snapd import MemoryResponseSet, get_fake_connection
+from subiquitycore.tests.mocks import make_app
+
+
+class TestIdentityController(unittest.TestCase):
+    @patch("os.ttyname", return_value="/dev/tty1")
+    @patch("console_conf.controllers.identity.get_core_version", return_value="24")
+    def test_snap_integration(self, core_version, ttyname):
+        with tempfile.TemporaryDirectory(suffix="console-conf-test") as statedir:
+            app = make_app()
+            app.state_dir = statedir
+            app.opts.dry_run = False
+            app.snapdcon = get_fake_connection()
+            app.state_dir = statedir
+            network_model = MagicMock()
+            mock_devs = [MagicMock(spec=NetworkDev)]
+            network_model.get_all_netdevs.return_value = mock_devs
+            mock_devs[0].actual_global_ip_addresses = ["1.2.3.4"]
+            app.base_model.network = network_model
+            app.urwid_loop = MagicMock()
+
+            def state_path(*parts):
+                return os.path.join(statedir, *parts)
+
+            app.state_path = MagicMock(side_effect=state_path)
+
+            create_user_calls = 0
+
+            def create_user_cb(path, body, **args):
+                nonlocal create_user_calls
+                create_user_calls += 1
+                self.assertEqual(path, "v2/users")
+                self.assertEqual(
+                    body, {"action": "create", "email": "foo@bar.com", "sudoer": True}
+                )
+                return {
+                    "status": "OK",
+                    "result": [
+                        {
+                            "username": "foo",
+                        }
+                    ],
+                }
+
+            # fake POST handlers
+            app.snapdcon.post_cb["v2/users"] = create_user_cb
+
+            c = IdentityController(app)
+            c.identity_done("foo@bar.com")
+
+            self.assertEqual(create_user_calls, 1)
+
+            with open(os.path.join(statedir, "login-details.txt")) as inf:
+                data = inf.read()
+            self.assertIn("Ubuntu Core 24 on 1.2.3.4 (tty1)\n", data)
+
+    @patch("pwd.getpwnam")
+    @patch("os.path.isdir", return_value=True)
+    def test_make_ui_managed_with_user(self, isdir, getpwnam):
+        pwinfo = MagicMock()
+        pwinfo.pw_gecos = "Foo,Bar"
+        getpwnam.return_value = pwinfo
+
+        app = make_app()
+        app.opts.dry_run = False
+        app.snapdcon = get_fake_connection()
+        # app.state_dir = statedir
+        network_model = MagicMock()
+        mock_devs = [MagicMock(spec=NetworkDev)]
+        network_model.get_all_netdevs.return_value = mock_devs
+        mock_devs[0].actual_global_ip_addresses = ["1.2.3.4"]
+        app.base_model.network = network_model
+
+        app.snapdcon.response_sets = {
+            "v2-system-info": MemoryResponseSet([{"result": {"managed": True}}]),
+            "v2-users": MemoryResponseSet(
+                [
+                    # no "username" for first entry
+                    {"result": [{}, {"username": "foo"}]}
+                ]
+            ),
+        }
+
+        c = IdentityController(app)
+        ui = c.make_ui()
+        self.assertIsInstance(ui, LoginView)
+        getpwnam.assert_called_with("foo")
+
+    def test_make_ui_unmanaged(self):
+        app = make_app()
+        app.opts.dry_run = False
+        app.snapdcon = get_fake_connection()
+
+        app.snapdcon.response_sets = {
+            "v2-system-info": MemoryResponseSet([{"result": {"managed": False}}]),
+        }
+
+        c = IdentityController(app)
+        ui = c.make_ui()
+        self.assertIsInstance(ui, IdentityView)

console_conf/controllers/welcome.py

@@ -1,16 +1,15 @@
 # Copyright 2015 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 from console_conf.ui.views import ChooserWelcomeView, WelcomeView
@@ -24,7 +23,7 @@ class WelcomeController(TuiController):
         return self.welcome_view(self)
 
     def done(self):
-        self.app.next_screen()
+        self.app.request_next_screen()
 
     def cancel(self):
         # Can't go back from here!

console_conf/core.py

@@ -1,16 +1,15 @@
 # Copyright 2015 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 import logging
@@ -18,15 +17,23 @@ import logging
 from console_conf.models.console_conf import ConsoleConfModel
 from console_conf.models.systems import RecoverySystemsModel
 from subiquitycore.prober import Prober
+from subiquitycore.snap import snap_name
+from subiquitycore.snapd import SnapdConnection
 from subiquitycore.tui import TuiApplication
 
 log = logging.getLogger("console_conf.core")
 
+# project is used to build the state directory path under /run/, which usually
+# ends up as /run/console-conf. Note this should only be changed in
+# coordination with console-conf-wrapper and any other glue shipped with Ubuntu
+# Core boot base
+CONSOLE_CONF_PROJECT = snap_name() or "console-conf"
+
 
 class ConsoleConf(TuiApplication):
     from console_conf import controllers as controllers_mod
 
-    project = "console_conf"
+    project = CONSOLE_CONF_PROJECT
 
     make_model = ConsoleConfModel
 
@@ -39,12 +46,15 @@ class ConsoleConf(TuiApplication):
     def __init__(self, opts):
         super().__init__(opts)
         self.prober = Prober(opts.machine_config, self.debug_flags)
+        # we're talking to snapd over the main socket, this may require
+        # snapd-control if executing inside a snap
+        self.snapdcon = SnapdConnection(self.root, "/run/snapd.socket")
 
 
 class RecoveryChooser(TuiApplication):
     from console_conf import controllers as controllers_mod
 
-    project = "console_conf"
+    project = CONSOLE_CONF_PROJECT
 
     controllers = [
         "RecoveryChooserWelcome",

console_conf/models/identity.py

@@ -1,16 +1,15 @@
 # Copyright 2015 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 import logging
@@ -25,7 +24,6 @@ class User(object):
     realname = attr.ib()
     username = attr.ib()
     homedir = attr.ib(default=None)
-    fingerprints = attr.ib(init=False, default=[])
 
 
 class IdentityModel(object):

console_conf/models/systems.py

@@ -2,16 +2,15 @@
 # Copyright 2020 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 import json
 import logging

console_conf/models/tests/test_systems.py

@@ -2,16 +2,15 @@
 # Copyright 2020 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 import json
 import unittest

console_conf/ui/__init__.py

@@ -1,16 +1,15 @@
 # Copyright 2015 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 """ Subiquity UI Components """

console_conf/ui/views/__init__.py

@@ -1,16 +1,15 @@
 # Copyright 2015 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 """ ConsoleConf UI Views """

console_conf/ui/views/chooser.py

@@ -1,16 +1,15 @@
 # Copyright 2015 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 """ Chooser

console_conf/ui/views/identity.py

@@ -1,16 +1,15 @@
 # Copyright 2015 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 import logging

console_conf/ui/views/login.py

@@ -1,16 +1,15 @@
 # Copyright 2015 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 """ Login

console_conf/ui/views/tests/test_chooser.py

@@ -1,16 +1,15 @@
 # Copyright 2020 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 import unittest
 

console_conf/ui/views/welcome.py

@@ -1,16 +1,15 @@
 # Copyright 2015 Canonical, Ltd.
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
+# You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 """ Welcome

debian/changelog

@@ -1,3 +1,9 @@
+subiquity (24.04.1+git45g5f9fae19) noble; urgency=medium
+
+  * Upgrade to noble, systemd files are now in /usr/lib
+
+ -- Dimitri John Ledkov <dimitri.ledkov@canonical.com>  Fri, 24 Nov 2023 23:10:15 +0000
+
 subiquity (20.04.1+git45g5f9fae19) focal; urgency=medium
 
   * Upload subquity snapshot with reverted consoleconf patch.

debian/control

@@ -25,6 +25,7 @@ Depends: probert-network,
          python3-yaml,
          python3-requests,
          python3-requests-unixsocket,
+         python3-pyroute2,
          ${misc:Depends},
          ${python3:Depends}
 Description: Ubuntu Server Installer - core libraries

debian/copyright

@@ -3,12 +3,16 @@ Upstream-Name: subiquity
 Source: https://github.com/canonical/subiquity
 
 Files: *
+Copyright: Copyright 2015, Canonical Ltd., All Rights Reserved.
+License: GPL-3.0
+
+Files: subiquity/*
 Copyright: Copyright 2015, Canonical Ltd.
 License: AGPL-3.0+
 
 Files: debian/*
-Copyright: Copyright 2015, Canonical Ltd.
-License: AGPL-3.0+
+Copyright: Copyright 2015, Canonical Ltd., All Rights Reserved.
+License: GPL-3.0
 
 License: AGPL-3.0+
  This program is free software: you can redistribute it and/or modify
@@ -23,3 +27,16 @@ License: AGPL-3.0+
  .
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+License: GPL-3.0
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, version 3.
+ .
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU General Public License for more details.
+ .
+ You should have received a copy of the GNU General Public License
+ along with this program.  If not, see <http://www.gnu.org/licenses/>.

debian/rules

@@ -26,10 +26,8 @@ override_dh_python3:
 override_dh_installinit:
 	dh_installsystemd --no-start --name=console-conf@
 	dh_installsystemd --no-start --name=serial-console-conf@
-	mkdir $(CURDIR)/debian/console-conf/lib/systemd/system/getty@.service.d/
-	install -m 0644 $(CURDIR)/debian/console-conf.conf $(CURDIR)/debian/console-conf/lib/systemd/system/getty@.service.d/
-	mkdir $(CURDIR)/debian/console-conf/lib/systemd/system/serial-getty@.service.d/
-	install -m 0644 $(CURDIR)/debian/console-conf-serial.conf $(CURDIR)/debian/console-conf/lib/systemd/system/serial-getty@.service.d/
+	install -D -m 0644 $(CURDIR)/debian/console-conf.conf $(CURDIR)/debian/console-conf/usr/lib/systemd/system/getty@.service.d/console-conf.conf
+	install -D -m 0644 $(CURDIR)/debian/console-conf-serial.conf $(CURDIR)/debian/console-conf/usr/lib/systemd/system/serial-getty@.service.d/console-conf-serial.conf
 
 override_dh_auto_test:
 	@echo "No tests."

doc/.custom_wordlist.txt

@@ -0,0 +1,88 @@
+AArch
+Autoinstall
+Autoinstalls
+Btrfs
+DHCP
+EFI
+Esc
+ESP
+ESPs
+GPT
+GUID
+GiB
+GiB
+Libera
+LPAR
+LTS
+LUKS
+LV
+LVM
+LinuxONE
+Mantic
+MiB
+NIC
+Netplan
+NoCloud
+OEM
+OpenSSH
+Petitboot
+PgDn
+PgUp
+POST
+PPA
+PReP
+SSD
+Seagate
+Subiquity
+UEFI
+URI
+Zdev
+amd
+authorized
+autoinstall
+autoinstaller
+autoinstalls
+bootable
+bootloader
+bootloaders
+codecs
+config
+conf
+curtin
+debconf
+debian
+dir
+el
+flavor
+geoip
+geolocation
+globbing
+hostname
+iSCSI
+init
+md
+oem
+passwd
+ppc
+pre
+preseed
+preseeded
+preseeding
+preseeds
+pw
+realname
+rootfs
+rsyslog
+runtime
+subvolume
+subvolumes
+superset
+sysfs
+traceback
+tty
+ubuntu
+udev
+unformatted
+VLAN
+webhook
+workdir

doc/.gitignore

@@ -1,2 +1,9 @@
+/*env*/
+.sphinx/venv/
+.sphinx/warnings.txt
+.sphinx/.wordlist.dic
+.sphinx/.doctrees/
 _build
-.sphinx
+.DS_Store
+__pycache__
+.idea/

doc/.sphinx/_static/custom.css

@@ -1,54 +1,13 @@
 /** Fix the font weight (300 for normal, 400 for slightly bold) **/
-/** Should be 100 for all headers, 400 for normal text  **/
 
-h1, h2, h3, h4, h5, h6, .sidebar-tree .current-page>.reference, button, input, optgroup, select, textarea, th.head {
-    font-weight: 200;
+div.page, h1, h2, h3, h4, h5, h6, .sidebar-tree .current-page>.reference, button, input, optgroup, select, textarea, th.head {
+    font-weight: 300
 }
 
-.toc-title {
+.toc-tree li.scroll-current>.reference, dl.glossary dt, dl.simple dt, dl:not([class]) dt {
     font-weight: 400;
 }
 
-.sidebar-tree .toctree-l2.has-children>.reference {
-    font-weight: 300;
-}
-
-li.toctree-l3 {
-    font-weight: 200;
-}
-
-div.page, li.scroll-current>.reference, dl.glossary dt, dl.simple dt, dl:not([class]) dt {
-    font-weight: 300;
-    line-height: 1.5;
-    font-size: var(--font-size--normal);
-}
-
-
-/** Side bars (side-bar tree = left, toc-tree = right) **/
-div.sidebar-tree {
-    font-weight: 200;
-    line-height: 1.5;
-    font-size: var(--font-size--normal);
-}
-
-div.toc-tree {
-    font-weight: 200;
-    font-size: var(--font-size--medium);
-    line-height: 1.5;
-}
-
-.sidebar-tree .toctree-l1>.reference, .toc-tree li.scroll-current>.reference {
-    font-weight: 400;
-}
-
-/** List styling   **/
-ol, ul {
-    margin-bottom: 1.5rem;
-    margin-left: 1rem;
-    margin-top: 0;
-    padding-left: 1rem;
-}
-
 /** Table styling **/
 
 th.head {
@@ -67,9 +26,9 @@ table.docutils td, table.docutils th, table.docutils td:last-child, table.docuti
     border-left: none;
 }
 
-/* center align table cells with ":-:" */
-td.text-center {
-    text-align: center;
+/* Allow to centre text horizontally in table data cells */
+table.align-center {
+    text-align: center !important;
 }
 
 /** No rounded corners **/
@@ -78,44 +37,12 @@ td.text-center {
     border-radius: 0;
 }
 
-/** code blocks and literals **/
-code.docutils.literal.notranslate, .highlight pre, pre.literal-block {
-    font-size: var(--font-size--medium);
-}
-
-
 /** Admonition styling **/
 
 .admonition {
-    font-size: var(--font-size--medium);
-    box-shadow: none;
-}
-
-/** Styling for links **/
-/* unvisited link */
-a:link {
-    color: #06c;
-    text-decoration: none;
-}
-
-/* visited link */
-a:visited {
-    color: #7d42b8;
-    text-decoration: none;
-}
-
-/* mouse over link */
-a:hover {
-    text-decoration: underline;
-}
-
-/* selected link */
-a:active {
-    text-decoration: underline;
-}
-
-a.sidebar-brand.centered {
-    text-decoration: none;
+    border-top: 1px solid #d9d9d9;
+    border-right: 1px solid #d9d9d9;
+    border-bottom: 1px solid #d9d9d9;
 }
 
 /** Color for the "copy link" symbol next to headings **/
@@ -242,7 +169,43 @@ details summary {
     color: var(--color-link);
 }
 
-/** Context links at the bottom of the page **/
-footer {
-    font-size: var(--font-size--medium);
+/** Fix the styling of the version box for readthedocs **/
+
+#furo-readthedocs-versions .rst-versions, #furo-readthedocs-versions .rst-current-version, #furo-readthedocs-versions:focus-within .rst-current-version, #furo-readthedocs-versions:hover .rst-current-version  {
+    background: var(--color-sidebar-item-background--hover);
 }
+
+.rst-versions .rst-other-versions dd a {
+    color: var(--color-link);
+}
+
+#furo-readthedocs-versions:focus-within .rst-current-version .fa-book, #furo-readthedocs-versions:hover .rst-current-version .fa-book, .rst-versions .rst-other-versions {
+    color: var(--color-sidebar-link-text);
+}
+
+.rst-versions .rst-current-version {
+    color: var(--color-version-popup);
+    font-weight: bolder;
+}
+
+/* Code-block copybutton invisible by default
+   (overriding Furo config to achieve default copybutton setting). */
+.highlight button.copybtn {
+   opacity: 0;
+}
+
+/* Mimicking the 'Give feedback' button for UX consistency */
+.sidebar-search-container input[type=submit] {
+    color: #FFFFFF;
+    border: 2px solid #D6410D;
+    padding: var(--sidebar-search-input-spacing-vertical) var(--sidebar-search-input-spacing-horizontal);
+    background: #D6410D;
+    font-weight: bold;
+    font-size: var(--font-size--small);
+    cursor: pointer;
+}
+
+.sidebar-search-container input[type=submit]:hover {
+    text-decoration: underline;
+}
+

doc/.sphinx/_static/furo_colors.css

@@ -0,0 +1,88 @@
+body {
+    --color-code-background: #f8f8f8;
+    --color-code-foreground: black;
+    --font-stack: Ubuntu, -apple-system, Segoe UI, Roboto, Oxygen, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif;
+    --font-stack--monospace: Ubuntu Mono, Consolas, Monaco, Courier, monospace;
+    --color-foreground-primary: #111;
+    --color-foreground-secondary: var(--color-foreground-primary);
+    --color-foreground-muted: #333;
+    --color-background-secondary: #FFF;
+    --color-background-hover: #f2f2f2;
+    --color-brand-primary: #111;
+    --color-brand-content: #06C;
+    --color-api-background: #cdcdcd;
+    --color-inline-code-background: rgba(0,0,0,.03);
+    --color-sidebar-link-text: #111;
+    --color-sidebar-item-background--current: #ebebeb;
+    --color-sidebar-item-background--hover: #f2f2f2;
+    --toc-font-size: var(--font-size--small);
+    --color-admonition-title-background--note: var(--color-background-primary);
+    --color-admonition-title-background--tip: var(--color-background-primary);
+    --color-admonition-title-background--important: var(--color-background-primary);
+    --color-admonition-title-background--caution: var(--color-background-primary);
+    --color-admonition-title--note: #24598F;
+    --color-admonition-title--tip: #24598F;
+    --color-admonition-title--important: #C7162B;
+    --color-admonition-title--caution: #F99B11;
+    --color-highlighted-background: #EbEbEb;
+    --color-link-underline: var(--color-background-primary);
+    --color-link-underline--hover: var(--color-background-primary);
+    --color-version-popup: #772953;
+}
+
+@media not print {
+    body[data-theme="dark"] {
+        --color-code-background: #202020;
+        --color-code-foreground: #d0d0d0;
+        --color-foreground-secondary: var(--color-foreground-primary);
+        --color-foreground-muted: #CDCDCD;
+        --color-background-secondary: var(--color-background-primary);
+        --color-background-hover: #666;
+        --color-brand-primary: #fff;
+        --color-brand-content: #06C;
+        --color-sidebar-link-text: #f7f7f7;
+        --color-sidebar-item-background--current: #666;
+        --color-sidebar-item-background--hover: #333;
+        --color-admonition-background: transparent;
+        --color-admonition-title-background--note: var(--color-background-primary);
+        --color-admonition-title-background--tip: var(--color-background-primary);
+        --color-admonition-title-background--important: var(--color-background-primary);
+        --color-admonition-title-background--caution: var(--color-background-primary);
+        --color-admonition-title--note: #24598F;
+        --color-admonition-title--tip: #24598F;
+        --color-admonition-title--important: #C7162B;
+        --color-admonition-title--caution: #F99B11;
+        --color-highlighted-background: #666;
+        --color-link-underline: var(--color-background-primary);
+        --color-link-underline--hover: var(--color-background-primary);
+        --color-version-popup: #F29879;
+    }
+    @media (prefers-color-scheme: dark) {
+        body:not([data-theme="light"]) {
+            --color-code-background: #202020;
+            --color-code-foreground: #d0d0d0;
+            --color-foreground-secondary: var(--color-foreground-primary);
+            --color-foreground-muted: #CDCDCD;
+            --color-background-secondary: var(--color-background-primary);
+            --color-background-hover: #666;
+            --color-brand-primary: #fff;
+            --color-brand-content: #06C;
+            --color-sidebar-link-text: #f7f7f7;
+            --color-sidebar-item-background--current: #666;
+            --color-sidebar-item-background--hover: #333;
+            --color-admonition-background: transparent;
+            --color-admonition-title-background--note: var(--color-background-primary);
+            --color-admonition-title-background--tip: var(--color-background-primary);
+            --color-admonition-title-background--important: var(--color-background-primary);
+            --color-admonition-title-background--caution: var(--color-background-primary);
+            --color-admonition-title--note: #24598F;
+            --color-admonition-title--tip: #24598F;
+            --color-admonition-title--important: #C7162B;
+            --color-admonition-title--caution: #F99B11;
+            --color-highlighted-background: #666;
+            --color-link-underline: var(--color-background-primary);
+            --color-link-underline--hover: var(--color-background-primary);
+            --color-version-popup: #F29879;
+        }
+    }
+}

doc/.sphinx/_static/github_issue_links.css

@@ -4,7 +4,7 @@
 .github-issue-link {
     font-size: var(--font-size--small);
     font-weight: bold;
-    background-color: #DD4814;
+    background-color: #D6410D;
     padding: 13px 23px;
     text-decoration: none;
 }

doc/.sphinx/_static/github_issue_links.js

@@ -1,19 +1,17 @@
+// if we already have an onload function, save that one
+var prev_handler = window.onload;
+
 window.onload = function() {
+    // call the previous onload function
+    if (prev_handler) {
+        prev_handler();
+    }
+
     const link = document.createElement("a");
     link.classList.add("muted-link");
     link.classList.add("github-issue-link");
     link.text = "Give feedback";
-    link.href = (
-        "https://github.com/canonical/subiquity/issues/new?"
-        + "title=docs%3A+TYPE+YOUR+QUESTION+HERE"
-        + "&body=*Please describe the question or issue you're facing with "
-        + `"${document.title}"`
-        + ".*"
-        + "%0A%0A%0A%0A%0A"
-        + "---"
-        + "%0A"
-        + `*Reported+from%3A+${location.href}*`
-    );
+    link.href = ("https://bugs.launchpad.net/subiquity/+filebug");
     link.target = "_blank";
 
     const div = document.createElement("div");

doc/.sphinx/_static/header-nav.js

@@ -0,0 +1,10 @@
+$(document).ready(function() {
+    $(document).on("click", function () {
+        $(".more-links-dropdown").hide();
+    });
+
+    $('.nav-more-links').click(function(event) {
+        $('.more-links-dropdown').toggle();
+        event.stopPropagation();
+    });
+})

doc/.sphinx/_static/header.css

@@ -0,0 +1,167 @@
+.p-navigation {
+  border-bottom: 1px solid var(--color-sidebar-background-border);
+}
+
+.p-navigation__nav {
+  background: #333333;
+  display: flex;
+}
+
+.p-logo {
+  display: flex !important;
+  padding-top: 0 !important;
+  text-decoration: none;
+}
+
+.p-logo-image {
+  height: 44px;
+  padding-right: 10px;
+}
+
+.p-logo-text {
+  margin-top: 18px;
+  color: white;
+  text-decoration: none;
+}
+
+ul.p-navigation__links {
+  display: flex;
+  list-style: none;
+  margin-left: 0;
+  margin-top: auto;
+  margin-bottom: auto;
+  max-width: 800px;
+  width: 100%;
+}
+
+ul.p-navigation__links li {
+  margin: 0 auto;
+  text-align: center;
+  width: 100%;
+}
+
+ul.p-navigation__links li a {
+  background-color: rgba(0, 0, 0, 0);
+  border: none;
+  border-radius: 0;
+  color: var(--color-sidebar-link-text);
+  display: block;
+  font-weight: 400;
+  line-height: 1.5rem;
+  margin: 0;
+  overflow: hidden;
+  padding: 1rem 0;
+  position: relative;
+  text-align: left;
+  text-overflow: ellipsis;
+  transition-duration: .1s;
+  transition-property: background-color, color, opacity;
+  transition-timing-function: cubic-bezier(0.215, 0.61, 0.355, 1);
+  white-space: nowrap;
+  width: 100%;
+}
+
+ul.p-navigation__links .p-navigation__link {
+  color: #ffffff;
+  font-weight: 300;
+  text-align: center;
+  text-decoration: none;
+}
+
+ul.p-navigation__links .p-navigation__link:hover {
+  background-color: #2b2b2b;
+}
+
+ul.p-navigation__links .p-dropdown__link:hover {
+  background-color: var(--color-sidebar-item-background--hover);
+}
+
+ul.p-navigation__links .p-navigation__sub-link {
+  background: var(--color-background-primary);
+  padding: .5rem 0 .5rem .5rem;
+  font-weight: 300;
+}
+
+ul.p-navigation__links .more-links-dropdown li a {
+  border-left: 1px solid var(--color-sidebar-background-border);
+  border-right: 1px solid var(--color-sidebar-background-border);
+}
+
+ul.p-navigation__links .more-links-dropdown li:first-child a {
+  border-top: 1px solid var(--color-sidebar-background-border);
+}
+
+ul.p-navigation__links .more-links-dropdown li:last-child a {
+  border-bottom: 1px solid var(--color-sidebar-background-border);
+}
+
+ul.p-navigation__links .p-navigation__logo {
+  padding: 0.5rem;
+}
+
+ul.p-navigation__links .p-navigation__logo img {
+  width: 40px;
+}
+
+ul.more-links-dropdown {
+  display: none;
+  overflow-x: visible;
+  height: 0;
+  z-index: 55;
+  padding: 0;
+  position: relative;
+  list-style: none;
+  margin-bottom: 0;
+  margin-top: 0;
+}
+
+.nav-more-links::after {
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16'%3E%3Cpath fill='%23111' d='M8.187 11.748l6.187-6.187-1.06-1.061-5.127 5.127L3.061 4.5 2 5.561z'/%3E%3C/svg%3E");
+  background-position: center;
+  background-repeat: no-repeat;
+  background-size: contain;
+  content: "";
+  display: block;
+  filter: invert(100%);
+  height: 1rem;
+  pointer-events: none;
+  position: absolute;
+  right: 1rem;
+  text-indent: calc(100% + 10rem);
+  top: calc(1rem + 0.25rem);
+  width: 1rem;
+}
+
+.nav-ubuntu-com {
+  display: none;
+}
+
+@media only screen and (min-width: 480px) {
+  ul.p-navigation__links li {
+    width: 100%;
+  }
+
+  .nav-ubuntu-com {
+    display: inherit;
+  }
+}
+
+@media only screen and (max-width: 800px) {
+  .nav-more-links {
+    margin-left: auto !important;
+    padding-right: 2rem !important;
+    width: 8rem !important;
+  }
+}
+
+@media only screen and (min-width: 800px) {
+  ul.p-navigation__links li {
+    width: 100% !important;
+  }
+}
+
+@media only screen and (min-width: 1310px) {
+  ul.p-navigation__links {
+    margin-left: calc(50% - 41em);
+  }
+}

doc/.sphinx/_templates/base.html

@@ -0,0 +1,12 @@
+{% extends "furo/base.html" %}
+
+{% block theme_scripts %}
+<script>
+  const github_url = "{{ github_url }}";
+</script>
+{% endblock theme_scripts %}
+
+{# ru-fu: don't include the color variables from the conf.py file, but use a
+   separate CSS file to save space #}
+{% block theme_styles %}
+{% endblock theme_styles %}

doc/.sphinx/_templates/footer.html

@@ -0,0 +1,99 @@
+{# ru-fu: copied from Furo, with modifications as stated below. Modifications are marked 'mod:'. #}
+
+<div class="related-pages">
+  {# mod: Per-page navigation #}
+  {% if meta %}
+    {% if 'sequential_nav' in meta %}
+      {% set sequential_nav = meta.sequential_nav %}
+    {% endif %}  
+  {% endif %}
+  {# mod: Conditional wrappers to control page navigation buttons #}
+  {% if sequential_nav != "none" -%}
+    {% if next and (sequential_nav == "next" or sequential_nav == "both") -%}
+      <a class="next-page" href="{{ next.link }}">
+        <div class="page-info">
+          <div class="context">
+            <span>{{ _("Next") }}</span>
+          </div>
+          <div class="title">{{ next.title }}</div>
+        </div>
+        <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+      </a>
+    {%- endif %}
+    {% if prev and (sequential_nav == "prev" or sequential_nav == "both") -%}
+      <a class="prev-page" href="{{ prev.link }}">
+        <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+        <div class="page-info">
+          <div class="context">
+            <span>{{ _("Previous") }}</span>
+          </div>
+          {% if prev.link == pathto(master_doc) %}
+            <div class="title">{{ _("Home") }}</div>
+          {% else %}
+            <div class="title">{{ prev.title }}</div>
+          {% endif %}
+        </div>
+      </a>
+    {%- endif %}
+  {%- endif %}
+</div>
+<div class="bottom-of-page">
+  <div class="left-details">
+    {%- if show_copyright %}
+    <div class="copyright">
+      {%- if hasdoc('copyright') %}
+        {% trans path=pathto('copyright'), copyright=copyright|e -%}
+          <a href="{{ path }}">Copyright</a> &#169; {{ copyright }}
+        {%- endtrans %}
+      {%- else %}
+        {% trans copyright=copyright|e -%}
+          Copyright &#169; {{ copyright }}
+        {%- endtrans %}
+      {%- endif %}
+    </div>
+    {%- endif %}
+
+    {# mod: removed "Made with" #}
+
+    {%- if last_updated -%}
+    <div class="last-updated">
+      {% trans last_updated=last_updated|e -%}
+        Last updated on {{ last_updated }}
+      {%- endtrans -%}
+    </div>
+    {%- endif %}
+
+    {%- if show_source and has_source and sourcename %}
+    <div class="show-source">
+      <a class="muted-link" href="{{ pathto('_sources/' + sourcename, true)|e }}"
+         rel="nofollow">Show source</a>
+    </div>
+    {%- endif %}
+  </div>
+  <div class="right-details">
+
+    {# mod: replaced RTD icons with our links #}
+
+    {% if discourse %}
+    <div class="ask-discourse">
+      <a class="muted-link" href="{{ discourse }}">Ask a question on Discourse</a>
+    </div>
+    {% endif %}
+
+    {% if github_url and github_version and github_folder %}
+
+    {% if github_issues %}
+    <div class="issue-github">
+      <a class="muted-link" href="https://bugs.launchpad.net/subiquity/+filebug">Open a Launchpad issue for this documentation</a>
+    </div>
+    {% endif %}
+
+    <div class="edit-github">
+      <a class="muted-link" href="{{ github_url }}/edit/{{ github_version }}{{ github_folder }}{{ pagename }}{{ page_source_suffix }}">Edit this page on GitHub</a>
+    </div>
+    {% endif %}
+
+
+    </div>
+  </div>
+</div>

doc/.sphinx/_templates/header.html

@@ -0,0 +1,36 @@
+<header id="header" class="p-navigation">
+
+  <div class="p-navigation__nav" role="menubar">
+
+    <ul class="p-navigation__links" role="menu">
+
+      <li>
+        <a class="p-logo" href="https://{{ product_page }}" aria-current="page">
+          <img src="{{ pathto(product_tag,1) }}" alt="Logo" class="p-logo-image">
+          <div class="p-logo-text p-heading--4">{{ project.title() }}
+          </div>
+        </a>
+      </li>
+
+      <li class="nav-ubuntu-com">
+        <a href="https://{{ product_page }}" class="p-navigation__link">{{ product_page }}</a>
+      </li>
+
+      <li>
+        <a href="#" class="p-navigation__link nav-more-links">More resources</a>
+        <ul class="more-links-dropdown">
+
+          <li>
+            <a href="{{ discourse }}" class="p-navigation__sub-link p-dropdown__link">Forum</a>
+          </li>
+
+          <li>
+            <a href="{{ github_url }}" class="p-navigation__sub-link p-dropdown__link">GitHub</a>
+          </li>
+
+        </ul>
+      </li>
+
+    </ul>
+  </div>
+</header>

doc/.sphinx/_templates/page.html

@@ -0,0 +1,49 @@
+{% extends "furo/page.html" %}
+
+{% block footer %}
+   {% include "footer.html" %}
+{% endblock footer %}
+
+{% block body -%}
+   {% include "header.html" %}
+   {{ super() }}
+{%- endblock body %}
+
+{% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %}
+   {% set furo_hide_toc_orig = furo_hide_toc %}
+   {% set furo_hide_toc=false %}
+{% endif %}
+
+{% block right_sidebar %}
+<div class="toc-sticky toc-scroll">
+   {% if not furo_hide_toc_orig %}
+    <div class="toc-title-container">
+      <span class="toc-title">
+       {{ _("Contents") }}
+      </span>
+    </div>
+    <div class="toc-tree-container">
+      <div class="toc-tree">
+        {{ toc }}
+      </div>
+    </div>
+   {% endif %}
+    {% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %}
+    <div class="relatedlinks-title-container">
+      <span class="relatedlinks-title">
+       Related links
+      </span>
+    </div>
+    <div class="relatedlinks-container">
+      <div class="relatedlinks">
+        {% if meta.discourse and discourse_prefix %}
+          {{ discourse_links(meta.discourse) }}
+        {% endif %}
+        {% if meta.relatedlinks %}
+          {{ related_links(meta.relatedlinks) }}
+        {% endif %}
+      </div>
+    </div>
+    {% endif %}
+  </div>
+{% endblock right_sidebar %}

doc/.sphinx/_templates/sidebar/search.html

@@ -0,0 +1,7 @@
+<form class="sidebar-search-container" method="get" action="{{ pathto('search') }}" role="search">
+    <input class="sidebar-search" placeholder="{{ _("Search") }}" name="q" aria-label="{{ _("Search" ) }}">
+    <input type="submit" value="Go">
+    <input type="hidden" name="check_keywords" value="yes">
+    <input type="hidden" name="area" value="default">
+  </form>
+  <div id="searchbox"></div>

doc/.sphinx/requirements.txt

@@ -1,6 +1,13 @@
+sphinx
+sphinx-autobuild
+sphinx-design
 furo
-m2r2
-sphinx==5.1.1
-sphinx_autobuild
-sphinx_copybutton
-sphinx_design
+sphinx-tabs
+sphinx-reredirects
+pyspelling
+sphinxext-opengraph
+lxd-sphinx-extensions
+sphinx-copybutton
+myst-parser
+sphinxcontrib-jquery
+sphinx-notfound-page

doc/.sphinx/spellingcheck.yaml

@@ -0,0 +1,28 @@
+matrix:
+- name: rST files
+  aspell:
+    lang: en
+    d: en_GB
+  dictionary:
+    wordlists:
+    - .wordlist.txt
+    - .custom_wordlist.txt
+    output: .sphinx/.wordlist.dic
+  sources:
+  - _build/**/*.html
+  pipeline:
+  - pyspelling.filters.html:
+      comments: false
+      attributes:
+      - title
+      - alt
+      ignores:
+      - code
+      - pre
+      - spellexception
+      - link
+      - title
+      - div.relatedlinks
+      - div.visually-hidden
+      - img
+      - a.p-navigation__link

doc/.wokeignore

@@ -0,0 +1,4 @@
+# the cheat sheets contain a link to a repository with a block word which we
+# cannot avoid for now, ie
+# https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+doc-cheat-sheet*

doc/.wordlist.txt

@@ -0,0 +1,41 @@
+
+API
+APIs
+CLI
+Charmhub
+Diátaxis
+EBS
+EKS
+Grafana
+IAM
+ISO
+ISOs
+JSON
+Jira
+Juju
+Kubeflow
+Kubernetes
+Makefile
+MyST
+NodePort
+OLM
+Permalink
+RTD
+ReadMe
+UI
+VM
+YAML
+addons
+balancer
+boolean
+dropdown
+favicon
+installable
+namespace
+namespaces
+observability
+reST
+reStructuredText
+subdirectories
+subfolders
+subtree

doc/Makefile

@@ -10,10 +10,12 @@ VENV          = .sphinx/venv/bin/activate
 
 
 # Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+help: install
+	@. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-install:
+install: .sphinx/venv
+
+.sphinx/venv: .sphinx/requirements.txt
 	@echo "... setting up virtualenv"
 	python3 -m venv .sphinx/venv
 	. $(VENV); pip install --upgrade -r .sphinx/requirements.txt
@@ -30,16 +32,20 @@ install:
                 "* check links: make linkcheck \n" \
                 "* check inclusive language: make woke \n" \
 		"--------------------------------------------------------------- \n"
-run:
+
+.sphinx/requirements.txt:
+	:
+
+run: install
 	. $(VENV); sphinx-autobuild -c . -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)"
 
-html:
+html: install
 	. $(VENV); $(SPHINXBUILD) -c . -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt
 
-epub:
+epub: install
 	. $(VENV); $(SPHINXBUILD) -c . -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt
 
-serve:
+serve: run
 	cd "$(BUILDDIR)"; python3 -m http.server 8000
 
 clean: clean-doc
@@ -48,17 +54,17 @@ clean: clean-doc
 clean-doc:
 	git clean -fx "$(BUILDDIR)"
 
-spelling: html
+spelling: install html
 	. $(VENV) ; python3 -m pyspelling -c .sphinx/spellingcheck.yaml
 
-linkcheck:
+linkcheck: install
 	. $(VENV) ; $(SPHINXBUILD) -c . -b linkcheck  "$(SOURCEDIR)" "$(BUILDDIR)"
 
 woke:
-	type woke >/dev/null 2>&1 || { snap install woke; exit 1; }
+	type woke >/dev/null 2>&1 || { sudo snap install woke || exit 1; }
 	woke *.rst **/*.rst -c https://github.com/canonical-web-and-design/Inclusive-naming/raw/main/config.yml
 
-.PHONY: help Makefile
+.PHONY: help Makefile install
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

doc/README.md

@@ -1,19 +1,14 @@
 # Documentation
 
-This `doc` folder is the future location of documentation for Subiquity.   This
-will be used to migrate the official documentation to readthedocs, and later
-will be the home of that documentation.
+This `doc` folder is the location of documentation for Subiquity.
 
-The `../documentation` folder is the existing location for this sort of
-documentation.  As the RTD version is not yet ready, documentation changes
-should be made to `../documentation` until this README is updated to say
-otherwise.  As such, please make any desired documentation changes to
-`../documentation`.
+In the not distant past, there was also a `../documentation` folder, but that
+is now an obsolete copy of what was on Discourse.
 
 # Local preview
 
 To build this documentation, you can run `make install` from this folder to
-create the virtual environment. 
+create the virtual environment.
 
 Then run the `make run` command, which will build a html version of the docs,
 and serve the docs in the virtual environment. This is very convenient if you

doc/_static/css/logo.css

@@ -1,7 +0,0 @@
-.sidebar-brand.centered {
-    text-align: start;
-}
-.sidebar-logo {
-    max-width: 44px;
-    margin: initial;
-}

doc/conf.py

@@ -1,138 +1,128 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Path setup --------------------------------------------------------------
-
-import datetime
-import os
 import sys
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown:
+sys.path.append('./')
+from custom_conf import *
 
-#sys.path.insert(0, os.path.abspath('../../'))
-#sys.path.insert(0, os.path.abspath('../'))
-#sys.path.insert(0, os.path.abspath('./'))
-#sys.path.insert(0, os.path.abspath('.'))
+# Configuration file for the Sphinx documentation builder.
+# You should not do any modifications to this file. Put your custom
+# configuration into the custom_conf.py file.
+# If you need to change this file, contribute the changes upstream.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Project information -----------------------------------------------------
-
-project = 'Ubuntu Install Guide'
-copyright = 'Canonical Group Ltd'
-
-# -- General configuration ---------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = '5.1.1'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
+############################################################
+### Extensions
+############################################################
 
 extensions = [
-    'sphinx.ext.intersphinx',
-    'sphinx_copybutton',
     'sphinx_design',
+    'sphinx_tabs.tabs',
+    'sphinx_reredirects',
+    'canonical.youtube-links',
+    'canonical.related-links',
+    'canonical.custom-rst-roles',
+    'canonical.terminal-output',
+    'sphinx_copybutton',
+    'sphinxext.opengraph',
+    'myst_parser',
+    'sphinxcontrib.jquery',
+    'notfound.extension'
+]
+extensions.extend(custom_extensions)
+
+### Configuration for extensions
+
+# Additional MyST syntax
+myst_enable_extensions = [
+    'substitution',
+    'deflist'
 ]
 
-intersphinx_mapping = {
-    'cloud-init': (
-        'https://canonical-cloud-init.readthedocs-hosted.com/en/latest',
-         None
-    )
+# Used for related links
+if 'discourse' in html_context:
+    html_context['discourse_prefix'] = html_context['discourse'] + '/t/'
+
+# The default for notfound_urls_prefix usually works, but not for
+# documentation on documentation.ubuntu.com
+if slug:
+    notfound_urls_prefix = '/' + slug + '/en/latest/'
+
+notfound_context = {
+    'title': 'Page not found',
+    'body': '<h1>Page not found</h1>\n\n<p>Sorry, but the documentation page that you are looking for was not found.</p>\n<p>Documentation changes over time, and pages are moved around. We try to redirect you to the updated content where possible, but unfortunately, that didn\'t work this time (maybe because the content you were looking for does not exist in this version of the documentation).</p>\n<p>You can try to use the navigation to locate the content you\'re looking for, or search for a similar page.</p>\n',
 }
 
-# Add any paths that contain templates here, relative to this directory.
+# Default image for OGP (to prevent font errors, see
+# https://github.com/canonical/sphinx-docs-starter-pack/pull/54 )
+if not 'ogp_image' in locals():
+    ogp_image = 'https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg'
 
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
-# The root toctree document.
-root_doc = 'index'
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-
-# version = version.version_string()
-# release = version
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
+############################################################
+### General configuration
+############################################################
 
 exclude_patterns = [
-    '.sphinx/venv/*',
-    'README.md',
+    '_build',
+    'Thumbs.db',
+    '.DS_Store',
+    '.sphinx',
 ]
+exclude_patterns.extend(custom_excludes)
 
-# Sphinx-copybutton config options:
-# 1) prompt to be stripped from copied code.
-# 2) Set to copy all lines (not just prompt lines) to ensure multiline snippets
-# can be copied even if they don't contain an EOF line.
-copybutton_prompt_text = '$ '
-copybutton_only_copy_prompt_lines = False
+rst_epilog = '''
+.. include:: /reuse/links.txt
+'''
+if 'custom_rst_epilog' in locals():
+    rst_epilog = custom_rst_epilog
 
-# -- Options for HTML output -------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
-html_theme = 'furo'
-html_logo = '_static/ubuntu_logo.png'
-html_theme_options = {
-    'light_css_variables': {
-        'color-sidebar-background-border': 'none',
-        'font-stack': 'Ubuntu, -apple-system, Segoe UI, Roboto, Oxygen, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif',
-        'font-stack--monospace': 'Ubuntu Mono variable, Ubuntu Mono, Consolas, Monaco, Courier, monospace',
-        'color-foreground-primary': '#111',
-        'color-foreground-secondary': 'var(--color-foreground-primary)',
-        'color-foreground-muted': '#333',
-        'color-background-secondary': '#FFF',
-        'color-background-hover': '#f2f2f2',
-        'color-brand-primary': '#111',
-        'color-brand-content': '#06C',
-        'color-inline-code-background': 'rgba(0,0,0,.03)',
-        'color-sidebar-link-text': '#111',
-        'color-sidebar-item-background--current': '#ebebeb',
-        'color-sidebar-item-background--hover': '#f2f2f2',
-        'sidebar-item-line-height': '1.3rem',
-        'color-link-underline': 'var(--color-background-primary)',
-        'color-link-underline--hover': 'var(--color-background-primary)',
-    },
-    'dark_css_variables': {
-        'color-foreground-secondary': 'var(--color-foreground-primary)',
-        'color-foreground-muted': '#CDCDCD',
-        'color-background-secondary': 'var(--color-background-primary)',
-        'color-background-hover': '#666',
-        'color-brand-primary': '#fff',
-        'color-brand-content': '#06C',
-        'color-sidebar-link-text': '#f7f7f7',
-        'color-sidebar-item-background--current': '#666',
-        'color-sidebar-item-background--hover': '#333',
-    },
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
 }
 
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named 'default.css' will overwrite the builtin 'default.css'.
-html_static_path = ['_static']
+if not 'conf_py_path' in html_context and 'github_folder' in html_context:
+    html_context['conf_py_path'] = html_context['github_folder']
 
-# If you ever want to use the feedback button, turn on GH issues and then
-# uncomment the github_issue_links files
+# For ignoring specific links
+linkcheck_anchors_ignore_for_url = [
+    r'https://github\.com/.*'
+]
+linkcheck_anchors_ignore_for_url.extend(custom_linkcheck_anchors_ignore_for_url)
+
+############################################################
+### Styling
+############################################################
+
+# Find the current builder
+builder = 'dirhtml'
+if '-b' in sys.argv:
+    builder = sys.argv[sys.argv.index('-b')+1]
+
+# Setting templates_path for epub makes the build fail
+if builder == 'dirhtml' or builder == 'html':
+    templates_path = ['.sphinx/_templates']
+
+# Theme configuration
+html_theme = 'furo'
+html_last_updated_fmt = ''
+html_permalinks_icon = '¶'
+
+############################################################
+### Additional files
+############################################################
+
+html_static_path = ['.sphinx/_static']
 
 html_css_files = [
-    'css/logo.css',
-#    'css/github_issue_links.css',
-    'css/custom.css',
-]
-html_js_files = [
-#    'js/github_issue_links.js',
+    'custom.css',
+    'header.css',
+    'github_issue_links.css',
+    'furo_colors.css'
 ]
+html_css_files.extend(custom_html_css_files)
+
+html_js_files = ['header-nav.js']
+if 'github_issues' in html_context and html_context['github_issues'] and not disable_feedback_button:
+    html_js_files.append('github_issue_links.js')
+html_js_files.extend(custom_html_js_files)

doc/custom_conf.py

@@ -0,0 +1,179 @@
+import datetime
+
+# Custom configuration for the Sphinx documentation builder.
+# All configuration specific to your project should be done in this file.
+#
+# The file is included in the common conf.py configuration file.
+# You can modify any of the settings below or add any configuration that
+# is not covered by the common conf.py file.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+############################################################
+### Project information
+############################################################
+
+# Product name
+project = 'Ubuntu installation'
+author = 'Canonical Group Ltd'
+
+# Uncomment if your product uses release numbers
+# release = '1.0'
+
+# The default value uses the current year as the copyright year.
+#
+# For static works, it is common to provide the year of first publication.
+# Another option is to give the first year and the current year
+# for documentation that is often changed, e.g. 2022–2023 (note the en-dash).
+#
+# A way to check a GitHub repo's creation date is to obtain a classic GitHub
+# token with 'repo' permissions here: https://github.com/settings/tokens
+# Next, use 'curl' and 'jq' to extract the date from the GitHub API's output:
+#
+# curl -H 'Authorization: token <TOKEN>' \
+#   -H 'Accept: application/vnd.github.v3.raw' \
+#   https://api.github.com/repos/canonical/<REPO> | jq '.created_at'
+
+copyright = '%s, %s' % (datetime.date.today().year, author)
+
+## Open Graph configuration - defines what is displayed in the website preview
+# The URL of the documentation output
+ogp_site_url = 'https://canonical-subiquity.readthedocs-hosted.com/'
+# The documentation website name (usually the same as the product name)
+ogp_site_name = 'Ubuntu Installation Guide'
+# An image or logo that is used in the preview
+ogp_image = 'https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg'
+
+# Update with the favicon for your product (default is the circle of friends)
+html_favicon = '.sphinx/_static/favicon.png'
+
+# (Some settings must be part of the html_context dictionary, while others
+#  are on root level. Don't move the settings.)
+html_context = {
+
+    # Change to the link to your product website (without "https://")
+    'product_page': 'ubuntu.com/download',
+
+    # Add your product tag to ".sphinx/_static" and change the path
+    # here (start with "_static"), default is the circle of friends
+    'product_tag': '_static/tag.png',
+
+    # Change to the discourse instance you want to be able to link to
+    # using the :discourse: metadata at the top of a file
+    # (use an empty value if you don't want to link)
+    'discourse': 'https://discourse.ubuntu.com/c/foundations/',
+
+    # Change to the GitHub info for your project
+    'github_url': 'https://github.com/canonical/subiquity',
+
+    # Change to the branch for this version of the documentation
+    'github_version': 'main',
+
+    # Change to the folder that contains the documentation
+    # (usually "/" or "/docs/")
+    'github_folder': '/doc/',
+
+    # Change to an empty value if your GitHub repo doesn't have issues enabled.
+    # This will disable the feedback button and the issue link in the footer.
+    'github_issues': 'https://bugs.launchpad.net/subiquity',
+
+    # Controls the existence of Previous / Next buttons at the bottom of pages
+    # Valid options: none, prev, next, both
+    'sequential_nav': "none"
+}
+
+# If your project is on documentation.ubuntu.com, specify the project
+# slug (for example, "lxd") here.
+slug = ""
+
+############################################################
+### Redirects
+############################################################
+
+# Set up redirects (https://documatt.gitlab.io/sphinx-reredirects/usage.html)
+# For example: 'explanation/old-name.html': '../how-to/prettify.html',
+
+redirects = {}
+
+############################################################
+### Link checker exceptions
+############################################################
+
+# Links to ignore when checking links
+
+linkcheck_ignore = [
+    'http://127.0.0.1:8000'
+    ]
+
+# Pages on which to ignore anchors
+# (This list will be appended to linkcheck_anchors_ignore_for_url)
+
+custom_linkcheck_anchors_ignore_for_url = [
+    ]
+
+############################################################
+### Additions to default configuration
+############################################################
+
+## The following settings are appended to the default configuration.
+## Use them to extend the default functionality.
+
+# Add extensions
+custom_extensions = [
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.extlinks'
+]
+
+# Add files or directories that should be excluded from processing.
+custom_excludes = [
+    'doc-cheat-sheet*',
+    '.sphinx/venv/*',
+    'README.md',
+]
+
+# Add CSS files (located in .sphinx/_static/)
+custom_html_css_files = []
+
+# Add JavaScript files (located in .sphinx/_static/)
+custom_html_js_files = []
+
+## The following settings override the default configuration.
+
+# Specify a reST string that is included at the end of each file.
+# If commented out, use the default (which pulls the reuse/links.txt
+# file into each reST file).
+custom_rst_epilog = '''
+.. include:: /reuse/substitutions.txt
+.. include:: /reuse/links.txt
+'''
+# By default, the documentation includes a feedback button at the top.
+# You can disable it by setting the following configuration to True.
+disable_feedback_button = False
+
+############################################################
+### Additional configuration
+############################################################
+
+## Add any configuration that is not covered by the common conf.py file.
+
+intersphinx_mapping = {
+    'cloud-init': (
+        'https://canonical-cloud-init.readthedocs-hosted.com/en/latest',
+         None
+    )
+}
+
+# The root toctree document.
+root_doc = 'index'
+
+# Sphinx-copybutton config options:
+# 1) prompt to be stripped from copied code.
+# 2) Set to copy all lines (not just prompt lines) to ensure multiline snippets
+# can be copied even if they don't contain an EOF line.
+copybutton_prompt_text = '$ '
+copybutton_only_copy_prompt_lines = False
+
+extlinks = {
+    'manualpage': ( 'https://manpages.ubuntu.com/manpages/lunar/en/%s', '' )
+}

doc/development/index.rst

@@ -1,33 +0,0 @@
-Development
-***********
-
-Subiquity is an open source project that warmly welcomes community
-projects, contributions, suggestions, fixes and constructive feedback. If you
-would like to contribute to Subiquity, this set of documentation will help
-orient you with our processes.
-
------
-
-Contributing
-============
-
-.. toctree::
-   :maxdepth: 1
-
-Debugging and reporting
-=======================
-
-.. toctree::
-   :maxdepth: 1
-
-Testing
-=======
-
-.. toctree::
-   :maxdepth: 1
-
-Documentation
-=============
-
-.. toctree::
-   :maxdepth: 1

doc/explanation/cloudinit-autoinstall-interaction.rst

@@ -0,0 +1,35 @@
+.. _cloudinit-autoinstall-interaction:
+
+Cloud-init and autoinstall interaction
+======================================
+
+While cloud-init may provide the autoinstall configuration to the Ubuntu
+installer, it does not process the autoinstall directives itself.
+
+Cloud-init runs in both the ephemeral system (during installation) and in the target
+system during first boot. Cloud-init then becomes inert for every subsequent
+reboot.
+
+To modify the ephemeral system with cloud-init, any
+:external+cloud-init:ref:`#cloud-config module schema keys<modules>` can
+be provided. If instead cloud-init directives are intended to modify the system
+being installed, they must appear under a :ref:`ai-user-data` section under
+``autoinstall:``.
+
+.. code-block:: yaml
+
+    #cloud-config
+    # cloud-init directives may optionally be specified here.
+    # These directives affect the ephemeral system performing the installation.
+
+    autoinstall:
+        # autoinstall directives must be specified here, not directly at the
+        # top level.  These directives are processed by the Ubuntu Installer,
+        # and configure the target system to be installed.
+
+        user-data:
+            # cloud-init directives may also be optionally be specified here.
+            # These directives also affect the target system to be installed,
+            # and are processed on first boot.
+
+For an overview of the methods used to provide the autoinstall configuration to the Ubuntu installer, go to :ref:`Providing autoinstall configuration <providing-autoinstall>`.

doc/explanation/configure-storage.rst

@@ -1,176 +0,0 @@
-.. _configure-storage:
-
-Configuring storage
-*******************
-
-There are a lot of options for storage configuration with the Subiquity
-installer. This guide will walk you through some of the common options for an
-Ubuntu Server installation.
-
-Guided options
-==============
-
-.. image:: figures/configure-storage-guided-options.png
-   :alt:
-
-Selecting "Use an entire disk" on the Guided storage configuration screen will
-install Ubuntu onto the selected disk, replacing any partitions or data already
-there.
-
-You can choose whether or not to set up LVM, and if you do, whether or not to
-encrypt the volume with LUKS. If you encrypt the volume, you need to choose a
-passphrase that will need to be entered each time the system boots.
-
-If you select "Custom storage layout", no configuration will be applied to the
-disks.
-
-In either case, the installer moves onto the main storage customisation screen.
-
-The main storage screen
-=======================
-
-.. image:: figures/configure-storage-main-screen.png
-   :alt:
-
-This screen presents a summary of the current storage configuration. Each
-device or partition of a device corresponds to a different row (which can be
-selected), and pressing :kbd:`Enter` or :kbd:`space` while a device is selected
-opens a menu of actions that apply to that device.
-
-Partitions
-==========
-
-.. image:: figures/configure-storage-partitions.png
-   :alt:
-
-To add a partition to a device, select "Add GPT Partition" for that device.
-
-.. image:: figures/configure-storage-GPT-partition.png
-   :alt:
-
-You can leave "Size" blank to use all the remaining space on the device.
-
-RAID
-====
-
-.. image:: figures/configure-storage-raid.png
-   :alt:
-
-`Linux software RAID <https://raid.wiki.kernel.org/index.php/Linux_Raid>`_
-(where RAID stands for "Redundant Array of Inexpensive Disks") can be used to
-combine several disks into a single device that is (usually) tolerant to any
-one disk failure.
-
-A software RAID device can be created out of entire disks or unformatted
-partitions. Select the "Create software RAID ("MD")" button to open the
-creation dialog.
-
-The server installer supports devices with RAID level 0, 1, 5, 6 or 10 being
-created. It does not allow customising other options such as metadata format or
-RAID10 layout at this time. See the
-`Linux RAID documentation <https://raid.wiki.kernel.org/index.php/Linux_Raid>`_
-for more details.
-
-A software RAID device can be formatted and mounted directly, can be
-partitioned into several partitions, and can even be used as part of another
-RAID device or LVM volume group.
-
-Logical Volume Manager (LVM)
-============================
-
-.. image:: figures/configure-storage-lvm.png
-   :alt:
-
-The LVM is a system of managing logical volumes, or filesystems, that is much
-more advanced and flexible than the traditional method of partitioning a disk
-into one or more segments and formatting that partition with a filesystem. It
-can be used to combine several disks into one larger pool of storage but it
-offers advantages even in a single disk system, such as snapshots and easy
-resizing of logical volumes.
-
-As with RAID, a LVM volume group can be created out of entire disks or
-unformatted partitions. Select the "Create LVM volume group" button to open
-the creation dialog.
-
-Once a volume group has been created, it can be divided into named logical
-volumes which can then be formatted and mounted. It generally makes sense to
-leave some space in the volume group for storage of snapshots and creation of
-more logical volumes as needed.
-
-The server installer does not supported configuring any of the many, many
-options that LVM supports when creating volume groups and logical volumes.
-
-Selecting boot devices
-======================
-
-.. image:: figures/configure-storage-boot-devices.png
-   :alt:
-
-On all architectures other than s390x, the bootloader needs to be installed to
-a disk in such a way that the system firmware can find it on boot. By default,
-the first device to have a partition created on it is selected as a boot device
-but this can be changed later.
-
-On amd64 and arm64 systems, multiple disks can be selected as boot devices,
-which means a system can be configured so that it will continue to boot after
-a failure of any one drive (assuming the root filesystem is placed on a RAID).
-The bootloader will be installed to each of these drives, and the operating
-system configured to install new versions of GRUB to each drive as it is
-updated.
-
-amd64 systems use GRUB as the bootloader. amd64 systems can boot in either UEFI
-or legacy (sometimes called "BIOS") mode (many systems can be configured to
-boot in either mode) and the bootloader is located completely differently in
-the two modes.
-
-Legacy mode
------------
-
-In legacy mode, the bootloader is read from the first "sector" of a hard drive
-(exactly which hard drive is up to the system firmware, which can usually be
-configured in a vendor-specific way). The installer will write GRUB to the
-start of all disks selected as a boot devices. As GRUB does not entirely fit
-in one sector, a small unformatted partition is needed at the start of the
-disk, which will automatically be created when a disk is selected as a boot
-device (a disk with an existing GPT partition table can only be used as a boot
-device if it has this partition).
-
-UEFI mode
----------
-
-In UEFI mode, the bootloader loaded from a "EFI System Partition" (ESP), which
-is a partition with a particular type GUID. The installer automatically creates
-an ESP (with minimum size 538 MiB) on a disk when it is selected as a boot
-device and will install GRUB there (a disk with an existing partition table can
-only be used as a boot device if it has an ESP -- bootloaders for multiple
-operating systems can be installed into a single ESP). UEFI defines a standard
-way to configure the way in which the operating system is chosen on boot, and
-the installer uses this to configure the system to boot the just-installed
-operating system. One of the ESPs must be mounted at ``/boot/efi``.
-
-Supported arm64 servers boot using UEFI, and are configured the same way as an
-UEFI-booting amd64 system.
-
-ppc64el systems also load their bootloader (Petitboot, a small linux kernel)
-from a "PReP" partition with a special flag, so in most ways they are similar
-to a UEFI system. The installer only supports one PReP partition at this time.
-
-Limitations and workarounds
-===========================
-
-Currently, the installer cannot **edit** partition tables. You can use existing
-partitions or reformat a drive entirely, but you cannot (for example) remove a
-large partition and replace it with two smaller ones.
-
-The installer allows the creation of LVM volume groups and logical volumes and
-MD raid devices, but does not allow tweaking of the parameters -- for example,
-all logical volumes are linear and all MD raid devices use the default metadata
-format (1.2).
-
-These limits can both be worked around in the same way: drop to a shell and use
-the usual shell commands to edit the partition table or create the LV or RAID
-with desired parameters, and then select these partitions or devices as mount
-points in the installer. Any changes you make while the installer is running
-but before altering the storage configuration will reflected in the installer.
-
-The installer cannot yet configure iSCSI mounts or btrfs subvolumes.

doc/explanation/index.rst

@@ -1,17 +1,15 @@
 Explanation
-***********
+===========
 
-Our explanatory and conceptual guides are written to provide a better
-understanding of how Subiquity works. They enable you to expand your
-knowledge and become better at using and configuring Subiquity.
+The explanatory and conceptual guides are written to provide a better understanding of how Subiquity works. They enable you to expand your knowledge and become better at using and configuring Subiquity.
 
 -----
 
 About the Server installer
-==========================
+--------------------------
 
 .. toctree::
    :maxdepth: 1
-   
-   operate-server-installer
-   configure-storage
+
+   cloudinit-autoinstall-interaction
+   zero-touch-autoinstall

doc/explanation/operate-server-installer.rst

@@ -1,96 +0,0 @@
-.. _operate-server-installer:
-
-Operating the Server installer
-******************************
-
-This document explains how to use the installer in general terms. For a
-step-by-step guide through the screens of the installer, you can use our
-`screen-by-screen reference guide <https://discourse.ubuntu.com/t/draft-using-the-server-installer-step-by-step/16690>`_.
-
-Get the installer
-=================
-
-Installer images are made (approximately) daily and are available from
-https://cdimage.ubuntu.com/ubuntu-server/daily-live/current/. These are not
-tested as extensively as the images from release day, but they contain the
-latest packages and installer, so fewer updates will be required during or
-after installation.
-
-You can download the server installer for amd64 from
-https://ubuntu.com/download/server and other architectures from
-http://cdimage.ubuntu.com/releases/20.04/release/.
-
-Installer UI navigation
-=======================
-
-In general, the installer can be used with the :kbd:`up` and :kbd:`down` arrows
-and :kbd:`space` or :kbd:`Enter` keys and a little typing. 
-
-:kbd:`Tab` and :kbd:`Shift` + :kbd:`Tab` move the focus down and up respectively.
-:kbd:`Home` / :kbd:`End` / :kbd:`Page Up` / :kbd:`Page Down` can be used to
-navigate through long lists more quickly in the usual way.
-
-Running the installer over serial
-=================================
-
-By default, the installer runs on the first virtual terminal, ``tty1``. This
-is what is displayed on any connected monitor by default. However, servers do
-not always have a monitor. Some out-of-band management systems provide a
-remote virtual terminal, but sometimes it is necessary to run the installer on
-the serial port. To do this, the kernel command line needs to
-`have an appropriate console <https://www.kernel.org/doc/html/latest/admin-guide/serial-console.html>`_
-specified on it -- a common value is ``console=ttyS0`` but this is not
-something that can be generically documented.
-
-When running on serial, the installer starts in a basic mode that uses only
-the ASCII character set and black and white colours. If you are connecting from
-a terminal emulator such as gnome-terminal that supports Unicode and rich
-colours you can switch to "rich mode" which uses Unicode, colours and supports
-many languages.
-
-.. _connect-via-ssh:
-
-Connecting to the installer over SSH
-====================================
-
-If the only available terminal is very basic, an alternative is to connect via
-SSH. If the network is up by the time the installer starts, instructions are
-offered on the initial screen in basic mode. Otherwise, instructions are
-available from the help menu once networking is configured.
-
-In addition, connecting via SSH is assumed to be capable of displaying all
-Unicode characters, enabling more translations to be used than can be displayed
-on a virtual terminal.
-
-Help menu
-=========
-
-The help menu is always in the top right of the screen. It contains help --
-both general and for the currently displayed screen -- and some general actions.
-
-Switching to a shell prompt
----------------------------
-
-You can switch to a shell at any time by selecting "Enter shell" from the help
-menu, or pressing :kbd:`Control` + :kbd:`Z` or :kbd:`F2`.
-
-If you are accessing the installer via ``tty1``, you can also access a shell
-by switching to a different virtual terminal (:kbd:`Control` + :kbd:`Alt` +
-arrow, or :kbd:`Control` + :kbd:`Alt` + number keys, to move between virtual
-terminals).
-
-Global keys
-===========
-
-There are some global keys you can press at any time:
-
-
-====================================  =============================================
-Key                                   Action
-====================================  =============================================
-:kbd:`ESC`                            Go back
-:kbd:`F1`                             Open help menu
-:kbd:`Control` + :kbd:`Z`, :kbd:`F2`  Switch to shell
-:kbd:`Control` + :kbd:`L`, :kbd:`F3`  Redraw screen
-:kbd:`Control` + :kbd:`T`, :kbd:`F4`  Toggle rich mode (colour, Unicode) on and off
-====================================  =============================================

doc/explanation/zero-touch-autoinstall.rst

@@ -0,0 +1,18 @@
+Zero-touch deployment with autoinstall
+======================================
+
+The Ubuntu Installer contains a safeguard, intended to prevent USB Flash Drives
+with an :code:`autoinstall.yaml` file from wiping out the wrong system.
+
+Before the Ubuntu Installer actually makes changes to the target system, a
+prompt is shown. ::
+
+    start: subiquity/Meta/status_GET
+    Confirmation is required to continue.
+    Add 'autoinstall' to your kernel command line to avoid this
+
+
+    Continue with autoinstall? (yes|no)
+
+To bypass this prompt, arrange for the argument :code:`autoinstall` to be
+present on the kernel command line.

doc/google8dda472a993637b7.html

@@ -0,0 +1 @@
+google-site-verification: google8dda472a993637b7.html

doc/howto/autoinstall-quickstart-s390x.rst

@@ -1,75 +1,75 @@
-.. _autoinstall-quickstart-s390x:
+.. _autoinstall_quick_start_s390x:
 
 Autoinstall quick start for s390x
-*********************************
+=================================
 
-The intent of this page is to provide simple instructions to perform an
-autoinstall in a VM on your machine on s390x.
+This guide provides instructions on how to use autoinstall with a current version of Ubuntu for the s390x architecture in a virtual machine (VM) on your computer.
 
-This page is just a slightly adapted page of the
-`autoinstall quickstart page<autoinstall_quickstart>` mapped to s390x.
+For older Ubuntu releases, substitute the version in the name of the ISO image. The instructions should otherwise be the same. See :ref:`Autoinstall quick start<autoinstall_quick_start>` for instructions on installing on the amd64 architecture.
 
-Download an ISO
-===============
+Download the ISO
+----------------
 
-At the time of writing (just after the Kinetic release), the best place to go
-is here:
-https://cdimage.ubuntu.com/ubuntu/releases/22.10/release/
-
-..code-block:: bash
-
-    wget https://cdimage.ubuntu.com/ubuntu/releases/22.10/release/ubuntu-22.10-live-server-s390x.iso -P ~/Downloads
+Download the latest release of the Ubuntu Server image (ISO) from the `Ubuntu ISO download page`_ (currently |ubuntu-latest-version| (|ubuntu-latest-codename|)).
 
 Mount the ISO
-=============
+-------------
 
-.. code-block:: bash
+Make the content of the ISO image accessible from a local directory:
+
+.. code:: none
 
     mkdir -p ~/iso
-    sudo mount -r ~/Downloads/ubuntu-22.10-live-server-s390x.iso ~/iso
+    sudo mount -r ~/Downloads/ubuntu-<version-number>-live-server-s390x.iso ~/iso
 
-Write your autoinstall config
-=============================
+Change ``<version-number>`` to match the number of the release you have downloaded.
 
-This means creating cloud-init config as follows:
+Write your autoinstall configuration
+------------------------------------
 
-.. code-block:: bash
+Create a cloud-init configuration:
+
+.. code-block:: none
 
     mkdir -p ~/www
     cd ~/www
     cat > user-data << 'EOF'
     #cloud-config
     autoinstall:
-    version: 1
-    identity:
+      version: 1
+      identity:
         hostname: ubuntu-server
         password: "$6$exDY1mhS4KUYCE/2$zmn9ToZwTKLhCw.b4/b.ZRTIZM30JZ4QrOQ2aOXJ8yk96xpcCof0kxKwuX1kqLG/ygbJ1f8wxED22bTL4F46P0"
         username: ubuntu
     EOF
     touch meta-data
 
-The crypted password is just ``ubuntu``.
+The encrypted password is ``ubuntu``.
 
-Serve the cloud-init config over HTTP
-=====================================
+Serve the cloud-init configuration over HTTP
+--------------------------------------------
 
-Leave this running in one terminal window:
+Leave the HTTP server running in a terminal:
 
-.. code-block:: bash
+.. code-block:: none
 
     cd ~/www
     python3 -m http.server 3003
 
 Create a target disk
-====================
+--------------------
 
-Proceed with a second terminal window:
+In a new terminal, install the ``qemu-img`` utility:
 
-.. code-block:: bash
+.. code-block:: none
 
     sudo apt install qemu-utils
     ...
 
+Create the target VM disk for the installation:
+
+.. code-block:: none
+
     qemu-img create -f qcow2 disk-image.qcow2 10G
     Formatting 'disk-image.qcow2', fmt=qcow2 size=10737418240 cluster_size=65536 lazy_refcounts=off refcount_bits=16
 
@@ -85,41 +85,45 @@ Proceed with a second terminal window:
         refcount bits: 16
         corrupt: false
 
-Run the install!
-================
+Run the installation
+--------------------
 
-.. code-block:: bash
+Install the ``kvm`` command:
+
+.. code-block:: none
 
     sudo apt install qemu-kvm
     ...
 
-You may need to add the default user to the ``kvm`` group:  <<BR>>
+Add the default user to the ``kvm`` group:
 
-.. code-block:: bash
+.. code-block:: none
 
     sudo usermod -a -G kvm ubuntu   # re-login to make the changes take effect
 
+Run the installation in a VM. Change ``<version-number>`` in the following command to match the release ISO you downloaded:
+
+.. code-block:: none
+
     kvm -no-reboot -name auto-inst-test -nographic -m 2048 \
         -drive file=disk-image.qcow2,format=qcow2,cache=none,if=virtio \
-        -cdrom ~/Downloads/ubuntu-22.10-live-server-s390x.iso \
+        -cdrom ~/Downloads/ubuntu-<version-number>-live-server-s390x.iso \
         -kernel ~/iso/boot/kernel.ubuntu \
         -initrd ~/iso/boot/initrd.ubuntu \
         -append 'autoinstall ds=nocloud-net;s=http://_gateway:3003/ console=ttysclp0'
 
-This will boot, download the config from the server (set up in the previous
-step) and run the install.
-
-The installer reboots at the end but the ``-no-reboot`` flag to ``kvm`` means
-that ``kvm`` will exit when this happens. It should take about 5 minutes.
+This command boots the VM, downloads the configuration from the server (prepared in the previous step) and runs the installation. The installer reboots at the end. The ``-no-reboot`` option to the ``kvm`` command instructs ``kvm`` to exit on reboot.
 
 Boot the installed system
-=========================
+-------------------------
 
-.. code-block:: bash
+.. code-block:: none
 
     kvm -no-reboot -name auto-inst-test -nographic -m 2048 \
         -drive file=disk-image.qcow2,format=qcow2,cache=none,if=virtio
 
-This will boot into the freshly installed system and you should be able to log
-in as ``ubuntu/ubuntu``.
+This command boots the installed system in the VM. Log in using ``ubuntu`` for both the user name and password.
 
+.. LINKS
+
+.. _Ubuntu ISO download page: https://releases.ubuntu.com/

doc/howto/autoinstall-quickstart.rst

@@ -1,128 +1,114 @@
-.. _autoinstall_quickstart:
+.. _autoinstall_quick_start:
 
 Autoinstall quick start
-***********************
+=======================
 
-The intent of this page is to provide simple instructions to perform an
-autoinstall in a VM on your machine.
+This guide provides instructions on how to use autoinstall with a current version of Ubuntu for the amd64 architecture in a virtual machine (VM) on your computer.
 
-This page assumes that you are installing a recent Ubuntu release. However,
-for older releases, you can substitute the name of the ISO image but the
-instructions should otherwise be the same.
-
-This page also assumes you are on the AMD64 architecture. There is a
-:ref:`version for s390x<autoinstall-quickstart-s390x>` too.
+For older Ubuntu releases, substitute the version in the name of the ISO image. The instructions should otherwise be the same. See :ref:`Autoinstall quick start for s390x<autoinstall_quick_start_s390x>` for instructions on installing on the s390x architecture.
 
 Providing the autoinstall data over the network
-===============================================
+-----------------------------------------------
 
-This method is the one that generalises most easily to doing an entirely
-network-based install, where a machine netboots and then is automatically
-installed.
+This method describes a network-based installation. When booting over a network, use this method to deliver autoinstall to perform the installation.
 
 Download the ISO
-----------------
+~~~~~~~~~~~~~~~~
 
-Go to the `Ubuntu ISO download page`_ and download the latest Ubuntu
-live-server ISO.
+Download the latest release of the Ubuntu Server image (ISO) from the `Ubuntu ISO download page`_ (currently |ubuntu-latest-version| (|ubuntu-latest-codename|)).
 
 Mount the ISO
--------------
+~~~~~~~~~~~~~
 
-.. code-block:: bash
+Make the content of the ISO image accessible from a local directory:
 
-    sudo mount -r ~/Downloads/ubuntu-<release-number>-live-server-amd64.iso /mnt
+.. code:: none
 
-Where you should change `<release-number>` to match the number of the LTS or
-release you have downloaded (e.g., `22.04.3` for Jammy or `23.04` for the Lunar
-interim release).
+    sudo mount -r ~/Downloads/ubuntu-<version-number>-live-server-amd64.iso /mnt
 
-Write your autoinstall config
------------------------------
+Change ``<version-number>`` to match the number of the release you have downloaded.
 
-This means creating cloud-init config as follows:
+Write your autoinstall configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: bash
+Create a cloud-init configuration:
+
+.. code:: none
 
     mkdir -p ~/www
     cd ~/www
     cat > user-data << 'EOF'
     #cloud-config
     autoinstall:
-    version: 1
-    identity:
+      version: 1
+      identity:
         hostname: ubuntu-server
         password: "$6$exDY1mhS4KUYCE/2$zmn9ToZwTKLhCw.b4/b.ZRTIZM30JZ4QrOQ2aOXJ8yk96xpcCof0kxKwuX1kqLG/ygbJ1f8wxED22bTL4F46P0"
         username: ubuntu
     EOF
     touch meta-data
 
-The crypted password is just "ubuntu".
+The encrypted password is ``ubuntu``.
 
-Serve the cloud-init config over HTTP
--------------------------------------
+Serve the cloud-init configuration over HTTP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Leave this running in one terminal window:
+Leave the HTTP server running in a terminal:
 
-.. code-block:: bash
+.. code:: none
 
     cd ~/www
     python3 -m http.server 3003
 
 Create a target disk
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
-.. code-block::
+Create the target VM disk for the installation:
+
+.. code:: none
 
     truncate -s 10G image.img
 
-Run the install!
-----------------
+Run the installation
+~~~~~~~~~~~~~~~~~~~~
 
-As before, you will need to change `<release-number>` in the following command
-to match the release ISO you downloaded.
+Change ``<version-number>`` in the following command to match the release ISO you downloaded.
 
-.. code-block:: bash
+.. code:: none
 
     kvm -no-reboot -m 2048 \
         -drive file=image.img,format=raw,cache=none,if=virtio \
-        -cdrom ~/Downloads/ubuntu-<release-number>-live-server-amd64.iso \
+        -cdrom ~/Downloads/ubuntu-<version-number>-live-server-amd64.iso \
         -kernel /mnt/casper/vmlinuz \
         -initrd /mnt/casper/initrd \
         -append 'autoinstall ds=nocloud-net;s=http://_gateway:3003/'
 
-This will boot, download the config from the server (set up in the previous
-step) and run the install. The installer reboots at the end but the
-``-no-reboot`` flag to ``kvm`` means that ``kvm`` will exit when this happens.
-It should take about 5 minutes.
+This command boots the VM, downloads the configuration from the server (prepared in the previous step) and runs the installation. The installer reboots at the end. The ``-no-reboot`` option to the ``kvm`` command instructs ``kvm`` to exit on reboot.
 
 Boot the installed system
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: bash
+.. code:: none
 
     kvm -no-reboot -m 2048 \
         -drive file=image.img,format=raw,cache=none,if=virtio
 
-This will boot into the freshly installed system and you should be able to log
-in as ``ubuntu/ubuntu``.
+This command boots the installed system in the VM. Log in using ``ubuntu`` for both the user name and password.
 
-Using another volume to provide the autoinstall config
-======================================================
+Using another volume to provide the autoinstall configuration
+-------------------------------------------------------------
 
-This is the method to use when you want to create media that you can just plug
-into a system to have it be installed.
+Use this method to create an installation medium to plug into a computer to have it be installed.
 
-Download the live-server ISO
-----------------------------
+Download the ISO
+~~~~~~~~~~~~~~~~
 
-Go to the `Ubuntu ISO download page`_ and download the latest Ubuntu
-live-server ISO.
+Download the latest Ubuntu Server ISO from the `Ubuntu ISO download page`_.
 
-Create your user-data and meta-data files
------------------------------------------
+Create user-data and meta-data files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: bash
+.. code:: none
 
     mkdir -p ~/cidata
     cd ~/cidata
@@ -137,55 +123,57 @@ Create your user-data and meta-data files
     EOF
     touch meta-data
 
-The crypted password is just ``ubuntu``.
+The encrypted password is ``ubuntu``.
 
 Create an ISO to use as a cloud-init data source
-------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: bash
+Install utilities for working with cloud images:
+
+.. code:: none
 
     sudo apt install cloud-image-utils
+
+Create the ISO image for cloud-init:
+
+.. code:: none
+
     cloud-localds ~/seed.iso user-data meta-data
 
 Create a target disk
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: bash
+Create the target VM disk for the installation:
+
+.. code:: none
 
     truncate -s 10G image.img
 
-Run the install!
-----------------
+Run the installation
+~~~~~~~~~~~~~~~~~~~~
 
-As before, you will need to change `<release-number>` in the following command
-to match the release ISO you downloaded.
+Change ``<version-number>`` in the following command to match the release ISO you downloaded.
 
-.. code-block:: bash
+.. code:: none
 
     kvm -no-reboot -m 2048 \
         -drive file=image.img,format=raw,cache=none,if=virtio \
         -drive file=~/seed.iso,format=raw,cache=none,if=virtio \
-        -cdrom ~/Downloads/ubuntu-<release-number>-live-server-amd64.iso
+        -cdrom ~/Downloads/ubuntu-<version-number>-live-server-amd64.iso
 
-This will boot and run the install. Unless you interrupt boot to add
-'autoinstall' to the kernel command line, the installer will prompt for
-confirmation before touching the disk.
+This command boots the system and runs the installation. The installer prompts for a confirmation before modifying the disk. To skip the need for a confirmation, interrupt the booting process, and add the ``autoinstall`` parameter to the kernel command line.
 
-The installer reboots at the end but the ``-no-reboot`` flag to ``kvm`` means
-that ``kvm`` will exit when this happens.
-
-The whole process should take about 5 minutes.
+The installer reboots at the end. The ``-no-reboot`` option to the ``kvm`` command instructs ``kvm`` to exit on reboot.
 
 Boot the installed system
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: bash
+.. code:: none
 
     kvm -no-reboot -m 2048 \
         -drive file=image.img,format=raw,cache=none,if=virtio
 
-This will boot into the freshly installed system and you should be able to log
-in as ``ubuntu/ubuntu``.
+This command boots the installed system in the VM. Log in using ``ubuntu`` for both the user name and password.
 
 .. LINKS
 

doc/howto/basic-server-installation.rst

@@ -0,0 +1,84 @@
+Basic server installation
+=========================
+
+This chapter provides an overview of how to install Ubuntu Server Edition. See also the guide on :ref:`how to operate the installer <operate-server-installer>` for more information on using the installer, and the :ref:`screen-by-screen guide <screen-by-screen>` for more information about each of the installer screens.
+
+Preparing to install
+--------------------
+
+This section explains various aspects to consider before starting the installation.
+
+System requirements
+~~~~~~~~~~~~~~~~~~~
+
+Ubuntu Server Edition provides a common, minimalist base for a variety of server applications, such as file or print services, web hosting, email hosting, etc. This version supports four 64-bit architectures:
+
+* amd64 (AMD64, Intel 64)
+* arm64 (AArch64)
+* ppc64el (POWER8 and POWER9)
+* s390x (IBM Z and LinuxONE)
+
+Recommended system requirements:
+
+* CPU: 1 GHz or better
+* RAM: 1 GB or more
+* Disk: 2.5 GB or more
+
+Perform a system backup
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Before installing Ubuntu Server Edition, back up all system data.
+
+.. warning:: Power failures, configuration mistakes, and other problems occurring during disk (re-)partitioning can result in complete data loss. Always back up your data before performing an installation of a new system.
+
+Download the Server ISO
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Download the amd64 Server Edition from `releases.ubuntu.com <https://releases.ubuntu.com/>`_. Choose the version to install and select the :guilabel:`Server install image` download. Note that the Server download includes the installer.
+
+There are platform-specific how-to guides for installations on:
+
+* `s390x LPAR <https://discourse.ubuntu.com/t/interactive-live-server-installation-on-ibm-z-lpar-s390x/16601>`_
+* `z/VM <https://discourse.ubuntu.com/t/interactive-live-server-installation-on-ibm-z-vm-s390x/16604>`_
+* `ppc64el <https://discourse.ubuntu.com/t/using-a-virtual-cdrom-and-petitboot-to-start-a-live-server-installation-on-ibm-power-ppc64el/16694>`_
+
+Create a bootable USB
+~~~~~~~~~~~~~~~~~~~~~
+
+There are many ways to boot the installer but the simplest and most common way is to `create a bootable USB stick <https://ubuntu.com/tutorials/create-a-usb-stick-on-ubuntu>`_ (`tutorials for other operating systems <https://ubuntu.com/search?q=%22create+a+bootable+USB+stick%22>`_ are also available).
+
+Perform the installation
+------------------------
+
+Now that you have prepared your installation medium, you are ready to install.
+
+Boot the installer
+~~~~~~~~~~~~~~~~~~
+
+Plug the USB stick into the system to be installed and (re)start it.
+
+Many computers automatically boot from available USB or DVD media. If you don't see the boot message and
+the :guilabel:`Welcome` screen, set your computer to boot from the installation media.
+
+.. note:: See your computer manual for instructions on how to select the boot source. You can also watch the screen during computer (re)start for a message with what key to press to access settings or a boot menu. Depending on the manufacturer, this can be :kbd:`Escape`, :kbd:`Enter`, :kbd:`F2`, :kbd:`F10` or :kbd:`F12`. Restart your computer and hold down this key until the boot menu appears, then select the drive with the Ubuntu installation medium. See also `Ubuntu Community documentation on booting from CD/DVD <https://help.ubuntu.com/community/BootFromCD>`_.
+
+After a few moments, the installer starts in its language selection screen.
+
+.. image:: figures/basic-installation-start-screen.png
+   :alt: Welcome screen of the Server installer showing the language selection options
+
+Using the installer
+~~~~~~~~~~~~~~~~~~~
+
+The installer is designed to be easy to use and have sensible default settings. For a first installation, you can accept the defaults:
+
+#. Choose your language.
+#. Update the installer (if offered).
+#. Select your keyboard layout.
+#. Do not configure networking (the installer attempts to configure wired network interfaces via DHCP, but you can continue without networking if this fails).
+#. Do not configure a proxy or custom mirror unless you have to in your network.
+#. For storage, leave :guilabel:`Use an entire disk` checked, and choose a disk to install to, then select :guilabel:`Done` on the configuration screen and confirm the installation.
+#. Enter a username, hostname and password.
+#. On the :guilabel:`SSH Setup` and :guilabel:`Featured Server Snaps` screens, select :guilabel:`Done`.
+#. You now see log messages as the installation is completed.
+#. Select :guilabel:`Reboot` when this is complete, and log in using the username and password provided.

doc/howto/configure-storage.rst

@@ -0,0 +1,108 @@
+.. _configure-storage:
+
+Configuring storage
+===================
+
+This article describes how to use the most common options for storage configuration of the Subiquity installer.
+
+Guided options
+--------------
+
+.. image:: figures/configure-storage-guided-options.png
+   :alt:
+
+Select :guilabel:`Use an entire disk` on the :guilabel:`Guided storage configuration` screen to install Ubuntu to the selected disk, replacing any partitions or data already there.
+
+You can choose whether or not to set up LVM, and if you do, whether or not to encrypt the volume with LUKS. If you encrypt the volume, choose a passphrase to be entered every time the system boots.
+
+Select :guilabel:`Custom storage layout` to apply no configuration to the disks.
+
+The installer then moves to the main storage customisation screen.
+
+The main storage screen
+-----------------------
+
+.. image:: figures/configure-storage-main-screen.png
+   :alt:
+
+This screen presents a summary of the current storage configuration. Each device or partition of a device corresponds to a different row (which can be selected). Press :kbd:`Enter` or :kbd:`space` while a device is selected to open a menu of actions that apply to that device.
+
+Partitions
+----------
+
+.. image:: figures/configure-storage-partitions.png
+   :alt:
+
+To add a partition to a device, select :guilabel:`Add GPT Partition` for that device.
+
+.. image:: figures/configure-storage-GPT-partition.png
+   :alt:
+
+To use all the remaining space on the device, leave :guilabel:`Size` blank.
+
+RAID
+----
+
+.. image:: figures/configure-storage-raid.png
+   :alt:
+
+`Linux software RAID <https://raid.wiki.kernel.org/index.php/Linux_Raid>`_ (Redundant Array of Independent Disks) can be used to combine several disks into a single device that is (usually) tolerant to any one disk failure.
+
+A software RAID device can be created from entire disks or unformatted partitions. Select the :guilabel:`Create software RAID ("MD")` button to open the creation dialog.
+
+The server installer supports RAID levels 0, 1, 5, 6 and 10. It does not allow customising other options, such as metadata format. See the `Linux RAID documentation <https://raid.wiki.kernel.org/index.php/Linux_Raid>`_ for more details.
+
+A software RAID device can be formatted and mounted directly. It can be partitioned into several partitions, and can be used as part of another RAID device or LVM volume group.
+
+Logical Volume Manager (LVM)
+----------------------------
+
+.. image:: figures/configure-storage-lvm.png
+   :alt:
+
+LVM is a system of managing logical volumes, or file systems, that is more advanced and flexible than the traditional method of partitioning a disk into one or more segments and formatting that partition with a file system. LVM can be used to combine several disks into one larger pool of storage. It also offers advantages for single-disk systems, such as snapshots and easy resizing of logical volumes.
+
+As with RAID, a LVM volume group can be created from entire disks or unformatted partitions. Select the :guilabel:`Create LVM volume group` button to open the creation dialog.
+
+Once a volume group has been created, it can be divided into named logical volumes, which can then be formatted and mounted. It is recommended to leave some space in the volume group for storage of snapshots and creation of more logical volumes as needed.
+
+The server installer does not support configuring any LVM options for creating volume groups and logical volumes.
+
+Selecting boot devices
+----------------------
+
+.. image:: figures/configure-storage-boot-devices.png
+   :alt:
+
+On all architectures other than s390x, the bootloader needs to be installed to a disk in such a way that the system firmware can find it on boot. By default, the first device to have a partition created on it is selected as a boot device. This can be changed later.
+
+On amd64 and arm64 systems, multiple disks can be selected as boot devices, which means a system can be configured to continue booting after a failure of any one drive (provided the root file system is placed on a RAID). The bootloader is installed to each of these drives, and the operating system configured to install new versions of GRUB to each drive as it is updated.
+
+amd64 systems use GRUB as the bootloader. amd64 systems can boot in either UEFI (Unified Extensible Firmware Interface) or legacy (sometimes called "BIOS") mode (many systems can be configured to boot in either mode). The bootloader is located in different places in the two modes.
+
+Legacy mode
+~~~~~~~~~~~
+
+In legacy mode, the bootloader is read from the first "sector" of a hard drive (which hard drive depends on the system firmware, which can usually be configured in a vendor-specific way). The installer writes GRUB to the start of all disks selected as boot devices. As GRUB does not entirely fit in one sector, a small unformatted partition is needed at the start of the disk, which is automatically created when a disk is selected as a boot device (a disk with an existing GPT partition table can only be used as a boot device if it has this partition).
+
+UEFI mode
+~~~~~~~~~
+
+In UEFI mode, the bootloader is loaded from an "EFI System Partition" (ESP), which is a partition with a particular GUID type. The installer automatically creates an ESP (with a minimum size of 538 MiB) on a disk when it is selected as a boot device and install GRUB there (a disk with an existing partition table can only be used as a boot device if it has an ESP -- bootloaders for multiple operating systems can be installed into a single ESP).
+
+UEFI defines a standard way to configure the way in which the operating system is chosen on boot, and the installer uses this to configure the system to boot the just-installed operating system. One of the ESPs must be mounted at ``/boot/efi``.
+
+Supported arm64 servers boot using UEFI and are configured the same way as an UEFI-booting amd64 system.
+
+ppc64el systems also load their bootloader (Petitboot, a small Linux kernel) from a PReP (PowerPC Reference Platform) partition with a special flag, so in most ways they are similar to a UEFI system. The installer only supports one PReP partition.
+
+Limitations and workarounds
+---------------------------
+
+The installer cannot **edit** partition tables. You can use existing partitions or reformat a drive entirely, but you cannot, for example, remove a large partition and replace it with two smaller ones.
+
+The installer supports the creation of LVM volume groups, logical volumes, and MD RAID (software RAID) devices, but it does not provide a way to configure parameters. For example, all logical volumes are linear and all MD RAID devices use the default metadata format (1.2).
+
+To work around these limitations, switch to a shell and use shell commands to edit the partition table or create the LV or RAID with desired parameters. Then select these partitions or devices as mount points in the installer. Any changes you make while the installer is running but before altering the storage configuration are reflected in the installer.
+
+The installer cannot configure iSCSI mounts or BTRFS subvolumes.

doc/howto/index.rst

@@ -1,31 +1,29 @@
 .. _howto_index:
 
 How-to guides
-*************
+=============
 
-If you have a specific goal in mind and are already familiar with the basics
-of Subiquity, our how-to guides cover some of the more common operations
-and tasks that you may need to complete.
+If you have a specific goal in mind and are already familiar with the basics of Subiquity, our how-to guides cover some of the more common operations and tasks you may need to complete.
 
-They will help you to achieve a particular end result, but may require you to
-understand and adapt the steps to fit your specific requirements.
+They will help you to achieve a particular end result, but may require you to understand and adapt the steps to fit your specific requirements.
 
 -----
 
-Getting started with Autoinstall
-================================
+Getting started with autoinstall
+--------------------------------
 
 .. toctree::
    :maxdepth: 1
-   
-   Autoinstall quick-start guide <autoinstall-quickstart>
-   Autoinstall quick-start guide for s390x <autoinstall-quickstart-s390x>
 
+   autoinstall-quickstart
+   autoinstall-quickstart-s390x
+   basic-server-installation
+   configure-storage
 
 Found a problem?
-================
+----------------
 
 .. toctree::
    :maxdepth: 1
-   
+
    report-bugs

doc/howto/report-bugs.rst

@@ -1,56 +1,32 @@
 .. _report-bugs:
 
-How to report a problem
-***********************
+Troubleshooting
+===============
 
-We always hope, of course, that every install with the server installer
-succeeds. But reality doesn't always work that way and there will sometimes be
-failures of various kinds. This section explains the most useful way to report
-any failures so that we can fix the bugs causing them, and we'll keep the topic
-up to date as the installer changes.
+This section explains how to deal with installation problems and how to report issues to the Subiquity team.
 
 Update Subiquity
-================
+----------------
 
-The first thing to do is to update your Subiquity snap using `snap refresh`.
-Not only because we fix issues that cause failures over time but also because
-we've been working on features to make failure reporting easier.
+Ensure you're using the latest stable version of the installer. Update the Subiquity snap by running ``snap refresh``.
 
 Crash reports
-=============
+-------------
 
-A failure will result in a crash report being generated which bundles up all
-the information we need to fully diagnose a failure. These live in
-``/var/crash`` in the installer environment, and for Ubuntu 19.10 and newer
-this is persisted to the install media by default (if there is space). 
+A failure results in a crash report being generated in ``/var/crash`` in the installer environment. The crash report includes all information for failure diagnostics. Starting with Ubuntu 19.10, crash reports are saved to the installation medium by default (provided there is enough space).
 
-When an error occurs you are presented with a dialog that allows you to upload
-the report to the error tracker and offers options for continuing. Uploads to
-the error tracker are non-interactive and anonymous, so they are useful for
-tracking which kinds of errors are affecting most users, but they do not give
-us a way to ask you to help diagnose the failure.
+When an error occurs, the installer displays a dialog for uploading the report to the error tracker and offers options for continuing. Uploads to the error tracker are non-interactive and anonymous. This is useful for
+tracking which kinds of errors affect most users.
 
-Create Launchpad bug report
-===========================
+Create a Launchpad bug report
+-----------------------------
 
-You can create a Launchpad bug report, which lets us establish this kind
-of two way communication, based on the contents of a crash report by using the
-standard ``apport-cli`` tool that is part of Ubuntu. Copy the crash report to
-another system, run:
+To create a Launchpad bug report based on the contents of a crash report, use the ``apport-cli`` tool that is part of Ubuntu. Copy the crash report to another system, and follow the prompts after executing:
 
 .. code-block:: bash
 
     apport-cli /path/to/report.crash
 
-and follow the prompts.
-
-You can also run ``apport-cli`` in the installer environment by switching to a
-shell but ``apport`` won't be able to open a browser to allow you to complete
-the report so you'll have to type the URL by hand on another machine.
-
-.. note::
-
-   Bugs for the Subiquity autoinstaller are `tracked in Launchpad <https://bugs.launchpad.net/subiquity>`_.
-
-
+To run ``apport-cli`` in the installer environment, switch to a shell. This way, ``apport`` can not open a browser to for you to complete the report. Instead, it provides a URL for completing the report, which you can do on another computer.
 
+.. note:: Issues for the Subiquity autoinstaller are `tracked in Launchpad <https://bugs.launchpad.net/subiquity>`_.

doc/index.rst

@@ -1,28 +1,19 @@
 .. _index:
 
-Ubuntu Installation documentation
-#################################
+Ubuntu installation guide
+=========================
 
-A single sentence that says what the product is, succinctly and memorably
-consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et
-dolore magna aliqua.
+Subiquity is an installer framework for Ubuntu. It provides the Ubuntu Server with a text-based installation user interface and Ubuntu Core first-boot configuration. Subiquity is also the back end for the Ubuntu Desktop installer.
 
-A paragraph of one to three short sentences, that describe what the product
-does. Urna cursus eget nunc scelerisque viverra mauris in. Nibh mauris cursus
-mattis molestie a iaculis at vestibulum rhoncus est pellentesque elit. Diam
-phasellus vestibulum lorem sed.
+This documentation set offers guidance for installing Ubuntu Server using Subiquity. It also includes instructions on performing an automated installation using the autoinstall feature.
 
-A third paragraph of similar length, this time explaining what need the product
-meets. Dui ut ornare lectus sit amet est. Nunc sed augue lacus viverra vitae
-congue eu consequat ac libero id faucibus nisl tincidunt eget nullam.
-
-Finally, a paragraph that describes whom the product is useful for. Nunc non
-blandit massa enim nec dui nunc mattis enim. Ornare arcu odio ut sem nulla
-pharetra diam porttitor leo a diam sollicitudin tempor id eu. Ipsum dolor sit
-amet consectetur adipiscing elit pellentesque habitant.
+.. note:: The aim is to gradually expand this documentation to cover the installation of all variants of the Ubuntu operating system.
 
 -----
 
+In this documentation
+---------------------
+
 .. grid:: 1 1 2 2
    :gutter: 3
 
@@ -54,34 +45,37 @@ amet consectetur adipiscing elit pellentesque habitant.
 
        Discussion and clarification of key topics
 
-Having trouble? We would like to help!
-======================================
-
-- Links to other communication channels go here
-
 Project and community
-=====================
+---------------------
 
-Subiquity is a member of the Ubuntu family. It's an open source project that
-warmly welcomes community projects, contributions, suggestions, fixes, and
-constructive feedback.
+Subiquity is a member of the Ubuntu family. It's an open source project that warmly welcomes community projects, contributions, suggestions, fixes and constructive feedback. Use the following resources to ask questions, report bugs, contribute translations, or participate in the development of the Ubuntu installer.
 
-* Read our `Code of Conduct`_
-* IRC?
-* Discourse?
-* Contribute?
-* Roadmap?
+Get started:
+  * Read our `Code of Conduct`_
+
+Discuss:
+  * IRC: `Libera.Chat`_, the *#ubuntu-server* channel
+  * Discourse: `Ubuntu Foundations`_
+
+Contribute:
+  * `Contribution guidelines`_ on GitHub
+  * `Issue tracker`_ on Launchpad
+  * `Localisation`_ on Launchpad
 
 .. toctree::
    :hidden:
    :maxdepth: 2
 
-   Introduction to Autoinstall<intro-to-autoinstall>
+   Introduction to autoinstall<intro-to-autoinstall>
    tutorial/index
    howto/index
    reference/index
    explanation/index
-   development/index
 
 .. Links:
-.. _Code of Conduct: https://ubuntu.com/community/code-of-conduct
+.. _Code of Conduct: https://ubuntu.com/community/ethos/code-of-conduct
+.. _Ubuntu Foundations: https://discourse.ubuntu.com/c/foundations/
+.. _Libera.Chat: https://libera.chat/
+.. _Contribution guidelines: https://github.com/canonical/subiquity/blob/main/CONTRIBUTING.md
+.. _Localisation: https://translations.launchpad.net/ubuntu/+source/subiquity/
+.. _Issue tracker: https://bugs.launchpad.net/subiquity

doc/intro-to-autoinstall.rst

@@ -1,7 +1,7 @@
 .. _tutorial_intro-to-autoinstall:
 
 Introduction to autoinstall
-***************************
+===========================
 
 Automatic Ubuntu installation is performed with the autoinstall format.
 You might also know this feature as "unattended", "hands-off" or "preseeded"
@@ -11,15 +11,20 @@ This format is supported in the following installers:
  * Ubuntu Server, version 20.04 and later
  * Ubuntu Desktop, version 23.04 and later
 
-Autoinstallation lets you answer all those configuration questions ahead of
-time with an *autoinstall config* and lets the installation process run without
+Automatic installation lets you answer all configuration questions ahead of
+time with an *autoinstall configuration* and lets the installation process run without
 any interaction.
 
+For more details on the relationship between autoinstall and cloud-init, as well as their respective functions, go to:
 
-Differences from debian-installer preseeding
-============================================
+* :ref:`Cloud-init and autoinstall interaction <cloudinit-autoinstall-interaction>`
+* :ref:`Providing autoinstall configuration <providing-autoinstall>`
 
-*preseeds* are the way to automate an installer based on debian-installer
+
+Differences from `debian-installer` preseeding
+----------------------------------------------
+
+*preseeds* are the way to automate an installer based on `debian-installer`
 (also known as d-i).
 
 Autoinstalls differ from preseeds in the following ways:
@@ -34,223 +39,8 @@ Autoinstalls differ from preseeds in the following ways:
    those.
 
 
-Providing the autoinstall configuration
-=======================================
-
-There are 2 ways to provide the autoinstall configuration:
- * Provide :external+cloud-init:ref:`#cloud-config
-   user-data<user_data_formats-cloud_config>` containing ``autoinstall:``
-   configuration directives to cloud-init at boot time
- * Directly on the install media
-
-Autoinstall by way of cloud-config
-----------------------------------
-
-The suggested way of providing autoinstall config to the Ubuntu installer is
-via cloud-init. This allows the configuration to be applied to the installer
-without having to modify the install media.
-
-The autoinstall config is provided via cloud-init configuration, which is
-almost endlessly flexible. In most scenarios the easiest way will be to provide
-user data via the :external+cloud-init:ref:`datasource_nocloud` data source.
-
-When providing autoinstall via cloud-init, the autoinstall config is provided
-as :external+cloud-init:ref:`user_data_formats-cloud_config`. This
-means we need a :code:`#cloud-config` header. The autoinstall directives are
-placed under a top level :code:`autoinstall:` key, like so:
-
-.. code-block:: yaml
-
-    #cloud-config
-    autoinstall:
-        version: 1
-        ....
-
-.. note::
-
-   :external+cloud-init:ref:`user_data_formats-cloud_config` files must contain
-   the ``#cloud-config`` header to be recognized as a valid cloud config data
-   file.
-
-Autoinstall on the install media
---------------------------------
-
-Another option for supplying autoinstall to the Ubuntu installer is to place a
-file named :code:`autoinstall.yaml` on the install media itself.
-
-There are two potential locations for the :code:`autoinstall.yaml` file:
- * At the root of the "CD-ROM". When you write the installation ISO to a USB
-   Flash Drive, this can be done by copying the :code:`autoinstall.yaml` to the
-   partition containing the contents of the ISO - i.e.,
-   in the directory containing the ``casper`` sub-directory.
- * On the rootfs of the installation system - this option will typically
-   require modifying the installation ISO and is not suggested, but is
-   supported.
-
-Directly specifying autoinstall as a :code:`autoinstall.yaml` file does not
-require a :code:`#cloud-config` header, and does not use a top level
-``autoinstall:`` key. The autoinstall directives are placed at the top
-level. For example:
-
-.. code-block:: yaml
-
-    version: 1
-    ....
-
-
-Cloud-init and autoinstall interaction
-======================================
-
-Cloud-init runs in both the ephemeral system (during install) and in the target
-system during first boot. Cloud-init then becomes inert for every subsequent
-reboot.
-
-While cloud-init may provide the autoinstall configuration to the Ubuntu
-installer, it does not process the autoinstall directives itself.
-
-To modify the ephemeral system with cloud-init, any
-:external+cloud-init:ref:`#cloud-config module schema keys<modules>` can
-be provided. If instead cloud-init directives are intended to modify the system
-being installed, they must appear under a :ref:`ai-user-data` section under
-``autoinstall:``.
-
-.. code-block:: yaml
-
-    #cloud-config
-    # cloud-init directives may optionally be specified here.
-    # These directives affect the ephemeral system performing the install.
-
-    autoinstall:
-        # autoinstall directives must be specified here, not directly at the
-        # top level.  These directives are processed by the Ubuntu Installer,
-        # and configure the target system to be installed.
-
-        user-data:
-            # cloud-init directives may also be optionally be specified here.
-            # These directives also affect the target system to be installed,
-            # and are processed on first boot.
-
-
-Zero-touch deployment with autoinstall
-======================================
-
-The Ubuntu Installer contains a safeguard, intended to prevent USB Flash Drives
-with an :code:`autoinstall.yaml` file from wiping out the wrong system.
-
-Before the Ubuntu Installer actually makes changes to the target system, a
-prompt is shown. ::
-
-    start: subiquity/Meta/status_GET
-    Confirmation is required to continue.
-    Add 'autoinstall' to your kernel command line to avoid this
-
-
-    Continue with autoinstall? (yes|no)
-
-To bypass this prompt, arrange for the argument :code:`autoinstall` to be
-present on the kernel command line.
-
-
-Creating an autoinstall config
-==============================
-
-When any system is installed using the Ubuntu installer, an autoinstall file
-for repeating the install is created at
-:code:`/var/log/installer/autoinstall-user-data`.
-
-
-The structure of an autoinstall configuration
-=============================================
-
-See the :ref:`ai` for full details on the supported autoinstall directives.
-
-A minimal autoinstall configuration in
-:external+cloud-init:ref:`user_data_formats-cloud_config` format looks like:
-
-.. code-block:: yaml
-
-    #cloud-config
-    autoinstall:
-        version: 1
-        identity:
-            hostname: hostname
-            username: username
-            password: $crypted_pass
-
-Here is an example file that shows off most of the autoinstall directives:
-
-.. parsed-literal::
-
-    #cloud-config
-    autoinstall:
-        :ref:`ai-version`: 1
-        :ref:`ai-reporting`:
-            hook:
-                type: webhook
-                endpoint: http\://example.com/endpoint/path
-        :ref:`ai-early-commands`:
-            - ping -c1 198.162.1.1
-        :ref:`ai-locale`: en_US
-        :ref:`ai-keyboard`:
-            layout: gb
-            variant: dvorak
-        :ref:`ai-network`:
-            network:
-                version: 2
-                ethernets:
-                    enp0s25:
-                       dhcp4: yes
-                    enp3s0: {}
-                    enp4s0: {}
-                bonds:
-                    bond0:
-                        dhcp4: yes
-                        interfaces:
-                            - enp3s0
-                            - enp4s0
-                        parameters:
-                            mode: active-backup
-                            primary: enp3s0
-        :ref:`ai-proxy`: http\://squid.internal:3128/
-        :ref:`ai-apt`:
-            primary:
-                - arches: [default]
-                  uri: http\://repo.internal/
-            sources:
-                my-ppa.list:
-                    source: "deb http\://ppa.launchpad.net/curtin-dev/test-archive/ubuntu $RELEASE main"
-                    keyid: B59D 5F15 97A5 04B7 E230  6DCA 0620 BBCF 0368 3F77
-        :ref:`ai-storage`:
-            layout:
-                name: lvm
-        :ref:`ai-identity`:
-            hostname: hostname
-            username: username
-            password: $crypted_pass
-        :ref:`ai-ssh`:
-            install-server: yes
-            authorized-keys:
-              - $key
-            allow-pw: no
-        :ref:`ai-snaps`:
-            - name: go
-              channel: 1.20/stable
-              classic: true
-        :ref:`ai-debconf-selections`: |
-            bind9      bind9/run-resolvconf    boolean false
-        :ref:`ai-packages`:
-            - libreoffice
-            - dns-server^
-        :ref:`ai-user-data`:
-            disable_root: false
-        :ref:`ai-late-commands`:
-            - sed -ie 's/GRUB_TIMEOUT=.\*/GRUB_TIMEOUT=30/' /target/etc/default/grub
-        :ref:`ai-error-commands`:
-            - tar c /var/log/installer | nc 192.168.0.1 1000
-
-
 Error handling
-==============
+--------------
 
 Progress through the installer is reported via the :ref:`ai-reporting` system,
 including errors. In addition, when a fatal error occurs, the

doc/reference/autoinstall-schema.rst

@@ -1,589 +1,41 @@
 .. _autoinstall_schema:
 
 Autoinstall schema
-******************
+==================
 
-The server installer validates the provided autoinstall config against a
-:ref:`JSON schema<autoinstall_JSON_schema>`.
+The server installer validates the provided autoinstall configuration against a :ref:`JSON schema<autoinstall_JSON_schema>`.
 
-How the config is validated
-===========================
+How the configuration is validated
+----------------------------------
 
-Although the schema is presented below as a single document, and if you want
-to pre-validate your config you should validate it against this document, the
-config is not actually validated against this document at run time. What
-happens instead is that some sections are loaded, validated, and applied
-first, before all other sections are validated. In detail:
+This reference manual presents the schema as a single document. Use it pre-validate your configuration.
+
+At run time, the configuration is not validated against this document. Instead, configuration sections are loaded and validated in this order:
 
 1. The reporting section is loaded, validated and applied.
 2. The error commands are loaded and validated.
 3. The early commands are loaded and validated.
 4. The early commands, if any, are run.
-5. The config is reloaded, and now all sections are loaded and validated.
+5. The configuration is reloaded, and all sections are loaded and validated.
 
-This is so that validation errors in most sections can be reported via the
-reporting and error-commands configuration, as all other errors are.
+This is to ensure that potential validation errors in most sections can be reported using the reporting and error-commands configuration the same way as other errors.
 
 .. _autoinstall_JSON_schema:
 
 Schema
-======
+------
 
-The `JSON schema`_ for autoinstall data is as follows:
+The `JSON schema`_ for autoinstall data:
 
-.. code-block:: JSON
-
-    "type": "object",
-    "properties": {
-        "version": {
-            "type": "integer",
-            "minimum": 1,
-            "maximum": 1
-        },
-        "early-commands": {
-            "type": "array",
-            "items": {
-                "type": [
-                    "string",
-                    "array"
-                ],
-                "items": {
-                    "type": "string"
-                }
-            }
-        },
-        "reporting": {
-            "type": "object",
-            "additionalProperties": {
-                "type": "object",
-                "properties": {
-                    "type": {
-                        "type": "string"
-                    }
-                },
-                "required": [
-                    "type"
-                ],
-                "additionalProperties": true
-            }
-        },
-        "error-commands": {
-            "type": "array",
-            "items": {
-                "type": [
-                    "string",
-                    "array"
-                ],
-                "items": {
-                    "type": "string"
-                }
-            }
-        },
-        "user-data": {
-            "type": "object"
-        },
-        "packages": {
-            "type": "array",
-            "items": {
-                "type": "string"
-            }
-        },
-        "debconf-selections": {
-            "type": "string"
-        },
-        "locale": {
-            "type": "string"
-        },
-        "refresh-installer": {
-            "type": "object",
-            "properties": {
-                "update": {
-                    "type": "boolean"
-                },
-                "channel": {
-                    "type": "string"
-                }
-            },
-            "additionalProperties": false
-        },
-        "kernel": {
-            "type": "object",
-            "properties": {
-                "package": {
-                    "type": "string"
-                },
-                "flavor": {
-                    "type": "string"
-                }
-            },
-            "oneOf": [
-                {
-                    "type": "object",
-                    "required": [
-                        "package"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "required": [
-                        "flavor"
-                    ]
-                }
-            ]
-        },
-        "keyboard": {
-            "type": "object",
-            "properties": {
-                "layout": {
-                    "type": "string"
-                },
-                "variant": {
-                    "type": "string"
-                },
-                "toggle": {
-                    "type": [
-                        "string",
-                        "null"
-                    ]
-                }
-            },
-            "required": [
-                "layout"
-            ],
-            "additionalProperties": false
-        },
-        "source": {
-            "type": "object",
-            "properties": {
-                "search_drivers": {
-                    "type": "boolean"
-                },
-                "id": {
-                    "type": "string"
-                }
-            }
-        },
-        "network": {
-            "oneOf": [
-                {
-                    "type": "object",
-                    "properties": {
-                        "version": {
-                            "type": "integer",
-                            "minimum": 2,
-                            "maximum": 2
-                        },
-                        "ethernets": {
-                            "type": "object",
-                            "properties": {
-                                "match": {
-                                    "type": "object",
-                                    "properties": {
-                                        "name": {
-                                            "type": "string"
-                                        },
-                                        "macaddress": {
-                                            "type": "string"
-                                        },
-                                        "driver": {
-                                            "type": "string"
-                                        }
-                                    },
-                                    "additionalProperties": false
-                                }
-                            }
-                        },
-                        "wifis": {
-                            "type": "object",
-                            "properties": {
-                                "match": {
-                                    "type": "object",
-                                    "properties": {
-                                        "name": {
-                                            "type": "string"
-                                        },
-                                        "macaddress": {
-                                            "type": "string"
-                                        },
-                                        "driver": {
-                                            "type": "string"
-                                        }
-                                    },
-                                    "additionalProperties": false
-                                }
-                            }
-                        },
-                        "bridges": {
-                            "type": "object"
-                        },
-                        "bonds": {
-                            "type": "object"
-                        },
-                        "tunnels": {
-                            "type": "object"
-                        },
-                        "vlans": {
-                            "type": "object"
-                        }
-                    },
-                    "required": [
-                        "version"
-                    ]
-                },
-                {
-                    "type": "object",
-                    "properties": {
-                        "network": {
-                            "type": "object",
-                            "properties": {
-                                "version": {
-                                    "type": "integer",
-                                    "minimum": 2,
-                                    "maximum": 2
-                                },
-                                "ethernets": {
-                                    "type": "object",
-                                    "properties": {
-                                        "match": {
-                                            "type": "object",
-                                            "properties": {
-                                                "name": {
-                                                    "type": "string"
-                                                },
-                                                "macaddress": {
-                                                    "type": "string"
-                                                },
-                                                "driver": {
-                                                    "type": "string"
-                                                }
-                                            },
-                                            "additionalProperties": false
-                                        }
-                                    }
-                                },
-                                "wifis": {
-                                    "type": "object",
-                                    "properties": {
-                                        "match": {
-                                            "type": "object",
-                                            "properties": {
-                                                "name": {
-                                                    "type": "string"
-                                                },
-                                                "macaddress": {
-                                                    "type": "string"
-                                                },
-                                                "driver": {
-                                                    "type": "string"
-                                                }
-                                            },
-                                            "additionalProperties": false
-                                        }
-                                    }
-                                },
-                                "bridges": {
-                                    "type": "object"
-                                },
-                                "bonds": {
-                                    "type": "object"
-                                },
-                                "tunnels": {
-                                    "type": "object"
-                                },
-                                "vlans": {
-                                    "type": "object"
-                                }
-                            },
-                            "required": [
-                                "version"
-                            ]
-                        }
-                    },
-                    "required": [
-                        "network"
-                    ]
-                }
-            ]
-        },
-        "ubuntu-pro": {
-            "type": "object",
-            "properties": {
-                "token": {
-                    "type": "string",
-                    "minLength": 24,
-                    "maxLength": 30,
-                    "pattern": "^C[1-9A-HJ-NP-Za-km-z]+$",
-                    "description": "A valid token starts with a C and is followed by 23 to 29 Base58 characters.\nSee https://pkg.go.dev/github.com/btcsuite/btcutil/base58#CheckEncode"
-                }
-            }
-        },
-        "ubuntu-advantage": {
-            "type": "object",
-            "properties": {
-                "token": {
-                    "type": "string",
-                    "minLength": 24,
-                    "maxLength": 30,
-                    "pattern": "^C[1-9A-HJ-NP-Za-km-z]+$",
-                    "description": "A valid token starts with a C and is followed by 23 to 29 Base58 characters.\nSee https://pkg.go.dev/github.com/btcsuite/btcutil/base58#CheckEncode"
-                }
-            },
-            "deprecated": true,
-            "description": "Compatibility only - use ubuntu-pro instead"
-        },
-        "proxy": {
-            "type": [
-                "string",
-                "null"
-            ],
-            "format": "uri"
-        },
-        "apt": {
-            "type": "object",
-            "properties": {
-                "preserve_sources_list": {
-                    "type": "boolean"
-                },
-                "primary": {
-                    "type": "array"
-                },
-                "mirror-selection": {
-                    "type": "object",
-                    "properties": {
-                        "primary": {
-                            "type": "array",
-                            "items": {
-                                "anyOf": [
-                                    {
-                                        "type": "string",
-                                        "const": "country-mirror"
-                                    },
-                                    {
-                                        "type": "object",
-                                        "properties": {
-                                            "uri": {
-                                                "type": "string"
-                                            },
-                                            "arches": {
-                                                "type": "array",
-                                                "items": {
-                                                    "type": "string"
-                                                }
-                                            }
-                                        },
-                                        "required": [
-                                            "uri"
-                                        ]
-                                    }
-                                ]
-                            }
-                        }
-                    }
-                },
-                "geoip": {
-                    "type": "boolean"
-                },
-                "sources": {
-                    "type": "object"
-                },
-                "disable_components": {
-                    "type": "array",
-                    "items": {
-                        "type": "string",
-                        "enum": [
-                            "universe",
-                            "multiverse",
-                            "restricted",
-                            "contrib",
-                            "non-free"
-                        ]
-                    }
-                },
-                "preferences": {
-                    "type": "array",
-                    "items": {
-                        "type": "object",
-                        "properties": {
-                            "package": {
-                                "type": "string"
-                            },
-                            "pin": {
-                                "type": "string"
-                            },
-                            "pin-priority": {
-                                "type": "integer"
-                            }
-                        },
-                        "required": [
-                            "package",
-                            "pin",
-                            "pin-priority"
-                        ]
-                    }
-                },
-                "fallback": {
-                    "type": "string",
-                    "enum": [
-                        "abort",
-                        "continue-anyway",
-                        "offline-install"
-                    ]
-                }
-            }
-        },
-        "storage": {
-            "type": "object"
-        },
-        "identity": {
-            "type": "object",
-            "properties": {
-                "realname": {
-                    "type": "string"
-                },
-                "username": {
-                    "type": "string"
-                },
-                "hostname": {
-                    "type": "string"
-                },
-                "password": {
-                    "type": "string"
-                }
-            },
-            "required": [
-                "username",
-                "hostname",
-                "password"
-            ],
-            "additionalProperties": false
-        },
-        "ssh": {
-            "type": "object",
-            "properties": {
-                "install-server": {
-                    "type": "boolean"
-                },
-                "authorized-keys": {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
-                },
-                "allow-pw": {
-                    "type": "boolean"
-                }
-            }
-        },
-        "snaps": {
-            "type": "array",
-            "items": {
-                "type": "object",
-                "properties": {
-                    "name": {
-                        "type": "string"
-                    },
-                    "channel": {
-                        "type": "string"
-                    },
-                    "classic": {
-                        "type": "boolean"
-                    }
-                },
-                "required": [
-                    "name"
-                ],
-                "additionalProperties": false
-            }
-        },
-        "active-directory": {
-            "type": "object",
-            "properties": {
-                "admin-name": {
-                    "type": "string"
-                },
-                "domain-name": {
-                    "type": "string"
-                }
-            },
-            "additionalProperties": false
-        },
-        "codecs": {
-            "type": "object",
-            "properties": {
-                "install": {
-                    "type": "boolean"
-                }
-            }
-        },
-        "drivers": {
-            "type": "object",
-            "properties": {
-                "install": {
-                    "type": "boolean"
-                }
-            }
-        },
-        "oem": {
-            "type": "object",
-            "properties": {
-                "install": {
-                    "oneOf": [
-                        {
-                            "type": "boolean"
-                        },
-                        {
-                            "type": "string",
-                            "const": "auto"
-                        }
-                    ]
-                }
-            },
-            "required": [
-                "install"
-            ]
-        },
-        "timezone": {
-            "type": "string"
-        },
-        "updates": {
-            "type": "string",
-            "enum": [
-                "security",
-                "all"
-            ]
-        },
-        "late-commands": {
-            "type": "array",
-            "items": {
-                "type": [
-                    "string",
-                    "array"
-                ],
-                "items": {
-                    "type": "string"
-                }
-            }
-        },
-        "shutdown": {
-            "type": "string",
-            "enum": [
-                "reboot",
-                "poweroff"
-            ]
-        }
-    },
-    "required": [
-        "version"
-    ],
-    "additionalProperties": true
-    }
+.. literalinclude:: ../../autoinstall-schema.json
+   :language: JSON
 
 Regeneration
-============
+------------
 
-The schema above can be regenerated by running ``make schema`` in a Subiquity
-source checkout.
+To regenerate the schema, run ``make schema`` in the root directory of the `Subiquity source repository`_.
 
 .. LINKS 
 
 .. _JSON schema: https://json-schema.org/
+.. _Subiquity source repository: https://github.com/canonical/subiquity

doc/reference/index.rst

@@ -1,17 +1,26 @@
 Reference
-*********
+=========
 
-Our reference section contains support information for Subiquity.
-This includes details on the network requirements, API definitions, support
-matrices and so on.
+The reference section contains reference information for Autoinstall and other tooling. This includes command syntax and options, details on network requirements, API definitions, support matrices, and other.
 
 -----
 
 Autoinstall reference manual
-============================
+----------------------------
 
 .. toctree::
    :maxdepth: 1
 
    Autoinstall configuration <autoinstall-reference.rst>
    Autoinstall JSON schema <autoinstall-schema.rst>
+
+
+ubuntu-image reference
+----------------------
+
+``ubuntu-image`` is a tool for generating bootable disk images with Ubuntu.
+
+.. toctree::
+   :maxdepth: 1
+
+   ubuntu-image reference <ubuntu-image.rst>

doc/reference/ubuntu-image.rst

@@ -0,0 +1,246 @@
+ubuntu-image syntax and options
+===============================
+
+``ubuntu-image`` is a program for generating bootable disk images. It supports building snap_-based and classical preinstalled Ubuntu images.
+
+
+Snap-based images
+-----------------
+
+Snap-based images are built from a *model assertion*, which is a YAML file describing a particular combination of core, kernel, and gadget snaps, along with other declarations, signed with a digital signature asserting its authenticity.  The assets defined in the model assertion uniquely describe the device for which the image is built.
+
+
+Classical images
+----------------
+
+Classical images are built from a local `gadget tree`_ path.  The `gadget tree`_ is a primed `gadget snap`_ containing a ``gadget.yaml`` file in the ``meta`` directory and all the necessary bootloader gadget bits built. For instance, a `gadget tree`_ can be prepared by fetching a specially tailored `gadget snap`_ source and running ``snapcraft prime`` on it, with the resulting tree being stored in the ``prime/`` directory.
+
+
+The ``gadget.yaml`` file
+------------------------
+
+As part of the model assertion, a `gadget snap`_ is specified.  The gadget contains a ``gadget.yaml`` file, which contains the exact description of the disk-image contents in the YAML format.  The ``gadget.yaml`` file describes, among other things:
+
+* Names of all the volumes to be produced (volumes are roughly analogous to disk images).
+
+* Structures (structures define the layout of the volume, including partitions, Master Boot Records, or any other relevant content.) within the volume. :none:`wokeignore:rule=master,`
+
+* Whether the volume contains a bootloader and if so, what kind of bootloader.
+
+Note that ``ubuntu-image`` communicates with the Snap Store using the ``snap prepare-image`` sub-command.  The model-assertion file is passed to ``snap prepare-image``, which handles downloading the appropriate gadget and any extra snaps.  See the :manualpage:`snap(8) manual page <man8/snap.8.html>` for additional details.
+
+
+Basic syntax
+------------
+
+.. code-block:: yaml
+
+    ubuntu-image snap [options] model.assertion
+
+    ubuntu-image classic [options] image_definition.yaml
+
+
+General options
+~~~~~~~~~~~~~~~
+
+-h, --help
+    Show the help message and exit.
+
+--version
+    Show the program version number and exit.
+
+
+Options of the ``snap`` command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These are the options for defining the contents of snap-based images.  They can only be used when the ``ubuntu-image snap`` command is used.
+
+``model_assertion``
+    Path to the model assertion file.  This positional argument must be given for this mode of operation.
+
+--cloud-init USER-DATA-FILE
+    ``cloud-config`` data to be copied to the image.
+
+--disable-console-conf
+    Disable ``console-conf`` on the resulting image.
+
+--factory-image
+    Hint that the image is meant to boot in a device factory.
+
+--validation=<ignore|enforce>
+    Control whether validations should be ignored or enforced.
+
+--snap SNAP
+    Install an extra snap.  This is passed through to ``snap prepare-image``. The snap argument can include additional information about the channel and/or risk with the following syntax: ``<snap>=<channel|risk>``. Note that this flag will cause an error if the model assertion has a grade higher than dangerous.
+
+--revision <SNAP_NAME:REVISION>
+    Install a specific revision of a snap rather than the latest available in a particular channel. The snap specified with ``SNAP_NAME`` must be included either in the model assertion or as an argument to ``--snap``. If both a revision and channel are provided, the revision specified is installed in the image, and updates come from the specified channel.
+
+--preseed
+    Preseed the image (Ubuntu Core 20 and higher only).
+
+--preseed-sign-key=<key>
+    Name of the key to use to sign the preseed assertion, otherwise use the default key.
+
+--sysfs-overlay=<path to directory that contains sysfs overlay>
+    Specify the directory that contains the sysfs overlay. This options also requires the ``--preseed`` and ``--preseed-sign-key`` options.
+
+Options of the ``classic`` command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These are the options for defining the contents of classical preinstalled Ubuntu images. They can only be used when the ``ubuntu-image classic`` command is used.
+
+``image_definition``
+    Path to the image-definition file. This file defines all of the customisation required when building the image. This positional argument must be given for this mode of operation.
+
+
+Common options
+~~~~~~~~~~~~~~
+
+There are two general operational modes to ``ubuntu-image``.  The usual mode is to run the script giving the required model-assertion file as a required positional argument, generating a disk image file.  These options are useful in this mode of operation.
+
+The second mode of operation is provided for debugging and testing purposes. It allows you to run the internal state machine step by step and is described in more detail below.
+
+-d, --debug
+    Enable debugging output.
+
+--verbose
+    Enable verbose output.
+
+--quiet
+    Only print error messages. Suppress all other output.
+
+-O DIRECTORY, --output-dir DIRECTORY
+    Write generated disk-image files to this directory.  The files will be named after the ``gadget.yaml`` volume names, with the ``.img`` suffix appended.  If not given, the value of the ``--workdir`` flag is used if specified.  If neither ``--output-dir`` nor ``--workdir`` is used, the image(s) will be placed in the current working directory.  This option replaces, and cannot be used with, the deprecated ``--output`` option.
+
+-i SIZE, --image-size SIZE
+    The size of the generated disk-image files.  If this size is smaller than the minimum calculated size of the volume, a warning is issued and ``--image-size`` is ignored.  The value is the size in bytes, with allowable suffixes ``M`` for MiB and ``G`` for GiB.
+
+    An extended syntax is supported for ``gadget.yaml`` files that specify multiple volumes (i.e. disk images).  In that case, a single ``SIZE`` argument is used for all the defined volumes, with the same rules for ignoring values that are too small.  You can specify the image size for a single volume using an indexing prefix on the ``SIZE`` parameter, where the index is either a volume name or an integer index starting at zero. For example, to set the image size only on the second volume, which might be called ``sdcard`` in ``gadget.yaml``, use: ``--image-size 1:8G`` (the number ``1`` index indicates the second volume; volumes are 0-indexed). Or use ``--image-size sdcard:8G``.
+
+    You can also specify multiple volume sizes by separating them with commas, and you can mix and match integer indices and volume-name indices.  Thus, if ``gadget.yaml`` names three volumes, and you want to set all three to different sizes, you can use ``--image-size 0:2G,sdcard:8G,eMMC:4G``.
+
+    In the case of ambiguities, the size hint is ignored, and the calculated size for the volume is used instead.
+
+--disk-info DISK-INFO-CONTENTS
+    File to be used as ``.disk/info`` on the root file system of the image.  This file can contain useful information about the target image, such as image identification data, system name, build timestamp, etc.
+
+-c CHANNEL, --channel CHANNEL
+    The default Snap channel to use while preseeding the image.
+
+--sector-size SIZE
+    When creating the disk-image file, use the given sector size.  This can be either 512 or 4096 (4k sector size), defaulting to 512.
+
+
+State-machine options
+~~~~~~~~~~~~~~~~~~~~~
+
+.. caution:: The options described here are primarily for debugging and testing purposes and should not be considered part of the stable, public API.  State-machine step numbers and names can change between releases.
+
+``ubuntu-image`` internally runs a state machine to create the disk image. These are some options for controlling this state machine.  Other than ``--workdir``, these options are mutually exclusive.  When ``--until`` or ``--thru`` is given, the state machine can be resumed later with ``--resume``, but ``--workdir`` must be given in that case since the state is saved in a ``ubuntu-image.json`` file in the working directory.
+
+-w DIRECTORY, --workdir DIRECTORY
+    The working directory in which to download and unpack all the source files for the image.  This directory can exist or not, and it is not removed after this program exits.  If not given, a temporary working directory is used instead, which *is* deleted after this program exits.  Use ``--workdir`` if you want to be able to resume a partial state-machine run.  The ``gadget.yaml`` file is copied to the working directory after it's downloaded.
+
+-u STEP, --until STEP
+    Run the state machine until the given ``STEP``, non-inclusively.  ``STEP`` is the name of a state-machine method. See the `List of steps`_.
+
+-t STEP, --thru STEP
+    Run the state machine until the given ``STEP``, inclusively.  ``STEP`` is the name of a state-machine method. See the `List of steps`_.
+
+-r, --resume
+    Continue the state machine from the previously saved state.  It returns an error if there is no previous state.
+
+
+Files used by ``ubuntu-image``
+------------------------------
+
+* |gadgetyaml|_
+* `model assertion`_
+* `gadget tree`_ (example)
+* `cloud-config`_
+
+
+Environment variables
+---------------------
+
+The following environment variables are recognised by ``ubuntu-image``.
+
+``UBUNTU_IMAGE_PRESERVE_UNPACK``
+    When set, the variable specifies the directory for preserving a pristine copy of the unpacked gadget contents.  The directory must exist, and an ``unpack`` directory will be created under this directory.  The full contents of the ``<workdir>/unpack`` directory after the ``snap prepare-image`` sub-command has run is copied here.
+
+There are a few other environment variables used for building and testing only.
+
+
+.. _list of steps:
+
+List of steps
+-------------
+
+The names of steps that can be used with ``--until`` and ``--thru`` for each image type are listed below.
+
+Classical-image steps
+~~~~~~~~~~~~~~~~~~~~~
+
+State machines are dynamically created for classical-image builds based on the contents of the image definition. The list of all possible states is as follows:
+
+#. ``make_temporary_directories``
+#. ``parse_image_definition``
+#. ``calculate_states``
+#. ``build_gadget_tree``
+#. ``prepare_gadget_tree``
+#. ``load_gadget_yaml``
+#. ``create_chroot``
+#. ``germinate``
+#. ``add_extra_ppas``
+#. ``install_packages``
+#. ``clean_extra_ppas``
+#. ``verify_artifact_names``
+#. ``customize_cloud_init``
+#. ``customize_fstab``
+#. ``manual_customization``
+#. ``preseed_image``
+#. ``clean_rootfs``
+#. ``populate_rootfs_contents``
+#. ``generate_disk_info``
+#. ``calculate_rootfs_size``
+#. ``populate_bootfs_contents``
+#. ``populate_prepare_partitions``
+#. ``make_disk``
+#. ``generate_package_manifest``
+
+To check the steps that are going to be used for a specific image-definition file, use the ``--print-states`` flag.
+
+Snap-image steps
+~~~~~~~~~~~~~~~~
+
+#. ``make_temporary_directories``
+#. ``prepare_image``
+#. ``load_gadget_yaml``
+#. ``populate_rootfs_contents``
+#. ``generate_disk_info``
+#. ``calculate_rootfs_size``
+#. ``populate_bootfs_contents``
+#. ``populate_prepare_partitions``
+#. ``make_disk``
+#. ``generate_snap_manifest``
+
+
+Additional resources
+--------------------
+
+* :manualpage:`snap(8) manual page <man8/snap.8.html>`
+
+
+.. |gadgetyaml| replace:: ``gadget.yaml``
+
+.. LINKS
+
+.. _snap: http://snapcraft.io/
+.. _gadget snap: https://snapcraft.io/docs/the-gadget-snap
+.. _gadget tree: https://github.com/snapcore/pc-gadget
+.. _image_definition.yaml: https://github.com/canonical/ubuntu-image/tree/main/internal/imagedefinition#readme
+.. _gadgetyaml: https://forum.snapcraft.io/t/gadget-snaps/696
+.. _model assertion: https://ubuntu.com/core/docs/reference/assertions/model
+.. _gadget tree: https://github.com/snapcore/pc-gadget
+.. _cloud-config: https://help.ubuntu.com/community/CloudInit

doc/reuse/links.txt

@@ -0,0 +1,2 @@
+.. _reStructuredText style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/
+.. _Example product documentation: https://canonical-example-product-documentation.readthedocs-hosted.com/

doc/reuse/substitutions.txt

@@ -0,0 +1,3 @@
+.. |ubuntu-latest-version| replace:: 23.10
+.. |ubuntu-latest-codename| replace:: Mantic Minotaur
+.. role:: command(literal)

doc/tutorial/basic-server-installation.rst

@@ -1,123 +0,0 @@
-Basic server installation
-*************************
-
-This chapter provides an overview of how to install Ubuntu Server Edition. You
-can also refer to this guide on
-:ref:`how to operate the installer <operate-server-installer>` for more
-information on using the installer, and to this
-:doc:`screen-by-screen reference guide <screen-by-screen>` for more
-information about each of the installer screens.
-
-Preparing to install
-====================
-
-This section explains various aspects to consider before starting the
-installation.
-
-System requirements
--------------------
-
-Ubuntu Server Edition provides a common, minimalist base for a variety of
-server applications, such as file/print services, web hosting, email hosting,
-etc. This version supports four 64-bit architectures:
-
-* amd64 (Intel/AMD 64-bit)
-* arm64 (64-bit ARM)
-* ppc64el (POWER8 and POWER9)
-* s390x (IBM Z and LinuxONE)
-
-The recommended system requirements are:
-
-* CPU: 1 gigahertz or better
-* RAM: 1 gigabyte or more
-* Disk: a minimum of 2.5 gigabytes
-
-Perform a system back up
-------------------------
-
-Before installing Ubuntu Server Edition you should make sure all data on the
-system is backed up.
-
-If this is not the first time an operating system has been installed on your
-computer, it is likely you will need to re-partition your disk to make room
-for Ubuntu.
-
-Any time you partition your disk, you should be prepared to lose everything on
-the disk should you make a mistake or something goes wrong during partitioning.
-The programs used in installation are quite reliable, most have seen years of
-use, but they also perform destructive actions.
-
-Download the server ISO
------------------------
-
-You can obtain the amd64 server download from https://releases.ubuntu.com/.
-Select the version you wish to install and select the "server install image"
-download. Note that the server download includes the installer.
-
-There are platform-specific how-to guides for installations on:
-
-* `s390x LPAR <https://discourse.ubuntu.com/t/interactive-live-server-installation-on-ibm-z-lpar-s390x/16601>`_
-* `z/VM <https://discourse.ubuntu.com/t/interactive-live-server-installation-on-ibm-z-vm-s390x/16604>`_
-* `ppc64el <https://discourse.ubuntu.com/t/using-a-virtual-cdrom-and-petitboot-to-start-a-live-server-installation-on-ibm-power-ppc64el/16694>`_
-
-Create a bootable USB
----------------------
-
-There are many ways to boot the installer but the simplest and most common way
-is to
-`create a bootable USB stick <https://ubuntu.com/tutorials/tutorial-create-a-usb-stick-on-ubuntu>`_
-to boot the system to be installed with
-(`tutorials for other operating systems <https://ubuntu.com/search?q=%22create+a+bootable+USB+stick%22>`_
-are also available). 
-
-Perform the installation
-========================
-
-Now that you have prepared your install medium, you are ready to install.
-
-Boot the installer
-------------------
-
-Plug the USB stick into the system to be installed and start it.
-
-Most computers will automatically boot from USB or DVD, though in some cases
-this is disabled to improve boot times. If you don't see the boot message and
-the "Welcome" screen which should appear after it, you will need to set your
-computer to boot from the install media.
-
-There should be an on-screen message when the computer starts, telling you what
-key to press for settings or a boot menu. Depending on the manufacturer, this
-could be :kbd:`Escape`, :kbd:`F2`, :kbd:`F10` or :kbd:`F12`. Restart your
-computer and hold down this key until the boot menu appears, then select the
-drive with the Ubuntu install media.
-
-If you are still having problems, check out the
-`Ubuntu Community documentation on booting from
-CD/DVD <https://help.ubuntu.com/community/BootFromCD>`_.
-
-After a few moments, the installer will start in its language selection screen.
-
-.. image:: figures/basic-installation-start-screen.png
-   :alt: Welcome screen of the Server installer showing the language selection options
-
-Using the installer
--------------------
-
-The installer is designed to be easy to use and have sensible defaults so for
-a first install you can mostly just accept the defaults for the most
-straightforward install:
-
-* Choose your language
-* Update the installer (if offered)
-* Select your keyboard layout
-* Do not configure networking (the installer attempts to configure wired
-  network interfaces via DHCP, but you can continue without networking if this
-  fails)
-* Do not configure a proxy or custom mirror unless you have to in your network
-* For storage, leave "use an entire disk" checked, and choose a disk to install
-  to, then select "Done" on the configuration screen and confirm the install
-* Enter a username, hostname and password
-* On the SSH and snap screens, select "Done"
-* You will now see log messages as the install is completed
-* Select restart when this is complete, and log in using the username and
-  password provided

doc/tutorial/creating-autoinstall-configuration.rst

@@ -0,0 +1,91 @@
+Creating autoinstall configuration
+===================================
+
+When any system is installed using the Ubuntu installer, an autoinstall file for repeating the installation is created at :code:`/var/log/installer/autoinstall-user-data`. :ref:`providing-autoinstall` describes the two ways of delivering this autoinstall configuration to Ubuntu installer.
+
+
+The structure of an autoinstall configuration
+---------------------------------------------
+
+Go to the :ref:`ai` for full details on the supported autoinstall directives.
+
+.. code-block:: yaml
+
+    #cloud-config
+    autoinstall:
+        version: 1
+        identity:
+            hostname: hostname
+            username: username
+            password: $crypted_pass
+
+Here is an example file that shows most of the autoinstall directives:
+
+.. parsed-literal::
+
+    #cloud-config
+    autoinstall:
+        :ref:`ai-version`: 1
+        :ref:`ai-reporting`:
+            hook:
+                type: webhook
+                endpoint: http\://example.com/endpoint/path
+        :ref:`ai-early-commands`:
+            - ping -c1 198.162.1.1
+        :ref:`ai-locale`: en_US
+        :ref:`ai-keyboard`:
+            layout: gb
+            variant: dvorak
+        :ref:`ai-network`:
+            network:
+                version: 2
+                ethernets:
+                    enp0s25:
+                       dhcp4: yes
+                    enp3s0: {}
+                    enp4s0: {}
+                bonds:
+                    bond0:
+                        dhcp4: yes
+                        interfaces:
+                            - enp3s0
+                            - enp4s0
+                        parameters:
+                            mode: active-backup
+                            primary: enp3s0
+        :ref:`ai-proxy`: http\://squid.internal:3128/
+        :ref:`ai-apt`:
+            primary:
+                - arches: [default]
+                  uri: http\://repo.internal/
+            sources:
+                my-ppa.list:
+                    source: "deb http\://ppa.launchpad.net/curtin-dev/test-archive/ubuntu $RELEASE main"
+                    keyid: B59D 5F15 97A5 04B7 E230  6DCA 0620 BBCF 0368 3F77
+        :ref:`ai-storage`:
+            layout:
+                name: lvm
+        :ref:`ai-identity`:
+            hostname: hostname
+            username: username
+            password: $crypted_pass
+        :ref:`ai-ssh`:
+            install-server: yes
+            authorized-keys:
+              - $key
+            allow-pw: no
+        :ref:`ai-snaps`:
+            - name: go
+              channel: 1.20/stable
+              classic: true
+        :ref:`ai-debconf-selections`: |
+            bind9      bind9/run-resolvconf    boolean false
+        :ref:`ai-packages`:
+            - libreoffice
+            - dns-server^
+        :ref:`ai-user-data`:
+            disable_root: false
+        :ref:`ai-late-commands`:
+            - sed -ie 's/GRUB_TIMEOUT=.\*/GRUB_TIMEOUT=30/' /target/etc/default/grub
+        :ref:`ai-error-commands`:
+            - tar c /var/log/installer | nc 192.168.0.1 1000

doc/tutorial/index.rst

@@ -1,25 +1,21 @@
 .. _tutorial_index:
 
 Tutorials
-*********
+=========
 
-This section contains step-by-step tutorials to help you get started with
-Subiquity. We hope our tutorials make as few assumptions as possible and
-are accessible to anyone with an interest in Subiquity. They should be a
-great place to start learning about Subiquity, how it works, and what it's
-capable of.
+This section contains step-by-step tutorials to help you get started with Subiquity. The tutorials make as few assumptions as possible in order to be accessible to anyone with an interest in Subiquity. This is the place to start learning about Subiquity: how it works, and what it's capable of.
 
 -----
 
 For Ubuntu Server
-=================
+-----------------
 
-This tutorial introduces the core concepts of autoinstall and is recommended as
-the first step.
+This tutorial introduces the core concepts of autoinstall and is recommended as the first step.
 
 .. toctree::
    :maxdepth: 1
 
-   basic-server-installation
+   creating-autoinstall-configuration
+   providing-autoinstall
+   operate-server-installer
    screen-by-screen
-

doc/tutorial/operate-server-installer.rst

@@ -0,0 +1,64 @@
+.. _operate-server-installer:
+
+Operating the server installer
+==============================
+
+This document explains how to use the installer in general terms. For a step-by-step guide through the screens of the installer, use the `screen-by-screen guide <https://discourse.ubuntu.com/t/screen-by-screen-installer-guide/16690>`_.
+
+Get the installer
+-----------------
+
+Installer images are created (approximately) daily and are available from the `Ubuntu release <https://cdimage.ubuntu.com/ubuntu-server/daily-live/current/>`_ page. These images are not tested as extensively as the images from release days, but they contain the latest packages and installer. Therefore, fewer updates are required during or after installation.
+
+Download the server installer for amd64 from the `Ubuntu Server <https://ubuntu.com/download/server>`_ page and other architectures from the `release directory <http://cdimage.ubuntu.com/releases/20.04/release/>`_.
+
+Installer UI navigation
+-----------------------
+
+Use the :kbd:`↑` and :kbd:`↓` arrows, as well as the :kbd:`Space` or :kbd:`Enter` keys to navigate the installer.
+
+:kbd:`Tab` and :kbd:`Shift` + :kbd:`Tab` move the focus down and up respectively. Use :kbd:`Home`, :kbd:`End`, :kbd:`PgUp` and :kbd:`PgDn` to navigate through long lists quickly.
+
+Running the installer over a serial port
+----------------------------------------
+
+By default, the installer runs on the first virtual terminal, ``tty1``. This is what is displayed on any connected monitor by default. On systems without a monitor or a remote virtual terminal, you can run the installer on the serial port. To do this, specify an `appropriate console <https://www.kernel.org/doc/html/latest/admin-guide/serial-console.html>`_ on the kernel command line. A common value is ``console=ttyS0``.
+
+When running on a serial port, the installer starts in a basic mode that uses only the ASCII character set and black and white colours. If you are connecting from a terminal emulator, such as gnome-terminal, that supports Unicode and rich colours, you can switch to "rich mode", which uses Unicode and colours, and supports
+many languages.
+
+.. _connect-via-ssh:
+
+Connecting to the installer over SSH
+------------------------------------
+
+An alternative to basic terminals is to connect via SSH. If the network is up by the time the installer starts, instructions are offered on the initial screen in basic mode. Otherwise, instructions are available from the help menu once networking is configured.
+
+In addition, connecting via SSH is capable of displaying all Unicode characters, which enables the use of more translations than can be displayed on a virtual terminal.
+
+Help menu
+---------
+
+The help menu is in the top right of the screen. It contains help -- both general and for the currently displayed screen -- and some general actions.
+
+Switching to a shell prompt
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To switch to a shell at any time, select :guilabel:`Enter shell` from the help menu, or press :kbd:`Control` + :kbd:`Z` or :kbd:`F2`.
+
+If you are accessing the installer via ``tty1``, you can also access a shell by switching to a different virtual terminal (:kbd:`Control` + :kbd:`Alt` + arrow, or :kbd:`Control` + :kbd:`Alt` + number keys, to move between virtual terminals).
+
+Global keys
+-----------
+
+The following global keys work at any time:
+
+====================================  =============================================
+Key                                   Action
+====================================  =============================================
+:kbd:`Esc`                            Go back
+:kbd:`F1`                             Open help menu
+:kbd:`Control` + :kbd:`Z`, :kbd:`F2`  Switch to shell
+:kbd:`Control` + :kbd:`L`, :kbd:`F3`  Redraw screen
+:kbd:`Control` + :kbd:`T`, :kbd:`F4`  Toggle rich mode (colour, Unicode) on and off
+====================================  =============================================

doc/tutorial/providing-autoinstall.rst

@@ -0,0 +1,79 @@
+.. _providing-autoinstall:
+
+Providing autoinstall configuration
+===================================
+
+There are two ways to provide the autoinstall configuration:
+
+* :external+cloud-init:ref:`#cloud-config user data <user_data_formats-cloud_config>` containing ``autoinstall:`` configuration directives for cloud-init
+* Directly on the installation media
+
+For detailed how-to guides that provide step-by-step instructions on how to use these two methods, go to:
+
+* :ref:`Autoinstall quick start <autoinstall_quick_start>`
+* :ref:`Autoinstall quick start for s390x <autoinstall_quick_start_s390x>`
+
+
+Autoinstall by way of `cloud-config`
+------------------------------------
+
+The suggested way of providing autoinstall configuration to the Ubuntu installer is via cloud-init. This allows the configuration to be applied to the installer without having to modify the installation media.
+
+The autoinstall configuration is provided via cloud-init configuration, which is almost endlessly flexible. In most scenarios the easiest way will be to provide user data via the :external+cloud-init:ref:`datasource_nocloud` data source.
+
+When providing autoinstall via cloud-init, the autoinstall configuration is provided as :external+cloud-init:ref:`user_data_formats-cloud_config`. This means it requires a :code:`#cloud-config` header. The autoinstall directives are placed under a top level :code:`autoinstall:` key:
+
+.. code-block:: yaml
+
+    #cloud-config
+    autoinstall:
+        version: 1
+        ....
+
+.. note::
+
+   :external+cloud-init:ref:`user_data_formats-cloud_config` files must contain the ``#cloud-config`` header to be recognised as a valid cloud configuration data file.
+
+
+Autoinstall on the installation media
+-------------------------------------
+
+Another option for supplying autoinstall to the Ubuntu installer is to place a file named :code:`autoinstall.yaml` on the installation media itself.
+
+The autoinstall configuration provided in this way is passed to the Ubuntu installer directly and does not require the top-level :code:`autoinstall:` key:
+
+.. code-block:: yaml
+
+    version: 1
+    ....
+
+Starting in 24.04 (Noble), to be consistent with the cloud-config based format, a top-level :code:`autoinstall:` keyword is allowed:
+
+.. code-block:: yaml
+
+    autoinstall:
+        version: 1
+        ....
+
+There are two locations that Subiquity checks for the :code:`autoinstall.yaml` file:
+
+* At the root of the installation medium. When writing the installation ISO to a USB flash drive, copy :code:`autoinstall.yaml` to the partition containing the contents of the ISO - i.e. to the directory containing the ``casper`` sub-directory.
+
+* On the root file system of the installation system - this option typically requires modifying the installation ISO and is not recommended.
+
+Alternatively, you can pass the location of the autoinstall file on the kernel command line via the :code:`subiquity.autoinstallpath` parameter, where the path is relative to the root directory of the installation system. For example:
+
+.. code-block::
+
+    subiquity.autoinstallpath=path/to/autoinstall.yaml`
+
+
+Order of precedence for autoinstall locations
+---------------------------------------------
+
+Because there are many ways to specify the autoinstall file, it may happen that multiple locations are specified at the same time. Subiquity searches for the autoinstall file in the following order and uses the first existing one:
+
+1. Kernel command line
+2. Root of the installation system
+3. `cloud-config`
+4. Root of the installation medium (ISO)

doc/tutorial/screen-by-screen.rst

@@ -1,46 +1,38 @@
-Screen-by-screen installer
-**************************
+.. _screen-by-screen:
 
-The installer is designed to be easy to use without documentation. However,
-this guide provides more information on each of the screens of the installer to
-help walk you through an installation.
+Screen-by-screen installer walk-through
+=======================================
+
+The installer is designed to be easy to use without documentation. This guide provides more information on each of the screens of the installer to guide you through an installation.
 
 Language selection
-==================
+------------------
 
 .. image:: figures/sbs-language.png
-   :alt:
+   :alt: Welcome!
 
-This screen selects the language for the installer and the default language
-for the installed system.
-
-More languages can be displayed if you
-`connect via SSH <https://discourse.ubuntu.com/t/draft-using-the-server-installer/16689#connect-via-ssh>`_.
+This screen lets you select the language for the installer and the default language for the installed system. In case only a basic terminal with limited language support is available for the installation, an alternative is to :ref:`connect via SSH <connect-via-ssh>`.
 
 Refresh
-=======
+-------
 
 .. image:: figures/sbs-refresh.png
-   :alt:
+   :alt: Installer update available
 
-This screen is shown if there is an update available for the installer. This
-allows you to get any improvements and bug fixes made since release.
+This screen is shown if there is an update available for the installer. Update the installer to get any improvements and bug fixes made since the release.
 
-If you choose to update, the new version will be downloaded and the installer
-will restart at the same point of the installation.
+If you choose to update, the new version is downloaded, and the installer will restart at the same point of the installation.
 
 Keyboard
-========
+--------
 
 .. image:: figures/sbs-keyboard.png
-   :alt:
+   :alt: Keyboard configuration
 
-Choose the layout and variant of keyboard attached to the system, if any. When
-running in a virtual terminal, it is possible to guess the layout and variant
-by answering questions about the keyboard.
+Choose the layout and variant of keyboard attached to the system, if any. When running in a virtual terminal, it is possible to guess the layout and variant by answering questions about the keyboard. Select :guilabel:`Identify keyboard` to use this feature.
 
 Zdev (s390x only)
-=================
+-----------------
 
 .. code-block::
 
@@ -48,7 +40,7 @@ Zdev (s390x only)
       Zdev setup                                                      
     ====================================================================
       ID                          ONLINE  NAMES                                  ^
-                                                                                             │
+                                                                                 │
       generic-ccw                                                                │
       0.0.0009                                    >                              │
       0.0.000c                                    >                              │
@@ -59,116 +51,94 @@ Zdev (s390x only)
       0.0.0190                                    >                              │
       0.0.0191                                    >                              │
       0.0.019d                                    >                              │
-      0.0.019e                                    >┌────────────┐                 
-      0.0.0200                                    >│< (close)   │                 
-      0.0.0300                                    >│  Enable    │                 
-      0.0.0400                                    >│  Disable   │                 
+      0.0.019e                                    >┌────────────┐
+      0.0.0200                                    >│< (close)   │
+      0.0.0300                                    >│  Enable    │
+      0.0.0400                                    >│  Disable   │
       0.0.0592                                    >└────────────┘                v
-                                                                                  
-                                     [ Continue   ]                               
-                                     [ Back       ]                               
-                                                                         
 
-This screen is only shown on s390x and allows z-specific configuration of
-devices.
+                                     [ Continue   ]
+                                     [ Back       ]
 
-The list of devices can be long. :kbd:`Home` / :kbd:`End` / :kbd:`PageUp` 
-/ :kbd:`PageDown` can be used to navigate through the list more quickly.
+This screen is only shown on the s390x architecture and allows z-specific configuration of devices.
+
+The list of devices can be long. Use the :kbd:`Home`, :kbd:`End`, :kbd:`PgUp` and :kbd:`PgDn` keys navigate through the list quickly.
 
 Network
-=======
+-------
 
 .. image:: figures/sbs-network.png
-   :alt:
+   :alt: Network connections
 
-This screen allows the configuration of the network. Ubuntu Server uses NetPlan
-to configure networking and the UI of the installer can configure a subset of
-NetPlan's capabilities. In particular it can configure DHCP or static
-addressing, VLANs and bonds.
+This screen allows the configuration of the network. Ubuntu Server uses Netplan to configure networking and the installer can configure a subset of Netplan capabilities. In particular, it can configure DHCP or static
+addressing, VLAN and bonds.
 
-If networking is present (defined as "at least one interface has a default
-route") then the installer will install updates from the archive at the end of
-installation.
+If networking is present (defined as "at least one interface has a default route"), then the installer installs updates from the repository at the end of installation.
 
 Proxy
-=====
+-----
 
 .. image:: figures/sbs-proxy.png
-   :alt:
+   :alt: Configure proxy
 
-The proxy configured on this screen is used for accessing the package
-repository and the snap store both in the installer environment and in the
-installed system.
+Use this screen to configure proxy for accessing the package repository and the snap store both in the installer environment and in the installed system.
 
 Mirror
-======
+------
 
 .. image:: figures/sbs-mirror.png
-   :alt:
+   :alt: Configure Ubuntu archive mirror
 
-The installer will attempt to use ``geoip`` to look up an appropriate default
-package mirror for your location. If you want or need to use a different
-mirror, enter its URL here.
+The installer attempts to use geolocation to find an appropriate default package mirror for your location. To use a different mirror, enter its URL here.
 
 Storage
-=======
+-------
 
 .. image:: figures/sbs-storage.png
-   :alt:
+   :alt: Storage configuration
 
-Storage configuration is a complicated topic and :ref:`has its own page for documentation <configure-storage>`.
+Storage configuration is a complex topic and :ref:`has its own page for documentation <configure-storage>`.
 
 .. image:: figures/sbs-confirm-storage.png
-   :alt:
+   :alt: Storage configuration
 
-Once the storage configuration is confirmed, the install begins in the
-background.
+Once the storage configuration is confirmed, the installation begins in the background.
 
 Identity
-========
+--------
 
 .. image:: figures/sbs-identity.png
-   :alt:
+   :alt: Profile setup
 
-The default user will be an administrator, able to use ``sudo`` (this is why a
-password is needed, even if SSH public key access is enabled on the next
-screen).
+The default user will be an administrator who can use ``sudo`` (this is why a password is needed, even if SSH public-key access is enabled on the next screen).
 
 SSH
-===
+---
 
 .. image:: figures/sbs-ssh.png
-   :alt:
+   :alt: SSH Setup
 
-A default Ubuntu install has no open ports. It is very common to administer
-servers via SSH so the installer allows it to be installed with the click of a
-button.
+A default Ubuntu installation has no open ports. As it is very common to administer servers via SSH, the installer allows it to be installed.
 
 You can import keys for the default user from GitHub or Launchpad.
 
-If you import a key, then password authentication is disabled by default but it
-can be re-enabled again at a later time if you wish.
+If you import a key, then password authentication is disabled by default. It can be re-enabled later.
 
 Snaps
-=====
+-----
 
 .. image:: figures/sbs-snaps.png
-   :alt:
+   :alt: Featured Server Snaps
 
-If a network connection is enabled, a selection of snaps that are useful in a
-server environment are presented and can be selected for installation.
+If a network connection is enabled, a selection of snaps that are useful in a server environment is presented and can be selected for installation.
 
 Installation logs
-=================
+-----------------
 
 .. image:: figures/sbs-logs.png
-   :alt:
+   :alt: Installing system
 
-The final screen of the installer shows the progress of the installer and
-allows viewing of the full log file. Once the install has completed and
-security updates installed, the installer waits for confirmation before
-restarting.
+The final screen of the installer shows the progress of the installer and allows viewing of the full log file. Once the installation has completed and security updates have been installed, the installer waits for a confirmation before restarting.
 
 .. image:: figures/sbs-complete.png
-   :alt:
-
+   :alt: Installation complete