diff --git a/documentation/autoinstall-quickstart-s390x.md b/documentation/autoinstall-quickstart-s390x.md index 3afc920f..ab44881f 100644 --- a/documentation/autoinstall-quickstart-s390x.md +++ b/documentation/autoinstall-quickstart-s390x.md @@ -1,4 +1,3 @@ -# 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. @@ -9,18 +8,23 @@ This page is just a slightly adapted page of [the autoinstall quickstart page](a At the time of writing (just after the kinetic release), the best place to go is here: -
wget https://cdimage.ubuntu.com/ubuntu/releases/22.10/release/ubuntu-22.10-live-server-s390x.iso -P ~/Downloads
+```bash +wget https://cdimage.ubuntu.com/ubuntu/releases/22.10/release/ubuntu-22.10-live-server-s390x.iso -P ~/Downloads +``` ## Mount the ISO -
mkdir -p ~/iso
-sudo mount -r ~/Downloads/ubuntu-22.10-live-server-s390x.iso ~/iso
+```bash +mkdir -p ~/iso +sudo mount -r ~/Downloads/ubuntu-22.10-live-server-s390x.iso ~/iso +``` ## Write your autoinstall config -This means creating cloud-init config as follows: +This means creating a cloud-init #cloud-config file as follows: -
mkdir -p ~/www
+```bash
+mkdir -p ~/www
 cd ~/www
 cat > user-data << 'EOF'
 #cloud-config
@@ -31,25 +35,30 @@ autoinstall:
     password: "$6$exDY1mhS4KUYCE/2$zmn9ToZwTKLhCw.b4/b.ZRTIZM30JZ4QrOQ2aOXJ8yk96xpcCof0kxKwuX1kqLG/ygbJ1f8wxED22bTL4F46P0"
     username: ubuntu
 EOF
-touch meta-data
+touch meta-data +``` The crypted password is just "ubuntu". -## Serve the cloud-init config over http +## Serve the cloud-init config over HTTP -Leave this running in one terminal window: +Leave this running in a new terminal window: -
cd ~/www
-python3 -m http.server 3003
+```bash +cd ~/www +python3 -m http.server 3003 +``` ## Create a target disk Proceed with a second terminal window: -
sudo apt install qemu-utils
-...
+```bash +sudo apt install qemu-utils +``` -
qemu-img create -f qcow2 disk-image.qcow2 10G
+```bash
+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
 
 qemu-img info disk-image.qcow2
@@ -62,30 +71,40 @@ Format specific information:
     compat: 1.1
     lazy refcounts: false
     refcount bits: 16
-    corrupt: false
+ corrupt: false +``` ## Run the install! -
sudo apt install qemu-kvm
-...
+```bash +sudo apt install qemu-kvm +``` -You may need to add the default user to the kvm group: <
> -`sudo usermod -a -G kvm ubuntu # re-login to make the changes take effect` +You may need to add the default user to the `kvm` group: -
kvm -no-reboot -name auto-inst-test -nographic -m 2048 \
+```bash
+sudo usermod -a -G kvm ubuntu
+```
+
+> **Note**:
+> You will need to re-login to make the changes take effect.
+
+```bash
+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 \
     -kernel ~/iso/boot/kernel.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' +``` -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 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. ## Boot the installed system -
kvm -no-reboot -name auto-inst-test -nographic -m 2048 \
-    -drive file=disk-image.qcow2,format=qcow2,cache=none,if=virtio
+```bash +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 will boot into the freshly installed system and you should be able to log in as `ubuntu`/`ubuntu`. diff --git a/documentation/autoinstall-quickstart.md b/documentation/autoinstall-quickstart.md index ec0aa619..75fe89a3 100644 --- a/documentation/autoinstall-quickstart.md +++ b/documentation/autoinstall-quickstart.md @@ -1,28 +1,29 @@ -# Autoinstall Quick Start - The intent of this page is to provide simple instructions to perform an autoinstall in a VM on your machine. -This page assumes that you are willing to install the latest Ubuntu release available i.e., 22.10 at the time of writing. For other releases, you would need to substitute the name of the ISO image but the instructions should otherwise remain the same. +This page assumes that you are willing to install the latest Ubuntu release available (23.10 at the time of writing). For other releases, you would need to substitute the name of the ISO image but the instructions should otherwise remain the same. -This page also assumes you are on the amd64 architecture. There is a version for [s390x](autoinstall-quickstart-s390x.md) too. +This page also assumes you are on the amd64 architecture. There is a [version for s390x](/t/automated-server-install-schema/16616) too. ## Providing the autoinstall data over the network -This method is the one that generalizes most easily to doing an entirely network-based install, where a machine netboots and then is automatically installed. +This method is the one that generalises most easily to doing an entirely network-based install, where a machine netboots and is then automatically installed. ### Download the ISO -Go to the [22.10 ISO download page](https://releases.ubuntu.com/22.10/) and download the latest Ubuntu 22.10 live-server ISO. +Go to the [23.10 ISO download page](https://releases.ubuntu.com/23.10/) and download the latest Ubuntu 23.10 live-server ISO. ### Mount the ISO -
sudo mount -r ~/Downloads/ubuntu-22.10-live-server-amd64.iso /mnt
+```bash +sudo mount -r ~/Downloads/ubuntu-23.10-live-server-amd64.iso /mnt +``` ### Write your autoinstall config This means creating cloud-init config as follows: -
mkdir -p ~/www
+```bash
+mkdir -p ~/www
 cd ~/www
 cat > user-data << 'EOF'
 #cloud-config
