Writing Linux Kernel Modules in Rust (https://www.youtube.com/watch?v=-l-8WrGHEGI & https://drive.google.com/drive/folders/1nmUhDVJxCKolkDN64U7Brm4kBQrvUGPq )

Rust_qemu_instructions.txt

Introduction
============

This short document contains instructions on how to install QEMU and run a
virtual machine with the disk image provided for the _Writing Linux Kernel
Modules in Rust_ session of the LF Mentorship Series.

It assumes that you have an x86-64 system running a 64-bit Linux operating
system with KVM enabled.

Installing QEMU
===============

QEMU is an open source machine emulator and virtualizer. We will use it to run a
virtual machine. If you already have it installed, you can skip to the next
section.

Otherwise, use the following command to install it on Linux distributions that
use `apt` as their package manager (e.g., Debian, Ubuntu, and derivatives):

```
sudo apt-get install qemu-kvm
```

Running the virtual machine (VM)
================================

Decompressing the disk image
----------------------------

Before running the VM, you need to decompress the disk image, which you can do
with the following command:

```
xz -d -k -T 0 disk.img.xz
```

This will create a new file called `disk.img` (i.e., no `.xz` suffix).

Starting the VM
---------------

Once QEMU is installed and the disk image is decompressed, use the following
command to launch the VM:

```
sudo qemu-system-x86_64 -m 8G -smp 16 -nographic -nic user,model=virtio-net-pci,hostfwd=tcp::2222-:22 -hda disk.img -enable-kvm
```

The arguments do the following:

- `-m 8G`: runs the VM with 8GB of memory. You may want to adjust this based
   on the amount of memory your system has.
- `-smp 16`: runs the VM with 16 cores. You may also want to adjust this based
   on the number of cores your system has.
- `-nographic`: disables any graphics and redirects the VM's serial console to
   the host shell.
- `-nic user,model=virtio-net-pci,hostfw=tcp::2222-:22`: enables networking on
   the VM (so it can access the internet) and redirects its port 22 to the host
   port 2222 so that you can ssh into the VM from the host.
- `-hda disk.img`: specifies the disk image to use with the VM. This must
   contain the path to the decompressed disk image.
- `-enable-kvm`: runs the VM with hardware acceleration. You may omit this, but
   the VM may be too slow.

Using the VM
============

The VM does not have a graphical user interface (GUI), all interactions are via
a text-mode console.

Once the VM starts, it will output messages indicating the boot process and will
eventually settle on the following prompt:

```
Debian GNU/Linux 11 debian ttyS0

debian login:
```

Connecting to the console
-------------------------

Once the VM reaches the login message above, you can login with the username
`guest` and password `guest`, which will lead you a shell similar to the
following:

```
Debian GNU/Linux 11 debian ttyS0

debian login: guest
Password:
Linux debian 5.10.0-14-cloud-amd64 #1 SMP Debian 5.10.113-1 (2022-04-29) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Thu Jun 23 12:36:51 UTC 2022 on ttyS0
Jun 23 12:38:01 debian systemd[1]: Started Session 3 of user guest.
guest@debian:~$
```

Connecting via SSH
------------------

You can also connect via SSH (which will give you a better terminal and allows
you to have more than one shell) using the following command:

```
ssh -p 2222 guest@localhost
```

It will ask you for the password, which is `guest`.

### Troubleshooting

The first time you run the command above, you'll likely see a message similar to:

```
The authenticity of host '[localhost]:2222 ([127.0.0.1]:2222)' can't be established.
ED25519 key fingerprint is SHA256:MudJqrrvf6MjAnRyKvHpq/9WzMZJB2Qp2q52tbSLX/8.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])?
```

To which you can safely answer `yes`.

If your `ssh` client is configured to only allow authentication with public
keys, you may need to run it as follows to force it to use password
authentication:

```
ssh -o PreferredAuthentications=password -o PubkeyAuthentication=no -p 2222 guest@localhost
```

Conclusion
==========

Once you reach the VM shell (preferably via ssh), you're ready to join the
session!

You may want to explore the `~/linux` directory as it contains a full checkout
of the Linux kernel source code with Rust enabled.

Tmux and the Neovim editor are also installed, the latter with a Rust LSP plugin
that allows you to browse the source code, jump to definitions, see
documentation, etc. Just run `nvim` from the `~/linux` directory.