From c12b29fa3bda050a228fa41692db55ef172520ad Mon Sep 17 00:00:00 2001 From: Razvan Deaconescu Date: Tue, 12 Mar 2024 12:40:20 +0200 Subject: [PATCH] docs/faq: Add common pitfalls Add common pitfalls from using / building Unikraft. Signed-off-by: Razvan Deaconescu --- content/docs/faq.mdx | 216 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 214 insertions(+), 2 deletions(-) diff --git a/content/docs/faq.mdx b/content/docs/faq.mdx index d16b92cf..9e80508f 100644 --- a/content/docs/faq.mdx +++ b/content/docs/faq.mdx @@ -20,7 +20,7 @@ description: | - A function in the initialization table failed. + A function in the initialization table failed. First, join our community server on [Discord](https://bit.ly/UnikraftDiscord). Then, send a Pull Request, if you already have an idea of contribution, or ask the community for some contribuition ideas. - For more details, see the [Contributing](/docs/contributing/) section. + For more details, see the [Contributing](/docs/contributing/) section. + + This is caused by missing KVM support. + This may be the case if: + + * you are running an ARM64 image on x86_64 (or viceversa) + * you are using a virtual machine for development / deployment + * you are using Windows (with WSL) or macOS + * your system simply doesn't have KVM support. + + If you are using `kraft run`, use the `-W` option to disable KVM support requirement. + If you are using QEMU, be sure to **not** use the `-enable-kvm` nor the `-accel kvm` options. + Firecracker currently requires KVM support; + you can't run it on a KVM-less system. + + + Use `Ctrl+a x` (i.e. press `Ctrl` and `a` keys simultanously, release, then press `x` key) to close an open QEMU instance in the terminal. + You can also kill all QEMU instances by running, in another console: + + ```console + pkill -f qemu-system + ``` + + + There's no keyboard shortcut to stop a running Firecracker instance. + You either find out the pid and kill it: + + ```console + pgrep -f firecracker + kill + ``` + + Replace `` with the actual PID (_Process ID_) returned by `pgrep`. + + You can also kill all Firecracker instances by running, in another console: + + ```console + pkill -f firecracker + ``` + + + If you use `Ctrl+c` that will close the current KraftKit controlling process, but may not fully remove the runtime information, including potential port mappings and potential started QEMU / Firecracker / Xen processes. + + Use `--rm` as argument to `kraft run` to remove the underlying runtime when using `Ctrl+c`. + + To list all active / inactive KraftKit instances, use: + + ```console + kraft ps -a + ``` + + To stop an instance or all instances, or to remove an instance or all instances use: + + ```console + kraft stop + kraft stop --all + kraft rm + kraft rm --all + ``` + + + There is another instance running that is using port `8080`. + That may be a KraftKit instance, a QEMU instance, a Firecracker instance, or something else. + + First, check the listening services to detect what is using the port: + + ```console + netstat -tlpn + ``` + + You can also check running KraftKit or QEMU or Firecracker instances: + + ``` + kraft ps -a + ps -ef | grep qemu-system + ps -ef | grep firecracker + ``` + + You can stop them to free the port: + + ```console + kraft rm + kill + kill + ``` + + You can also stop all running instances: + + ```console + kraft rm --all + pkill -f qemu-system + pkill -f firecracker + ``` + + + This is because you passed the debug image (with the `.dbg` extension) to QEMU. + You need to pass the actual image (i.e. **without** the `.dgb` extension). + The image with the `.dbg` extension is used by GDB. + + See more [here](https://unikraft.org/guides/debugging#using-gdb). + + + It's because you don't use KVM support and large pages are required. + Pass the `-cpu max` option to `qemu-system-x86_64`. + + + You need to also pass the tag, the full command should be: + + ```console + kraft run unikraft.org/: + ``` + + e.g. + + ```console + kraft run unikraft.org/nginx:1.25 + kraft run unikraft.org/ruby:3.2 + ``` + + + You didn't provide enough memory. + Use the `-M` option to `kraft run`, e.g.: + + ```console + kraft run -M 256M unikraft.org/ruby:3.2 + ``` + + + The `app-...` repositories are archived and no longer in use. + Visit the [`catalog` repository](https://github.com/unikraft/catalog) and see applications and examples there. + + + Your goal should be to add the appplication to the [`catalog` repository](https://github.com/unikraft/catalog). + Follow these guides: + + * [Using the Application Catalog](https://unikraft.org/guides/using-the-app-catalog) + * [Behind the Scenes with the Application Catalog](https://unikraft.org/guides/catalog-behind-the-scenes) + * [Adding Applications to the Catalog](https://unikraft.org/docs/contributing/adding-to-the-app-catalog) + + + In its default configuration, KraftKit will start a temporary / transient [BuildKit instance](https://docs.docker.com/build/buildkit/). + + To speed things up, start a more permanent BuildKit instance that will cache the built filesystems. + Follow the instruction [here](https://unikraft.org/guides/building-dockerfile-images-with-buildkit) to start a more permanent BuildKit instance. + + + Use the commands below to clear all KraftKit-related information and then refresh it. + + ```console + kraft rm --all + kraft pkg rm --all + rm -fr ~/.local/share/kraftkit/ + kraft pkg ls --apps --update + ``` + + + + Make sure you remove the local configuration and output files beforehand: + + ```console + rm -f config* + rm -fr .unikraft + ``` + + There are cached version of repositories. + You can clean the KraftKit setup with the steps above: + + ```console + kraft rm --all + kraft pkg rm --all + rm -fr ~/.local/share/kraftkit/ + kraft pkg ls --apps --update + ``` + + Otherwise, request `kraft build` to use only fresh images: + + ```console + kraft build --no-cache --no-update ... + ``` +