@@ -33,38 +34,46 @@ autoinstall:
     password: "$6$exDY1mhS4KUYCE/2$zmn9ToZwTKLhCw.b4/b.ZRTIZM30JZ4QrOQ2aOXJ8yk96xpcCof0kxKwuX1kqLG/ygbJ1f8wxED22bTL4F46P0"
     username: ubuntu
 EOF
-touch meta-data
- +touch meta-data +``` The crypted password is just "ubuntu". -### Serve the cloud-init config over http +### Serve the cloud-init config over HTTP -Leave this running in one terminal window: +Leave this running in a new terminal window: -
cd ~/www
-python3 -m http.server 3003
+```bash +cd ~/www +python3 -m http.server 3003 +``` ### Create a target disk -
truncate -s 10G image.img
+```bash +truncate -s 10G image.img +``` ### Run the install! -
kvm -no-reboot -m 2048 \
+```bash
+kvm -no-reboot -m 2048 \
     -drive file=image.img,format=raw,cache=none,if=virtio \
     -cdrom ~/Downloads/ubuntu-22.10-live-server-amd64.iso \
     -kernel /mnt/casper/vmlinuz \
     -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 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 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. ### Boot the installed system -
kvm -no-reboot -m 2048 \
-    -drive file=image.img,format=raw,cache=none,if=virtio
+```bash +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 will boot into the freshly installed system and you should be able to log in as `ubuntu`/`ubuntu`. ## Using another volume to provide the autoinstall config @@ -72,11 +81,12 @@ This is the method to use when you want to create media that you can just plug i ### Download the live-server ISO -Go to the [22.10 ISO download page](https://releases.ubuntu.com/22.10/) and download the latest Ubuntu 22.10 live-server ISO. +Go to the [23.10 ISO download page](https://releases.ubuntu.com/23.10/) and download the latest Ubuntu 23.10 live-server ISO. -### Create your user-data & meta-data files +### Create your `user-data` and `meta-data` files -
mkdir -p ~/cidata
+```bash
+mkdir -p ~/cidata
 cd ~/cidata
 cat > user-data << 'EOF'
 #cloud-config
@@ -87,35 +97,44 @@ autoinstall:
     password: "$6$exDY1mhS4KUYCE/2$zmn9ToZwTKLhCw.b4/b.ZRTIZM30JZ4QrOQ2aOXJ8yk96xpcCof0kxKwuX1kqLG/ygbJ1f8wxED22bTL4F46P0"
     username: ubuntu
 EOF
