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
Autoinstalls
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
in a virtual machine (VM) on a local machine on the s390x architecture.
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 how-to is a version of :ref:`autoinstall_quickstart`.
adapted for 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>` for instructions on installing on the amd64 architecture.
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|)).
.. parsed-literal::
wget https:\ //cdimage.ubuntu.com/ubuntu/releases/|ubuntu-latest-version|/release/ubuntu-|ubuntu-latest-version|-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
=============
-------------
.. parsed-literal::
Make the content of the ISO image accessible from a local directory:
.. code:: none
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
====================================
------------------------------------
Create a cloud-init configuration:
@ -49,9 +47,9 @@ Create a cloud-init configuration:
The encrypted password is ``ubuntu``.
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
@ -59,15 +57,19 @@ Leave this running in a new terminal window:
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:: 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
@ -84,7 +86,9 @@ Proceed with a second terminal window:
corrupt: false
Run the installation
====================
--------------------
Install the ``kvm`` command:
.. 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
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'
The above commands boot the virtual machine, download the configuration from the server
(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.
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:: none
kvm -no-reboot -name auto-inst-test -nographic -m 2048 \
-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
name and password.
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/

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

@ -1,48 +1,39 @@
.. _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-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 installation where a machine boots over a network 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
Change ``<version-number>`` to match the number of the release you have downloaded.
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
cd ~/www
@ -60,69 +51,64 @@ This means creating cloud-init configuration as follows:
The encrypted password is ``ubuntu``.
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 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 configuration from the server (set up in the previous
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.
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 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
@ -140,52 +126,54 @@ Create your user-data and meta-data files
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 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 boots the system and runs the installation. Unless you interrupt boot to add
``autoinstall`` to the kernel command line, the installer prompts 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

20
doc/howto/index.rst
View File

@ -1,29 +1,25 @@
.. _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 quick start <autoinstall-quickstart>
Autoinstall quick start for s390x <autoinstall-quickstart-s390x>
Found a problem?
================
----------------
.. toctree::
:maxdepth: 1

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

@ -1,56 +1,34 @@
.. _report-bugs:
How to report a problem
***********************
Troubleshooting
===============
We always hope, of course, that every installation 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 installation 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.
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::
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:
:maxdepth: 2
Introduction to Autoinstall<intro-to-autoinstall>
Introduction to autoinstall<intro-to-autoinstall>
tutorial/index
howto/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:
* amd64 (Intel/AMD 64-bit)
* arm64 (64-bit ARM)
* amd64 (AMD64, Intel 64)
* arm64 (AArch64)
* ppc64el (POWER8 and POWER9)
* s390x (IBM Z and LinuxONE)