StealthOS/subiquity
StealthOS
/
subiquity
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #1862 from rkratky/FR-5768_review-howtos 

Review howtos
This commit is contained in:
Dan Bungert 2023-10-27 10:16:14 -06:00 committed by GitHub
parent 2fd829b568 e0593a2dfc
commit 454c487242
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 127 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/.custom_wordlist.txt
View File

@ -1,3 +1,4 @@
AArch
Autoinstall Autoinstall
Autoinstalls Autoinstalls
Btrfs Btrfs

71
doc/howto/autoinstall-quickstart-s390x.rst
View File

@ -1,33 +1,31 @@
.. _autoinstall-quickstart-s390x: .. _autoinstall-quick-start-s390x:
Automatic installation quick start for s390x Autoinstall quick start for s390x
******************************************** =================================
This how-to provides basic instructions to perform an automatic installation 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.
in a virtual machine (VM) on a local machine on the s390x architecture.
This how-to is a version of :ref:`autoinstall_quickstart`. 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 instructions on installing on the amd64 architecture.
adapted for s390x.
Download an ISO Download the ISO
=============== ----------------
Download an ISO image of the latest release from the `release page <https://cdimage.ubuntu.com/ubuntu/releases/>`_ (currently |ubuntu-latest-version| (|ubuntu-latest-codename|)). Download the latest release of the Ubuntu Server image (ISO) from the `Ubuntu ISO download page`_ (currently |ubuntu-latest-version| (|ubuntu-latest-codename|)).
.. parsed-literal::
wget https:\ //cdimage.ubuntu.com/ubuntu/releases/|ubuntu-latest-version|/release/ubuntu-|ubuntu-latest-version|-live-server-s390x.iso -P ~/Downloads
Mount the ISO Mount the ISO
============= -------------
.. parsed-literal:: Make the content of the ISO image accessible from a local directory:
.. code:: none
mkdir -p ~/iso mkdir -p ~/iso
sudo mount -r ~/Downloads/ubuntu-|ubuntu-latest-version|-live-server-s390x.iso ~/iso sudo mount -r ~/Downloads/ubuntu-<version-number>-live-server-s390x.iso ~/iso
Change ``<version-number>`` to match the number of the release you have downloaded.
Write your autoinstall configuration Write your autoinstall configuration
==================================== ------------------------------------
Create a cloud-init configuration: Create a cloud-init configuration:
@ -49,9 +47,9 @@ Create a cloud-init configuration:
The encrypted password is ``ubuntu``. The encrypted password is ``ubuntu``.
Serve the cloud-init configuration over HTTP Serve the cloud-init configuration over HTTP
============================================ --------------------------------------------
Leave this running in a new terminal window: Leave the HTTP server running in a terminal:
.. code-block:: none .. code-block:: none
@ -59,15 +57,19 @@ Leave this running in a new terminal window:
python3 -m http.server 3003 python3 -m http.server 3003
Create a target disk Create a target disk
==================== --------------------
Proceed with a second terminal window: In a new terminal, install the ``qemu-img`` utility:
.. code-block:: none .. code-block:: none
sudo apt install qemu-utils 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 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 Formatting 'disk-image.qcow2', fmt=qcow2 size=10737418240 cluster_size=65536 lazy_refcounts=off refcount_bits=16
@ -84,7 +86,9 @@ Proceed with a second terminal window:
corrupt: false corrupt: false
Run the installation Run the installation
==================== --------------------
Install the ``kvm`` command:
.. code-block:: none .. code-block:: none
@ -97,26 +101,29 @@ Add the default user to the ``kvm`` group:
sudo usermod -a -G kvm ubuntu # re-login to make the changes take effect 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 \ kvm -no-reboot -name auto-inst-test -nographic -m 2048 \
-drive file=disk-image.qcow2,format=qcow2,cache=none,if=virtio \ -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 \ -kernel ~/iso/boot/kernel.ubuntu \
-initrd ~/iso/boot/initrd.ubuntu \ -initrd ~/iso/boot/initrd.ubuntu \
-append 'autoinstall ds=nocloud-net;s=http://_gateway:3003/ console=ttysclp0' -append 'autoinstall ds=nocloud-net;s=http://_gateway:3003/ console=ttysclp0'
The above commands boot the virtual machine, download the configuration from the server 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.
(prepared in the previous step) and run the installation.
The installer reboots at the end. The ``-no-reboot`` flag to ``kvm`` instructs ``kvm``
to terminate on reboot. The procedure takes approximately 5 minutes.
Boot the installed system Boot the installed system
========================= -------------------------
.. code-block:: none .. code-block:: none
kvm -no-reboot -name auto-inst-test -nographic -m 2048 \ kvm -no-reboot -name auto-inst-test -nographic -m 2048 \
-drive file=disk-image.qcow2,format=qcow2,cache=none,if=virtio -drive file=disk-image.qcow2,format=qcow2,cache=none,if=virtio
This command boots into the installed system. Log in using ``ubuntu`` for both the user This command boots the installed system in the VM. Log in using ``ubuntu`` for both the user name and password.
name and password.
.. LINKS
.. _Ubuntu ISO download page: https://releases.ubuntu.com/

