integration-test, xtask: Move xtask run docs into README

test/README.md

@@ -1,7 +1,6 @@
-Aya Integration Tests
-=====================
+# Aya Integration Tests
 
-The aya integration test suite is a set of tests to ensure that
+The Aya integration test suite is a set of tests to ensure that
 common usage behaviours work on real Linux distros
 
 ## Prerequisites
@@ -19,21 +18,67 @@ From the root of this repository:
 
 ### Native
 
-```
+```console
 cargo xtask integration-test local
 ```
 
 ### Virtualized
 
+VM tests require a kernel image to test with.
+
+#### Obtaining a kernel image
+
+##### Debian
+
+To download an image from the Debian project:
+
+- Browse to the [Debian FTP site](ftp://ftp.us.debian.org/debian/pool/main/l/linux/) for the kernel version you require
+- Download the kernel into `tests/.tmp/debian-kernels/${architecture}/`
+
+```bash
+wget -nd -q -P test/.tmp/debian-kernels/x86_64 \
+ ftp://ftp.us.debian.org/debian/pool/main/l/linux/linux-image-5.10.0-23-cloud-amd64-unsigned_5.10.179-3_amd64.deb
+```
+
+- Extract the kernel image:
+
+```bash
+dpkg --fsys-tarfile test/.tmp/debian-kernels/arm64/linux-image-5.10.0-23-cloud-amd64-unsigned_5.10.179-3_amd64.deb | tar -C test/.tmp --wildcards --extract '*vmlinuz*' --file -
+```
+
+#### Fedora
+
+To download an image from the Fedora project:
+
+- Search for the kernel version you require on [Koji](https://koji.fedoraproject.org/koji/search?match=glob&type=build&terms=kernel-4*)
+- Copy the download link for the `kernel-core-${version}.rpm` and download it into `tests/.tmp/fedora-kernels/${architecture}/`
+
+```bash
+wget -nd -P test/.tmp/fedora-kernels/x86_64 \
+ https://kojipkgs.fedoraproject.org//packages/kernel/5.10.23/200.fc33/x86_64/kernel-core-5.10.23-200.fc33.x86_64.rpm
+```
+
+- Extract the kernel image:
+
+```bash
+rpm2cpio ./test/.tmp/fedora-kernels/x86_64/kernel-core-5.10.23-200.fc33.x86_64.rpm \
+ | cpio -iv --to-stdout ./lib/modules/5.10.23-200.fc33.x86_64/vmlinuz > ./test/.tmp/boot/vmlinuz-5.10.23-200.fc33.x86_64
 ```
-cargo xtask integration-test vm
+
+#### Running the tests
+
+To run the tests run the following command, replacing `/path/to/vmlinuz` with
+the path to the kernel image you extracted above:
+
+```console
+cargo xtask integration-test vm /path/to/vmlinuz
 ```
 
 ### Writing an integration test
 
 Tests should follow these guidelines:
 
-- Rust eBPF code should live in `integration-ebpf/${NAME}.rs` and included in
+- Rust eBPF code should live in `integration-ebpf/${NAME}.rs` and be included in
  `integration-ebpf/Cargo.toml` and `integration-test/src/lib.rs` using
  `include_bytes_aligned!`.
 - C eBPF code should live in `integration-test/bpf/${NAME}.bpf.c`. It should be

xtask/src/run.rs

@@ -25,17 +25,6 @@ enum Environment {
  /// Runs the integration tests in a VM.
  VM {
  /// The kernel images to use.
- ///
- /// You can download some images with:
- ///
- /// wget --accept-regex '.*/linux-image-[0-9\.-]+-cloud-.*-unsigned*' \
- /// --recursive ftp://ftp.us.debian.org/debian/pool/main/l/linux/
- ///
- /// You can then extract them with:
- ///
- /// find . -name '*.deb' -print0 \
- /// | xargs -0 -I {} sh -c "dpkg --fsys-tarfile {} \
- /// | tar --wildcards --extract '*vmlinuz*' --file -"
  #[clap(required = true)]
  kernel_image: Vec<PathBuf>,
  },