docs/linux: recommend setting net.ifnames to 0

When net.ifnames is set to 1, syzkaller might not be able to connect
to the virtual machines. Add the corresponding recommendations to the
documentation as well as a note to the troubleshooting guide.

3 files changed, 50 insertions, 0 deletions

diff --git a/docs/linux/kernel_configs.md b/docs/linux/kernel_configs.md
index ebd907955..b6dc311c2 100644
--- a/docs/linux/kernel_configs.md
+++ b/docs/linux/kernel_configs.md
@@ -65,6 +65,13 @@ It is recommended to disable the following config (and required if your kernel d
 # CONFIG_RANDOMIZE_BASE is not set
 ```
 
+It is also recommended to disable the Predictable Network Interface Names mechanism. This can be done
+either via syzkaller configuration (see details [here](troubleshooting.md)) or by adjusting the following configs:
+```
+CONFIG_CMDLINE_BOOL=y
+CONFIG_CMDLINE="net.ifnames=0"
+```
+
 ## Bug detection configs
 
 Syzkaller is meant to be used with
diff --git a/docs/linux/setup_ubuntu-host_qemu-vm_x86-64-kernel.md b/docs/linux/setup_ubuntu-host_qemu-vm_x86-64-kernel.md
index b54013199..7de20e6f5 100644
--- a/docs/linux/setup_ubuntu-host_qemu-vm_x86-64-kernel.md
+++ b/docs/linux/setup_ubuntu-host_qemu-vm_x86-64-kernel.md
@@ -61,6 +61,13 @@ Since enabling these options results in more sub options being available, we nee
 make CC="$GCC/bin/gcc" olddefconfig
 ```
 
+You might also be interested in disabling the Predictable Network Interface Names mechanism. This can be disabled either in the syzkaller configuration (see details [here](troubleshooting.md)) or by updating these kernel configuration parameters:
+
+```
+CONFIG_CMDLINE_BOOL=y
+CONFIG_CMDLINE="net.ifnames=0"
+```
+
 Build the kernel:
 
 ```
diff --git a/docs/linux/troubleshooting.md b/docs/linux/troubleshooting.md
index 76f780fa4..3993dc1f6 100644
--- a/docs/linux/troubleshooting.md
+++ b/docs/linux/troubleshooting.md
@@ -27,6 +27,42 @@ Here are some things to check if there are problems running syzkaller.
      CONFIG_E1000=y
      CONFIG_E1000E=y
      ```
+ - If the virtual machine reports that it has "Failed to start Raise network interfaces" or (which
+   is a consequence of that) syzkaller is unable to connect to the virtual machines, try to disable
+   the Predictable Network Interface Names mechanism. There are two ways to achieve this:
+    - Add the following two lines to the kernel configuration file and recompile the kernel.
+      ```
+      CONFIG_CMDLINE_BOOL=y
+      CONFIG_CMDLINE="net.ifnames=0"
+      ```
+    - Add the following line to the VM's properties inside the syzkaller manager configuration:
+      ```
+      "cmdline": "net.ifnames=0"
+      ```
+
+      The resulting configuration may look like this:
+      ```json
+      {
+        "target": "linux/amd64",
+        "http": "127.0.0.1:56741",
+        "workdir": "$GOPATH/src/github.com/google/syzkaller/workdir",
+        "kernel_obj": "$KERNEL",
+        "image": "$IMAGE/stretch.img",
+        "sshkey": "$IMAGE/stretch.id_rsa",
+        "syzkaller": "$GOPATH/src/github.com/google/syzkaller",
+        "procs": 8,
+        "type": "qemu",
+        "vm": {
+            "count": 4,
+            "kernel": "$KERNEL/arch/x86/boot/bzImage",
+            "cmdline": "net.ifnames=0",
+            "cpu": 2,
+            "mem": 2048
+        }
+      }
+      ```
+
+      This is, however, not guaranteed to work across all virtualization technologies.
 
  - Check that the `CONFIG_KCOV` option is available inside the VM:
     - `ls /sys/kernel/debug       # Check debugfs mounted`