136
doc/howto/autoinstall-quickstart.rst
View File

@ -1,48 +1,39 @@
.. _autoinstall_quickstart: .. _autoinstall_quick-start:
Autoinstall quick start Autoinstall quick start
*********************** =======================
The intent of this page is to provide simple instructions to perform an 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.
autoinstall in a VM on your machine.
This page assumes that you are installing a recent Ubuntu release. However, 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-s390x>` for instructions on installing on the s390x architecture.
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.
Providing the autoinstall data over the network Providing the autoinstall data over the network
=============================================== -----------------------------------------------
This method is the one that generalises most easily to doing an entirely This method describes a network-based installation. When booting over a network, use this method to deliver autoinstall to perform the installation.
network-based installation where a machine boots over a network and then is automatically
installed.
Download the ISO Download the ISO
---------------- ~~~~~~~~~~~~~~~~
Go to the `Ubuntu ISO download page`_ and download the latest Ubuntu Download the latest release of the Ubuntu Server image (ISO) from the `Ubuntu ISO download page`_ (currently |ubuntu-latest-version| (|ubuntu-latest-codename|)).
live-server ISO.
Mount the ISO 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 sudo mount -r ~/Downloads/ubuntu-<version-number>-live-server-amd64.iso /mnt
release you have downloaded (e.g., `22.04.3` for Jammy or `23.04` for the Lunar
interim release). Change ``<version-number>`` to match the number of the release you have downloaded.
Write your autoinstall configuration Write your autoinstall configuration
------------------------------------ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This means creating cloud-init configuration as follows: Create a cloud-init configuration:
.. code-block:: bash .. code:: none
mkdir -p ~/www mkdir -p ~/www
cd ~/www cd ~/www
@ -60,69 +51,64 @@ This means creating cloud-init configuration as follows:
The encrypted password is ``ubuntu``. The encrypted password is ``ubuntu``.
Serve the cloud-init configuration 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 cd ~/www
python3 -m http.server 3003 python3 -m http.server 3003
Create a target disk Create a target disk
-------------------- ~~~~~~~~~~~~~~~~~~~~
.. code-block:: Create the target VM disk for the installation:
.. code:: none
truncate -s 10G image.img truncate -s 10G image.img
Run the installation Run the installation
-------------------- ~~~~~~~~~~~~~~~~~~~~
As before, you will need to change `<release-number>` in the following command Change ``<version-number>`` in the following command to match the release ISO you downloaded.
to match the release ISO you downloaded.
.. code-block:: bash .. code:: none
kvm -no-reboot -m 2048 \ kvm -no-reboot -m 2048 \
-drive file=image.img,format=raw,cache=none,if=virtio \ -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 \ -kernel /mnt/casper/vmlinuz \
-initrd /mnt/casper/initrd \ -initrd /mnt/casper/initrd \
-append 'autoinstall ds=nocloud-net;s=http://_gateway:3003/' -append 'autoinstall ds=nocloud-net;s=http://_gateway:3003/'
This will boot, download the configuration from the server (set up in the previous 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.
step) and run the installation. 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.
Boot the installed system Boot the installed system
------------------------- ~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: bash .. code:: none
kvm -no-reboot -m 2048 \ kvm -no-reboot -m 2048 \
-drive file=image.img,format=raw,cache=none,if=virtio -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 This command boots the installed system in the VM. Log in using ``ubuntu`` for both the user name and password.
in as ``ubuntu/ubuntu``.
Using another volume to provide the autoinstall configuration 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 Use this method to create an installation medium to plug into a computer to have it be installed.
into a system 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 Download the latest Ubuntu Server ISO from the `Ubuntu ISO download page`_.
live-server ISO.
Create your user-data and meta-data files Create user-data and meta-data files
----------------------------------------- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: bash .. code:: none
mkdir -p ~/cidata mkdir -p ~/cidata
cd ~/cidata cd ~/cidata
@ -140,52 +126,54 @@ Create your user-data and meta-data files
The encrypted password is ``ubuntu``. The encrypted password is ``ubuntu``.
Create an ISO to use as a cloud-init data source 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 sudo apt install cloud-image-utils
Create the ISO image for cloud-init:
.. code:: none
cloud-localds ~/seed.iso user-data meta-data cloud-localds ~/seed.iso user-data meta-data
Create a target disk Create a target disk
-------------------- ~~~~~~~~~~~~~~~~~~~~
.. code-block:: bash Create the target VM disk for the installation:
.. code:: none
truncate -s 10G image.img truncate -s 10G image.img
Run the installation Run the installation
-------------------- ~~~~~~~~~~~~~~~~~~~~
As before, you will need to change `<release-number>` in the following command Change ``<version-number>`` in the following command to match the release ISO you downloaded.
to match the release ISO you downloaded.
.. code-block:: bash .. code:: none
kvm -no-reboot -m 2048 \ kvm -no-reboot -m 2048 \
-drive file=image.img,format=raw,cache=none,if=virtio \ -drive file=image.img,format=raw,cache=none,if=virtio \
-drive file=~/seed.iso,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 boots the system and runs the installation. Unless you interrupt boot to add 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.
``autoinstall`` to the kernel command line, the installer prompts for
confirmation before touching the disk.
The installer reboots at the end but the ``-no-reboot`` flag to ``kvm`` means The installer reboots at the end. The ``-no-reboot`` option to the ``kvm`` command instructs ``kvm`` to exit on reboot.
that ``kvm`` will exit when this happens.
The whole process should take about 5 minutes.
Boot the installed system Boot the installed system
------------------------- ~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: bash .. code:: none
kvm -no-reboot -m 2048 \ kvm -no-reboot -m 2048 \
-drive file=image.img,format=raw,cache=none,if=virtio -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 This command boots the installed system in the VM. Log in using ``ubuntu`` for both the user name and password.
in as ``ubuntu/ubuntu``.
.. LINKS .. LINKS

20
doc/howto/index.rst
View File

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

50
doc/howto/report-bugs.rst
View File

@ -1,56 +1,34 @@
.. _report-bugs: .. _report-bugs:
How to report a problem Troubleshooting
*********************** ===============
We always hope, of course, that every installation with the server installer This section explains how to deal with installation problems and how to report issues to the Subiquity team.
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.
Update Subiquity Update Subiquity
================ ----------------
The first thing to do is to update your Subiquity snap using `snap refresh`. Ensure you're using the latest stable version of the installer. Update the Subiquity snap by running ``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.
Crash reports Crash reports
============= -------------
A failure will result in a crash report being generated which bundles up all 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).
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 installation media by default (if there is space).
When an error occurs you are presented with a dialog that allows you to upload 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
the report to the error tracker and offers options for continuing. Uploads to tracking which kinds of errors affect most users.
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.
Create Launchpad bug report Create a Launchpad bug report
=========================== -----------------------------
You can create a Launchpad bug report, which lets us establish this kind 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:
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:
.. code-block:: bash .. code-block:: bash
apport-cli /path/to/report.crash apport-cli /path/to/report.crash
and follow the prompts. 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.
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:: .. note::
Bugs for the Subiquity autoinstaller are `tracked in Launchpad <https://bugs.launchpad.net/subiquity>`_. Issues for the Subiquity autoinstaller are `tracked in Launchpad <https://bugs.launchpad.net/subiquity>`_.

2
doc/index.rst
View File

@ -66,7 +66,7 @@ Contribute:
:hidden: :hidden:
:maxdepth: 2 :maxdepth: 2
Introduction to Autoinstall<intro-to-autoinstall> Introduction to autoinstall<intro-to-autoinstall>
tutorial/index tutorial/index
howto/index howto/index
reference/index reference/index

4
doc/tutorial/basic-server-installation.rst
View File

@ -13,8 +13,8 @@ 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: 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 (Intel/AMD 64-bit) * amd64 (AMD64, Intel 64)
* arm64 (64-bit ARM) * arm64 (AArch64)
* ppc64el (POWER8 and POWER9) * ppc64el (POWER8 and POWER9)
* s390x (IBM Z and LinuxONE) * s390x (IBM Z and LinuxONE)