Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
docs:guide-user:virtualization:virtualbox-vm [2018/12/21 19:38] – [VM setup] jeffdocs:guide-user:virtualization:virtualbox-vm [2023/10/20 01:46] (current) – [VM setup] atownlede
Line 1: Line 1:
-====== Run OpenWrt as a Virtualbox virtual machine ====== +====== OpenWrt on VirtualBox HowTo ====== 
-This document describes how to run the x86-64 OpenWrt images in [[https://www.virtualbox.org|VirtualBox]], or VB for short.+This document describes how to run the x86-64 OpenWrt images in <abbr>Virtual Machine (VM)</abbr> [[https://www.virtualbox.org|VirtualBox]], or VBox for short.
  
 ===== Prerequisites ===== ===== Prerequisites =====
   * Download and install [[https://www.virtualbox.org/wiki/Downloads|VirtualBox]]   * Download and install [[https://www.virtualbox.org/wiki/Downloads|VirtualBox]]
-  * Download and install the Virtualbox Guest Additions (needed for USB connectivity among others) +  * Download and install the VirtualBox Guest Additions (needed for USB connectivity among others) 
-  * Download the //openwrt-x86-64-combined-squashfs.img// image, from [[https://downloads.openwrt.org/snapshots/targets/x86/64/|snapshots/targets/x86/64/]](On Linux, downlaod the //openwrt-x86-64-combined-ext4.img// image)+ 
 +==== Select an OpenWrt image ==== 
 +You need a [[docs:guide-user:installation:openwrt_x86|x86 64 bit version of OpenWrt]]. 
 +There is two versions of them: 
 + 
 +  * ''combined-squashfs.img.gz'' This disk image uses the traditional OpenWrt layout, a squashfs read-only root filesystem and a read-write partition where settings and packages you install are stored. Due to how this image is assembled, you will have only 230-ish MB of space to store additional packages and configuration, and Extroot does not work. 
 +  * ''combined-ext4.img.gz'' This disk image uses a single read-write ext4 partition with no read-only squashfs root filesystem, which allows to enlarge the partition. Features like Failsafe Mode or Factory Reset won't be available as they need a read-only squashfs partition to function. 
 + 
 +In the guide we'll use //openwrt-x86-64-combined-ext4.img.gz// because it has fewer limitations. 
 + 
 +  * Download a stable release of the //openwrt-x86-64-combined-ext4.img.gz// image from [[https://archive.openwrt.org/releases/|targets/x86/64/ folder]] e.g. [[https://archive.openwrt.org/releases/22.03.5/targets/x86/64/openwrt-22.03.5-x86-64-generic-ext4-combined.img.gz|22.03.5]]. Or you can try the fresher but unstable [[https://downloads.openwrt.org/snapshots/targets/x86/64/openwrt-x86-64-generic-ext4-combined.img.gz|snapshot]] image 
 +  * Uncompress the gziped img file. On Linux use the command ''gzip -d openwrt-*.img.gz''. As a result you should get the raw ''openwrt-x86-64-combined-ext4.img'' image  file. 
 + 
 +=== Custom Images === 
 +You can compile your own image (//Target System -> x86-64// and //Target Images -> Build VirtualBox image files//). ''ext4'' needs to be enabled first. 
 + 
 +==== Convert openwrt.img to VBox drive ====
   * Open a terminal and go in the folder where you have downloaded the file (sorry, the tool has only a command line interface)   * Open a terminal and go in the folder where you have downloaded the file (sorry, the tool has only a command line interface)
-  * Convert it to native VB format by writing this in command line (the same for Windows, Mac and Linux. Sadly this tool does not have graphical user interface): ''VBoxManage convertfromraw %%--%%format VDI openwrt-x86-64-combined-squashfs.img openwrt-x86-64-combined-squashfs.vdi'' (tested and working in VB 5.1.8, 5.1.10 on debian8, 5.2.22 on macOS)+  * Convert it to native VBox format by writing this in command line (the same for Windows, macOS and Linux. Sadly this tool does not have graphical user interface): ''VBoxManage convertfromraw %%--%%format VDI openwrt-*.img openwrt.vdi''. This will create the ''openwrt.vdi'' file which a virtual drive for VBox virtual machine.
  
-if you receive an error similar to\\ +=== Error === 
 +If you receive an error similar to\\ 
 <code>VBoxManage: error: VD: The given disk size 19444018 is not aligned on a sector boundary (512 bytes) <code>VBoxManage: error: VD: The given disk size 19444018 is not aligned on a sector boundary (512 bytes)
 VBoxManage: error: Error code VERR_VD_INVALID_SIZE at /Users/vbox/tinderbox/5.1-mac-rel/src/VBox/Storage/VD.cpp(7002) in function int VDCreateBase(PVBOXHDD, const char *, const char *, uint64_t, unsigned int, const char *, PCVDGEOMETRY, PCVDGEOMETRY, PCRTUUID, unsigned int, PVDINTERFACE, PVDINTERFACE) VBoxManage: error: Error code VERR_VD_INVALID_SIZE at /Users/vbox/tinderbox/5.1-mac-rel/src/VBox/Storage/VD.cpp(7002) in function int VDCreateBase(PVBOXHDD, const char *, const char *, uint64_t, unsigned int, const char *, PCVDGEOMETRY, PCVDGEOMETRY, PCRTUUID, unsigned int, PVDINTERFACE, PVDINTERFACE)
 VBoxManage: error: Cannot create the disk image "openwrt.vdi": VERR_VD_INVALID_SIZE</code>\\ VBoxManage: error: Cannot create the disk image "openwrt.vdi": VERR_VD_INVALID_SIZE</code>\\
-you may need to pad the image with ''dd if=openwrt-x86-64-combined-squashfs.img of=openwrt.img bs=128000 conv=sync'' and use the padded image as input to VBoxManage convertfromraw. +you may need to pad the image with ''dd if=openwrt-x86-64-combined-ext4.img of=openwrt.img bs=128000 conv=sync'' and use the padded image as input to VBoxManage convertfromraw.
- +
-Or you can compile your own image (//Target System -> x86-64// and //Target Images -> Build VirtualBox image files//). ''ext4'' needs to be enabled first.+
  
   * Enlarge the image to a useful size (size is in MB)   * Enlarge the image to a useful size (size is in MB)
  
-  $ VboxManage modifymedium openwrt-x86-64-combined-squashfs.vdi --resize 128+  $ VBoxManage modifymedium openwrt.vdi --resize 128
   0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%   0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%
- 
- 
  
 ===== VM Setup in VirtualBox ===== ===== VM Setup in VirtualBox =====
- 
 ==== VM creation ==== ==== VM creation ====
-:!: tutorial and screenshots from Virtualbox 5.1.8 on Linux host, on Windows or MacOS hosts there will be some cosmetic differences (a different top bar) but the Virtualbox panels and buttons will be exactly the same+:!: Tutorial and screenshots from VirtualBox 5.1.8 on Linux host, on Windows or macOS hosts there will be some cosmetic differences (a different top bar) but the VirtualBox panels and buttons will be exactly the same
  
 {{docs:guide-user:vboxstart.png?direct&70 |}} Start VirtualBox and click //New// to add a virtual machine (VM)\\ {{docs:guide-user:vboxstart.png?direct&70 |}} Start VirtualBox and click //New// to add a virtual machine (VM)\\
Line 35: Line 47:
 {{docs:guide-user:vboxaddvm2.png?direct&70 |}} OpenWrt will work fine with much less RAM than the recommended amount, 128 MiB will be enough.  {{docs:guide-user:vboxaddvm2.png?direct&70 |}} OpenWrt will work fine with much less RAM than the recommended amount, 128 MiB will be enough. 
 ---- ----
-{{docs:guide-user:vboxaddvm3.png?direct&70 |}} Choose //Use an existing hard disk file//, click the //file// icon to open //Virtual Media Manager//, click //Add// and choose your ''.vdi'' file using the file chooser window. Click //Create// to end this guided procedure.\\+{{docs:guide-user:vboxaddvm3.png?direct&70 |}} Choose //Use an existing hard disk file//, click the //file// icon to open //Virtual Media Manager//, click //Add// and choose your ''openwrt.vdi'' file using the file chooser window. Click //Create// to end this guided procedure.\\
 ---- ----
-:!: It's recommended to place the disk image in a permanent place //before// linking it with VB. If you move it //afterwards//, VB will not find it anymore and will complain about this issue on next start (or when you try to start the VM). It will offer a guided procedure to link the disk image again, so don't worry. +:!: It's recommended to place the disk image in a permanent place //before// linking it with VBox. If you move it //afterwards//, VBox will not find it anymore and will complain about this issue on next start (or when you try to start the VM). It will offer a guided procedure to link the disk image again, so don't worry.
  
 ==== VM setup ==== ==== VM setup ====
 +
 +{{section>meta:infobox:howto_links#config-network-device&noheader&nofooter&noeditbutton}}
 +
 This part of the configuration will deal with setting up networking manually.\\ This part of the configuration will deal with setting up networking manually.\\
 The configuration you will set up by following this tutorial is: The configuration you will set up by following this tutorial is:
-  * **eth0** of the VM on **mng** (management) interface, fixed address 192.168.56.2, set in Virtualbox as **Host-only Adapter** on adapter **vboxnet0**. This interface will be __always__ available to the host even if host or VM are disconnected from any network. +  * **eth0** of the VM on **mng** (management) interface, fixed address 192.168.56.2, set in VirtualBox as **Host-only Adapter** on adapter **vboxnet0**. This interface will be __always__ available to the host even if host or VM are disconnected from any network. 
-  * **eth1** of the VM on **wan** interface, dynamic address, set in Virtualbox as **NAT**. This interface will be used to access the Internet through whatever setup the host also uses. +  * **eth1** of the VM on **wan** interface, dynamic address, set in VirtualBox as **NAT**. This interface will be used to access the Internet through whatever setup the host also uses. 
-  * //(optional) **eth2** of the VM on **lan** interface, configured depending on your local network, set in Virtualbox as **Bridged Adapter**. This interface allows other devices (host included) to connect to the VM as if it was a physical device in the local network. Will only work if there is already a local network of some kind.//+  * //(optional) **eth2** of the VM on **lan** interface, configured depending on your local network, set in VirtualBox as **Bridged Adapter**. This interface allows other devices (host included) to connect to the VM as if it was a physical device in the local network. Will only work if there is already a local network of some kind.//
   * //For a setup with 2 bridged physical network cards WAN/LAN Setup see [[#troubleshooting]]. The rest of this guide applies to a setup with 2 physical cards as well. //   * //For a setup with 2 bridged physical network cards WAN/LAN Setup see [[#troubleshooting]]. The rest of this guide applies to a setup with 2 physical cards as well. //
  
Line 53: Line 67:
 == Host-only network adapter == == Host-only network adapter ==
 we first need to make sure there is a Host-only network adapter and that it has the right settings\\ we first need to make sure there is a Host-only network adapter and that it has the right settings\\
 +Note: this is found in VBox 6.0 (at least for Windows) under Tools, and is pre-configured.
 ---- ----
-{{docs:guide-user:vboxvmhost-only-network1.png?direct&70 |}} click on **File** -> **Preferences** -> **Network**\\ +{{docs:guide-user:vboxvmhost-only-network1.png?direct&70 |}} Click on **File** -> **Preferences** -> **Network**\\ 
 On macOS, this setting may be found through File > Host Network Manager... On macOS, this setting may be found through File > Host Network Manager...
 ---- ----
-{{docs:guide-user:vboxvmhost-only-network2.png?direct&70 |}} click on Host-only Networks tab and then if you don't see a **vboxnet0** entry click on the  **+** icon on the right of the window to add a new one.\\+{{docs:guide-user:vboxvmhost-only-network2.png?direct&70 |}} Click on Host-only Networks tab and then if you don't see a **vboxnet0** entry click on the  **+** icon on the right of the window to add a new one.\\
 Now select the **vboxnet0** entry, and click on the screwdriver icon on the right to open its settings.\\ Now select the **vboxnet0** entry, and click on the screwdriver icon on the right to open its settings.\\
 ---- ----
Line 64: Line 79:
 {{docs:guide-user:vboxvmhost-only-network4.png?direct&70 |}} //(optional) you can also set the DHCP server as shown in the screenshot if you want to have dynamic addresses to the VM, but for this tutorial it is not required as we set a static address in the VM itself// {{docs:guide-user:vboxvmhost-only-network4.png?direct&70 |}} //(optional) you can also set the DHCP server as shown in the screenshot if you want to have dynamic addresses to the VM, but for this tutorial it is not required as we set a static address in the VM itself//
 ---- ----
-press OK to save and close until you are back to Virtualbox Manager interface again.+Press OK to save and close until you are back to VirtualBox Manager interface again.
  
 == Network Settings == == Network Settings ==
Line 84: Line 99:
     - //Click on **Advanced** and do the same you did for **Adapter 1**'s advanced options//     - //Click on **Advanced** and do the same you did for **Adapter 1**'s advanced options//
  
-=== VM Settings === +=== Virtual Machine Settings === 
-:!: due to limitations, the keyboard in the VM's terminal screen is set as US, so some (or most) of your keys will not print the right symbols.\\ +:!: Due to limitations, the keyboard in the virtual machine's terminal is set to US, so some (or most) of your keys may not print the symbols as indicated by the keycaps.\\ 
-Also, due to the fact that what you see there is a bare machine terminal and not a smart thing like a ssh program (Putty/Kitty/whatever) or a terminal emulator program, you cannot copy-paste text into it.\\+Also, due to the fact that what you see there is a bare machine terminal and not a smart thing like a SSH program (Putty/Kitty/whatever) or a terminal emulator program, you cannot copy-paste text into it.\\
 Don't worry, most of the setup will be done after you are connected with SSH (remote terminal) that does not have any of these issues.\\ Don't worry, most of the setup will be done after you are connected with SSH (remote terminal) that does not have any of these issues.\\
 {{docs:guide-user:1280px-qwerty.png?direct&50 |}} Look at this US keyboard layout to find what button you need to press on your keyboard to generate the right symbol.  {{docs:guide-user:1280px-qwerty.png?direct&50 |}} Look at this US keyboard layout to find what button you need to press on your keyboard to generate the right symbol. 
 ---- ----
-  - Boot into your VM+  - Boot into your Virtual Machine
   - Wait 4 seconds for GRUB to boot automatically   - Wait 4 seconds for GRUB to boot automatically
-  - Press Enter to activate the console when the boot messages have finished to scroll by. It may take two or three minutes for "entropy" to be generated (''random: crng init done'' with OpenWrt 17.01.4). Until there is sufficient entropy, ssh and other cryptographic functions may fail. +  - Press Enter to activate the console when the boot messages have finished scrolling by. It may take two or three minutes for "entropy" to be generated (''random: crng init done'' with OpenWrt 17.01.4). Until there is sufficient entropy, SSH and other cryptographic functions may fail. 
-  - let's see the current network configuration\\ <code>root@openwrt:~# uci show network+  - Display the current network configuration\\ <code>root@openwrt:~# uci show network
 network.loopback=interface network.loopback=interface
 network.loopback.ifname='lo' network.loopback.ifname='lo'
Line 115: Line 130:
 network.wan6.proto='dhcpv6'</code> network.wan6.proto='dhcpv6'</code>
 Note that the default LAN address of 192.168.1.1 is present on first boot. Note that the default LAN address of 192.168.1.1 is present on first boot.
-  - edit the network configuration to allow SSH access by writing these commands and pressing enter: +  - Edit the network configuration to allow SSH access by writing these commands and pressing enter: 
     - **uci set network.lan.ipaddr='192.168.56.2'**     - **uci set network.lan.ipaddr='192.168.56.2'**
     - **uci commit**     - **uci commit**
     - **reboot**     - **reboot**
-  - now your VM should be accessible from SSH, user **root** (no password) address **192.168.56.2** +  - Now your VM should be accessible from SSH, user **root** (no password) address **192.168.56.2** 
-  - after you have logged in successfully, we can actually do the true configuration, please copy-paste the following block of code and press enter:\\ <code>uci batch <<EOF +  - After you have logged in successfully, we can actually do the true configuration. For 22.03 and earlier, copy-paste the following block of code and press enter:\\ <code>uci batch <<EOF 
 set network.mng=interface  set network.mng=interface 
 set network.mng.type='bridge'  set network.mng.type='bridge' 
Line 131: Line 146:
 set network.wan=interface set network.wan=interface
 set network.wan.ifname='eth1' set network.wan.ifname='eth1'
 +set network.wan.proto='dhcp'
 +EOF</code>  For 23.05 and later, copy-paste the following:\\ <code>uci batch <<EOF 
 +set network.mng=interface 
 +set network.mng.device='br-lan'  
 +set network.mng.proto='static'
 +set network.mng.ipaddr='192.168.56.2'  
 +set network.mng.netmask='255.255.255.0'
 +set firewall.@zone[0].network='mng'
 +set firewall.@zone[0].name='mng'
 +delete network.lan
 +delete network.wan6
 +set network.wan=interface
 +set network.wan.device='eth1'
 set network.wan.proto='dhcp' set network.wan.proto='dhcp'
 EOF</code> EOF</code>
-  - now write **uci changes** to check if the setting configuration was loaded correctly. If you see the following (the **network.mng** entries MUST be the same as the ones shown here, the **network.wan** might be slightly different), everything went well\\ <code>root@openwrt:~# uci changes+  - now write **uci changes** to check if the setting configuration was loaded correctly. If you see the following on 22.03 and earlier (the **network.mng** entries MUST be the same as the ones shown here, the **network.wan** might be slightly different), everything went well\\ <code>root@openwrt:~# uci changes
 network.mng='interface' network.mng='interface'
 network.mng.type='bridge' network.mng.type='bridge'
Line 142: Line 170:
 -network.lan -network.lan
 -network.wan6 -network.wan6
-network.wan='interface'</code>+network.wan='interface'</code> For 23.03 and later, you should see\\ <code>root@OpenWrt:~# uci changes 
 +firewall.cfg02dc81.network='mng' 
 +firewall.cfg02dc81.name='mng' 
 +network.mng='interface' 
 +network.mng.device='br-lan' 
 +network.mng.proto='static' 
 +network.mng.ipaddr='192.168.56.2' 
 +network.mng.netmask='255.255.255.0' 
 +-network.lan 
 +-network.wan6 
 +</code>
   - if all is well, save config with **uci commit && reboot**, if all is NOT well, write **reboot** to erase the temporary changes and find a way to set the above configuration manually.   - if all is well, save config with **uci commit && reboot**, if all is NOT well, write **reboot** to erase the temporary changes and find a way to set the above configuration manually.
   - close and open again the SSH terminal when the VM has restarted, with same connection parameters (user **root** and **192.168.56.2**)   - close and open again the SSH terminal when the VM has restarted, with same connection parameters (user **root** and **192.168.56.2**)
   - now you should have both internet access (try a **opkg update**) AND a management interface with a static address you can connect your SSH client program to even if your PC is disconnected from a local network.   - now you should have both internet access (try a **opkg update**) AND a management interface with a static address you can connect your SSH client program to even if your PC is disconnected from a local network.
-  - the optional **Bridged Adapter** on **Adapter 3** isn't crucial for basic functionality and is also specific for your own local network parameters. In my own network (and in most home networks) it will work fine if you write <code>uci batch <<EOF +  - the optional **Bridged Adapter** on **Adapter 3** isn't crucial for basic functionality and is also specific for your own local network parameters. In my own network (and in most home networks) it will work fine for 22.03 and earlier if you write <code>uci batch <<EOF 
 set network.lan=interface set network.lan=interface
 set network.lan.ifname='eth2' set network.lan.ifname='eth2'
 set network.lan.proto='dhcp' set network.lan.proto='dhcp'
 EOF EOF
-uci commit</code>\\ If you have more complex requirements you will have to set that up on your own by reading the documentation, or through luci.+uci commit</code>and for 23.05 and later <code>uci batch <<EOF  
 +set network.lan=interface 
 +set network.lan.device='eth2' 
 +set network.lan.proto='dhcp' 
 +EOF 
 +uci commit 
 +service network restart 
 +</code>\\ If you have more complex requirements you will have to set that up on your own by reading the documentation, or through luci.
   - you can now install packages to this images as normal, you will probably want to install luci, write **opkg update && opkg install luci**, then you can connect to the VM's luci by typing 192.168.56.2 in your browser address bar or [[http://192.168.56.2|click on this link]] to get there.   - you can now install packages to this images as normal, you will probably want to install luci, write **opkg update && opkg install luci**, then you can connect to the VM's luci by typing 192.168.56.2 in your browser address bar or [[http://192.168.56.2|click on this link]] to get there.
- 
  
 ===== Troubleshooting ===== ===== Troubleshooting =====
   * If you rebuild the disk image, and VirtualBox complains about invalid UUIDs for the disk   * If you rebuild the disk image, and VirtualBox complains about invalid UUIDs for the disk
-    * You need to remove the disk from **both** the VM **and also** from the //Virtual Media Manager//+    * You need to remove the disk from **both** the //VM// **and** from the //Virtual Media Manager//
     * Then add the disk image to the VM again     * Then add the disk image to the VM again
  
Line 169: Line 213:
       * **Allow All** if you want to connect your bridged virtual network to your physical network       * **Allow All** if you want to connect your bridged virtual network to your physical network
  
- +===== Run with VirtualBox automatically on Start of Windows OS =====
-===== Run with Virtual Box automatically on Start of Windows OS ===== +
   * Ordered List ItemImport the following entry to your registry or add it manually:   * Ordered List ItemImport the following entry to your registry or add it manually:
     - [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run]     - [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run]
     - "VB-MYDEVICE"="\"C:\\Program Files\\Oracle\\VirtualBox\\VBoxManage.exe\" startvm \"NAMEOFVBINSTANCE\" --type headless"     - "VB-MYDEVICE"="\"C:\\Program Files\\Oracle\\VirtualBox\\VBoxManage.exe\" startvm \"NAMEOFVBINSTANCE\" --type headless"
  
-  * Alternative create 2 shortcuts and use the Windows Task sheduler+  * Alternatively create 2 shortcuts and use the Windows Task scheduler
     - "C:\Program Files\Oracle\VirtualBox\VBoxManage.exe" startvm MYDEVICE --type headless     - "C:\Program Files\Oracle\VirtualBox\VBoxManage.exe" startvm MYDEVICE --type headless
       - Create a task in the Scheduler triggered by logon of any user as action the shortcut       - Create a task in the Scheduler triggered by logon of any user as action the shortcut
Line 187: Line 229:
      
   * Or use following:   * Or use following:
-       - VB Service: https://sourceforge.net/projects/vboxvmservice/+       - [[https://github.com/onlyfang/VBoxVmService|VBoxVmService]] Windows Service to run VirtualBox VMs automatically
  
 +===== See also =====
 +  * [[docs:guide-user:virtualization:virtualbox-advanced|VirtualBox Advanced]]
 +  * [[docs:guide-user:virtualization:start|Other virtualization options]]: Docker, VMware etc.
  
  • Last modified: 2018/12/21 19:38
  • by jeff