-touch meta-data
+touch meta-data +``` The crypted password is just "ubuntu". ### Create an ISO to use as a cloud-init data source -
sudo apt install cloud-image-utils
-cloud-localds ~/seed.iso user-data meta-data
+```bash +sudo apt install cloud-image-utils +cloud-localds ~/seed.iso user-data meta-data +``` ### Create a target disk -
truncate -s 10G image.img
+```bash +truncate -s 10G image.img +``` ### Run the install! -
kvm -no-reboot -m 2048 \
+```bash
+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-22.10-live-server-amd64.iso
+ -cdrom ~/Downloads/ubuntu-22.10-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 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. -The installer reboots at the end but the -no-reboot flag to kvm means that kvm will exit when this happens. +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. ### Boot the installed system -
kvm -no-reboot -m 2048 \
-    -drive file=image.img,format=raw,cache=none,if=virtio
+```bash +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 will boot into the freshly installed system and you should be able to log in as `ubuntu`/`ubuntu`. diff --git a/documentation/autoinstall-reference.md b/documentation/autoinstall-reference.md index 545477e1..091f5696 100644 --- a/documentation/autoinstall-reference.md +++ b/documentation/autoinstall-reference.md @@ -163,7 +163,7 @@ Identifier of the source to install (e.g., `"ubuntu-server-minimal"`). **default:** DHCP on interfaces named eth\* or en\* **can be interactive:** yes -[Netplan-formatted](https://netplan.io/reference) network configuration. This will be applied during installation as well as in the installed system. The default is to interpret the config for the install media, which runs DHCPv4 on any interface with a name matching "eth\*" or "en\*" but then disables any interface that does not receive an address. +[Netplan-formatted](https://netplan.readthedocs.io/en/stable/netplan-yaml/) network configuration. This will be applied during installation as well as in the installed system. The default is to interpret the config for the install media, which runs DHCPv4 on any interface with a name matching "eth\*" or "en\*" but then disables any interface that does not receive an address. For example, to run DHCPv6 on a particular NIC: @@ -335,7 +335,7 @@ storage: The default is to use the `lvm` layout. -#### Sizing-policy +#### sizing-policy The lvm layout will, by default, attempt to leave room for snapshots and further expansion. A sizing-policy key may be supplied to control this behavior. diff --git a/documentation/autoinstall.md b/documentation/autoinstall.md index 0552987a..3cb1442e 100644 --- a/documentation/autoinstall.md +++ b/documentation/autoinstall.md @@ -1,63 +1,63 @@ -# Automated Server Installs - ## Introduction -Since version 20.04, the server installer supports the automated installation mode, autoinstallation for short. You might also know this feature as unattended or handsoff or preseeded installation. +Since version 20.04, the server installer supports automated installation mode (autoinstallation for short). You might also know this feature as *unattended*, *hands-off*, or *preseeded* installation. -Autoinstallation lets you answer all those configuration questions ahead of time with an *autoinstall config* and lets the installation process run without any interaction. +Autoinstallation lets you answer all those configuration questions ahead of time with an *autoinstall config*, and lets the installation process run without any interaction. ## Differences from debian-installer preseeding -*preseeds* are the way to automate an installer based on debian-installer (aka d-i). +*Preseeds* are the way to automate an installer based on debian-installer (a.k.a. *d-i*). -autoinstalls for the new server installer differ from preseeds in the following main ways: +Autoinstalls for the new server installer differ from preseeds in the following main ways: - * the format is completely different (cloud-init config, usually yaml, vs debconf-set-selections format) - * when the answer to a question is not present in a preseed, d-i stops and asks the user for input. autoinstalls are not like this: by default, if there is any autoinstall config at all, the installer takes the default for any unanswered question (and fails if there is no default). - * You can designate particular sections in the config as "interactive", which means the installer will still stop and ask about those. + * The format is completely different (cloud-init config, usually YAML, vs. `debconf-set-selections` format). + * When the answer to a question is not present in a preseed, d-i stops and asks the user for input. Autoinstalls are not like this: by default, if there is any autoinstall config at all, the installer takes the default for any unanswered question (and fails if there is no default). + * You can designate particular sections in the config as "interactive", which means the installer will still stop and ask about those. -## Providing the autoinstall config +## Provide the autoinstall config via cloud-init -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 [nocloud](https://cloudinit.readthedocs.io/en/latest/topics/datasources/nocloud.html) data source. +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 NoCloud datasource](https://cloudinit.readthedocs.io/en/latest/reference/datasources/nocloud.html). The autoinstall config should be provided under the `autoinstall` key in the config. For example: - #cloud-config - autoinstall: - version: 1 - ... +```yaml +#cloud-config +autoinstall: + version: 1 + ... +``` -## Running a truly automatic autoinstall +## Run a truly automatic autoinstall -Even if a fully noninteractive autoinstall config is found, the server installer will ask for confirmation before writing to the disks unless `autoinstall` is present on the kernel command line. This is to make it harder to accidentally create a USB stick that will reformat a machine it is plugged into at boot. Many autoinstalls will be done via netboot, where the kernel command line is controlled by the netboot config -- just remember to put `autoinstall` in there! +Even if a fully non-interactive autoinstall config is found, the server installer will ask for confirmation before writing to the disks unless `autoinstall` is present on the kernel command line. This is to make it harder to accidentally create a USB stick that will reformat the machine it is plugged into at boot. Many autoinstalls will be done via netboot, where the kernel command line is controlled by the netboot config -- just remember to put `autoinstall` in there! -## Quick start +### Quick start So you just want to try it out? Well we have [the page for you](autoinstall-quickstart.md). -## Creating an autoinstall config +### Create an autoinstall config When any system is installed using the server installer, an autoinstall file for repeating the install is created at `/var/log/installer/autoinstall-user-data`. -# Translating a preseed file +### Translate a preseed file -If you have a preseed file already, the [autoinstall-generator](https://snapcraft.io/autoinstall-generator) snap can assist in translating that preseed data to an autoinstall file. See this [discussion](https://discourse.ubuntu.com/t/autoinstall-generator-tool-to-help-with-creation-of-autoinstall-files-based-on-preseed/21334) for more details. +If you have a preseed file already, the [autoinstall-generator snap](https://snapcraft.io/autoinstall-generator) can help translate that preseed data to an autoinstall file. See this discussion on the [autoinstall generator tool](https://discourse.ubuntu.com/t/autoinstall-generator-tool-to-help-with-creation-of-autoinstall-files-based-on-preseed/21334) for more details on how to set this up. -# The structure of an autoinstall config +## The structure of an autoinstall config The autoinstall config has [full documentation](autoinstall-reference.md). -Technically speaking the config is not defined as a textual format, but cloud-init config is usually provided as YAML so that is the syntax the documentation uses. +Technically speaking, the config is not defined as a textual format, but cloud-init config is usually provided as YAML so that is the syntax the documentation uses. A minimal config consists of: -A minimal config is: +```yaml +version: 1 +identity: + hostname: hostname + username: username + password: $crypted_pass +``` - version: 1 - identity: - hostname: hostname - username: username - password: $crypted_pass - -Here is an example file that shows off most features: +However, here is a more complete example file that shows off most features: 
version: 1
 reporting:
