diff --git a/doc/howto/autoinstall-quickstart-s390x.rst b/doc/howto/autoinstall-quickstart-s390x.rst index 10a10104..643d10b3 100644 --- a/doc/howto/autoinstall-quickstart-s390x.rst +++ b/doc/howto/autoinstall-quickstart-s390x.rst @@ -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:`` 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 `_ (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--live-server-s390x.iso ~/iso + +Change ```` 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 ```` 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--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/ diff --git a/doc/howto/autoinstall-quickstart.rst b/doc/howto/autoinstall-quickstart.rst index b1a48aa5..633a35fc 100644 --- a/doc/howto/autoinstall-quickstart.rst +++ b/doc/howto/autoinstall-quickstart.rst @@ -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` too. +For older Ubuntu releases, substitute the version in the name of the ISO image. The instructions should otherwise be the same. See :ref:`` 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--live-server-amd64.iso /mnt +.. code:: none -Where you should change `` 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--live-server-amd64.iso /mnt + +Change ```` 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 `` in the following command -to match the release ISO you downloaded. +Change ```` 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--live-server-amd64.iso \ + -cdrom ~/Downloads/ubuntu--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 `` in the following command -to match the release ISO you downloaded. +Change ```` 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--live-server-amd64.iso + -cdrom ~/Downloads/ubuntu--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 diff --git a/doc/howto/index.rst b/doc/howto/index.rst index f754bfe4..b987d577 100644 --- a/doc/howto/index.rst +++ b/doc/howto/index.rst @@ -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 quick-start guide for s390x - + Autoinstall quick start + Autoinstall quick start for s390x Found a problem? -================ +---------------- .. toctree:: :maxdepth: 1 diff --git a/doc/howto/report-bugs.rst b/doc/howto/report-bugs.rst index f49d5380..23402aff 100644 --- a/doc/howto/report-bugs.rst +++ b/doc/howto/report-bugs.rst @@ -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 `_. - - - +Issues for the Subiquity autoinstaller are `tracked in Launchpad `_. diff --git a/doc/index.rst b/doc/index.rst index b702517b..026faf7b 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -66,7 +66,7 @@ Contribute: :hidden: :maxdepth: 2 - Introduction to Autoinstall + Introduction to autoinstall tutorial/index howto/index reference/index