@@ -127,30 +127,30 @@ Here is an example file that shows off most features:
 
 Many keys and values correspond straightforwardly to questions the installer asks (e.g. keyboard selection). See the reference for details of those that do not.
 
-# Error handling
+## Error handling
 
-Progress through the installer is reported via the [`reporting`](autoinstall-reference.md#reporting) system, including errors. In addition, when a fatal error occurs, the [`error-commands`](autoinstall-reference.md#error-commands) are executed and the traceback printed to the console. The server then just waits.
+Progress through the installer is reported via [the `reporting` system](/t/automated-server-install-reference/16613#reporting), including errors. In addition, when a fatal error occurs, the [`error-commands`](/t/automated-server-install-reference/16613#error-commands) are executed and the traceback printed to the console. The server then just waits.
 
-# Interactions between Autoinstall and Cloud-init
+## Interactions between Autoinstall and Cloud-init
 
-## Delivery of Autoinstall
+### Delivery of Autoinstall
 
-Cloud-config can be used to deliver the Autoinstall data to the installation environment. The [autoinstall quickstart](autoinstall-quickstart.md) has an [example](autoinstall-quickstart.md#write-your-autoinstall-config) demonstrating this.
+Cloud-config can be used to deliver the autoinstall data to the installation environment. The [autoinstall quickstart](/t/automated-server-install-quickstart/16614) has an example of [writing the autoinstall config](/t/automated-server-install-quickstart/16614#write-your-autoinstall-config).
 
-Note that Autoinstall is processed by Subiquity (not Cloud-init), so please direct defects in Autoinstall behavior to [Subiquity](https://bugs.launchpad.net/subiquity/+filebug).
+Note that autoinstall is processed by Subiquity (not cloud-init), so please direct defects in autoinstall behavior and [bug reports to Subiquity](https://bugs.launchpad.net/subiquity/+filebug).
 
-## The installation environment
+### The installation environment
 
-At install time, the live-server environment is just that, a live but ephemeral copy of Ubuntu Server.  This means that Cloud-init is present and running in that environment, and existing methods of interacting with Cloud-init can be used to configure the live-server ephemeral environment.  For example, any #cloud-config user-data keys are presented to the live-server containing [`ssh_import_id`](https://cloudinit.readthedocs.io/en/latest/topics/modules.html?highlight=ssh#ssh-import-id), then ssh keys will be added to the authorized_keys list for the ephemeral environment.
+At install time, the live-server environment is just that: a live but ephemeral copy of Ubuntu Server.  This means that cloud-init is present and running in that environment, and existing methods of interacting with cloud-init can be used to configure the live-server ephemeral environment. For example, any #cloud-config user data keys are presented to the live-server containing [`ssh_import_id`]( https://cloudinit.readthedocs.io/en/latest/reference/modules.html#ssh-import-id), then SSH keys will be added to the `authorized_keys` list for the ephemeral environment.
 
-## First boot configuation of the target system
+### First boot configuration of the target system
 
-Autoinstall data may optionally contain a [user-data](autoinstall-reference.md#user-data) sub-section, which is cloud-config data that is used to configure the target system on first boot.
+Autoinstall data may optionally contain a [user data sub-section](/t/automated-server-install-reference/16613#user-data), which is cloud-config data that is used to configure the target system on first boot.
 
-Subiquity itself delegates some configuration items to Cloud-init, and these items are processed on first boot.
+Subiquity itself delegates some configuration items to cloud-init, and these items are processed on first boot.
 
-Starting with Ubuntu 22.10, once Cloud-init has performed this first boot configuration, it will disable itself as cloud-init completes configuration in the target system on first boot.
+Starting with Ubuntu 22.10, once cloud-init has performed this first boot configuration, it will disable itself as cloud-init completes configuration in the target system on first boot.
 
-# Possible future directions
+### Possible future directions
 
 We might want to extend the 'match specs' for disks to cover other ways of selecting disks.