How to set up the UNetLab or EVE-NG network emulator on a Linux system

February 6, 2017 — 4 Comments

EVE-NG and UNetLab are graphical network emulators that support both commercial and open-source router images. UNetLab is the current, stable version of the network emulator and EVE-NG is an updated version of the same tool, available as an alpha release. The UNetLab/EVE-NG network emulator runs in a virtual machine so it can be set up Windows, Mac OS, or Linux computers. Its graphical user interface runs in a web browser.

Since it runs in a virtual machine, EVE-NG may be set up on any operating system such as Windows, Linux, or Mac OS. When using the EVE-NG virtual machine on a Linux computer, I had to resolve a few problems related to the way VMware Player works in Linux. In this post, I focus only on the specific issues related to getting EVE-NG working on a Linux system. I’ll also show the basic steps to creating and running a simple lab consisting of emulated Linux nodes. The procedure is the same for UNetLab.

For users of other operating systems, the EVE-NG development team provides good information on setting it up on Windows (Setup, Integration) or Mac OS (Setup,Intergration).

The steps requires to set up the EVE-NG (or UNetLab) virtual machine on a Linux host computer are:

  1. Set up Telnet, VNC, and Wireshark to work with EVE-NG
  2. Download and install VMware Player
  3. Download the EVE-NG virtual machine
  4. Set up the EVE-NG VM in VMware Player
  5. Modify the permissions of the VMware virtual interfaces on the Linux host computer
  6. Start the EVE-NG VM for the first time and run through the automatic setup script
  7. Modify the EVE-NG VM’s network interfaces configuration file and restart the VM
  8. Add to the EVE-NG VM the images you will use to emulate network nodes
  9. Test EVE-NG with a simple network emulation scenario

EVE-NG Overview

EVE-NG is a clientless network emulator that provides a user interface via a browser. Users may create network nodes from a library of templates, connect them together, and configure them. Advanced users or administrators may add software images to the library and build custom templates to support almost any network scenario.

EVE-NG supports pre-configured multiple hypervisors on one virtual machine. It runs commercial network device software on Dynamips and IOU and runs other network devices, such as open-source routers, on QEMU.

EVE-NG is an open-source project and the EVE-NG source code is posted on GitLab. At the time this post was written, the EVE-NG developers are raising funds to support ongoing EVE-NG network emulator development. They are also developing an EVE-Cloud hosted solution that (I assume) will allow users to pay for access in exchange for a hosted solution on a remote cloud server.

Since it runs in a virtual machine, EVE-NG may be set up on any operating system such as Windows, Linux, or Mac OS. In this post, I focus only on the specific issues related to getting EVE-NG working on a Linux system. For users of other operating systems, the EVE-NG development team provides good information on setting it up on Windows (Setup, Integration) or Mac OS (Setup,Intergration).

Why EVE-NG instead of UNetLab?

EVE-NG is the new version of UNetLab. In addition to updating and re-working the software, the developers changed the project’s name.

At the time I wrote this post, UNetLab and EVE-NG are still very similar. However, the developers have stopped developing UNetLab. Any problems found in UNetLab will be only fixed in EVE-NG. Any changes made to the EVE-NG user interface and any new EVE-NG features will not be back-ported to UNetLab.

So, I decided to start my work with the UNetLab/EVE-NG network emulator by using the latest version, EVE-NG, even if it is still in alpha.

Set up Telnet, VNC, and Wireshark

When you click on nodes in the EVE-NG user interface, the browser will try to open a terminal window or a VNC window to connect to the node, or may run Wireshark to capture network traffic from one of the node’s interfaces. We need to set up the browser to use the custom protocol handlers used by EVE-NG, such as “telnet://* and capture://, so it can launch these programs with the correct parameters to support requests from the EVE-NG virtual machine.

As a first step, we will install applications that EVE-NG uses when interacting with nodes and we will integrate new protocol handlers into the Internet browser. In this case, I am using Firefox but this procedure should support other browsers, also.

This can be done manually by editing the protocol handlers in the browser’s configuration files but the easiest way is to use the UNetLab X Integration script created by Sergei Eremenko. Sergei’s script is available on GitHub.

To install the script, execute the following commands in a terminal window on your Linux computer:

$ wget -qO- https://raw.githubusercontent.com/SmartFinn/unetlab-x-integration/master/install.sh | sh
$ sudo usermod -a -G wireshark $USER

The script installs telnet, wireshark, and a VNC viewer. It also configures the new protocol handlers.

Log out and back in again to make your changes take effect.

Install VMware Workstation Player on Ubuntu Linux

EVE-NG runs KVM/QEMU virtual machines inside a another virtual machine running on our host computer. This nested virtualization setup is not supported by VirtualBox — my usual VM manager. So I used VMware Player, the solution recommended by the EVE-NG developers.

Download the latest version of VMware Workstation Player from the following URL: http://www.vmware.com/go/tryworkstation-linux-64. In this example, we download the file VMware-Player-12.5.1-4542065.x86_64.bundle.

Make the file executable, then run the file to install VMware.

$ cd ~/Downloads
$ chmod +x VMware-Player-12.5.1-4542065.x86_64.bundle
$ ./VMware-Player-12.5.1-4542065.x86_64.bundle

The VMware install wizard will start. Accept the license terms and follow the prompts to install VMware.

When you get to the license window, select the button that you agree to use VMware Player for only non-commercial use.

Follow the prompts until the VMware installation is completed. Start VMware player from your application launcher or enter the following command in the terminal:

$ vmplayer &

The VMware player window opens up. We can now download and import the EVE-NG virtual machine in VMware Player.

Download the EVE-NG virtual machine

Download the EVE-NG OVA file from the EVE-NG Downloads page. In this case, we downloaded the file EVE-ALFA.ova. It is over one Gigabyte in size so it may take a long time to download.

The EVE-NG virtual machine image is hosted in two locations: a server in Russia and on the MEGA download site. I’m not sure about the security issues related to either site but I downloaded EVE-NG from the mail.ru server in Russia and I did not experience any problems afterward.

Set up EVE-NG VM in VMware Player

Next, Create a new virtual machine in VMware Player. Click on the Open a Virtual Machine button in the player window.

A file browser window will appear. Navigate to the folder containing the EVE-NG OVA file, select the file and click on the Open button.

This opens the Import Virtual Machine window. Give the virtual machine a name and click the Import button.

VMware Player will import the EVE-NG appliance and it will appear in the player window.

Next, click on the Edit virtual machine settings button at the bottom of the window.

Set up the virtual hardware. In the VMware Player settings window, make the following changes:

  • Memory
    • Set the VM memory size to 4GB
  • Processors
    • Check the Virtualize Intel VT-x/EPT or AMD-V/RVI box to enable nested virtualization
    • set the number of processors to match the number of physical cores in your system. In my case, I have a dual-core Intel Core i5 processor so I set the value to “2”.
  • Network Adapters
    • Configure the first network adapter as “NAT”. This is the interface used by the EVE-NG VM to connect to the Internet.
    • Configure the remaining network adapters as needed. I recommend setting them also as “NAT” because we won’t be using these and NAT is a safe configuration choice that makes them still useful for connecting EVE-NG nodes to the Internet via separate interfaces.

The VMware virtual machine settings should look similar to the screenshot below:

Now your VM is configured. Click the Save button to complete the setup process.

Configure VMware Interfaces

So that nested virtual machines running inside a VMware virtual machine can communicate with external networks, change the permissions of the VMware virtual interfaces so that any user running VMware Player can access them.

First find the vmnet devices on your host computer. These will have been set up when you installed VMware Player, or when you create a virtual machine in VMware player that uses these interfaces. To see all available vmnet devices, execute the commands:

t420:~$ cd /dev
t420:~$ ls -l | grep vmnet
crw-------  1 root root      119,   0 Feb 28 10:46 vmnet0
crw-------  1 root root      119,   1 Feb 28 10:46 vmnet1
crw-------  1 root root      119,   8 Feb 28 10:46 vmnet8

We see from the command output that there are three vmnet devices and that all are accessible by only the root user. Change the devices’ permissions so that all users may access them. Execute the following commands. If you found a different list of vmnet devices when you listed them, adapt your commands to match the devices on your computer:

t420:~$ sudo chmod a+rw /dev/vmnet0
t420:~$ sudo chmod a+rw /dev/vmnet1
t420:~$ sudo chmod a+rw /dev/vmnet8

NOTE: It is important to configure the VMware Player’s network device permissions before you start the EVE-NG VM. If you already have started the EVE-NG VM, then configure the device permissions as shown above, shut down the EVE-NG VM, and then start the EVE-NG VM in VMware. A restart will not work. You need to shut down the VM completely first, then start it again.

To make permanent changes so you do not need to modify the vmnet device permissions every time you start your computer, you may modify the VMware service script1

Start EVE-NG VM for the first time

Start the EVE-NG virtual Machine in VMware Player. The VMware Player console will show the EVE-NG login prompt. The default root password is displayed above the login prompt.

In the VMware Player console window, log into the EVE-NG virtual machine using root password displayed on the screen. In this case, the userid is root and the password is eve.

Next, enter in the information requested by the EVE-NG setup script. First, you need to create a new root password. You’ll need to also enter it a second time to confirm it.

Choose a hostname for the EVE-NG VM. I chose eve-ng.

Set the DNS domain name for the EVE-NG VM. I chose to use eve.lab.

The EVE-NG developers recommend using a static IP address for the EVE-NG machine2. Choose Static in the screen that asks whether we will use DHCP or a static IP address:


Choose an IP address. I recommend using an IP address that is inside the same subnet as the IP address range supported by the VMware Player DHCP server. The VMware Player installed on my Linux computer uses the subnet 172.16.66.0/24 for its DHCP server. This range may be different on other operating systems.

The DHCP server’s address range cannot be changed in VMware Player. You would need to upgrade to VMware Workstation to get the ability to configure the DHCP server.

Also, I noticed that the VMware Player DHCP server assigns addresses starting in the middle of the subnet, 172.16.66.128 and higher. This means that, if I manually assign a static IP address that is lower than 172.16.66.128, I should be able to avoid IP address conflicts.

I chose to use the static IP address 172.16.66.120.

Configure the subnet mask, which is 255.255.255.0.

Enter the IP address of the default network gateway. In this case, VMware assigns the IP address of 172.16.66.2 to its gateway — since it already assigns 172.16.66.1 to a virtual interface to the host computer. So, enter 172.16.66.2 in this field:

Enter the primary DNS server IP address. This is the same as the default gateway IP address: 172.16.66.2.

Enter the secondary DNS server IP address. You may leave this blank or enter something like Google’s DNS server address, 8.8.8.8.

You may leave the NTP address blank. I did.

Choose the appropriate value for the method the VM will use to connect to the Internet. In some cases you may need to configure a proxy. In my case, I chose Direct connection.

The EVE-NG setup script will complete and the VM will now start. First, you’ll see the EVE-NG splash screen. This appears every time you start EVE-NG.

Then the VMware Player console will show the EVE-NG login prompt. Again, look at the IP address displayed above the login prompt. It should show 172.16.66.120 because we set that as the static IP address. Use this address to connect to the VM via SSH and HTTP.

I use a terminal window to connect to the EVE-NG VM because the VMware Player console does not support copy-and-paste, or other useful terminal functions. To connect to the EVE-NG virtual machine, Use the ssh command and connect to the root account at the IP address displayed in the VMware console window.

In my case, the command would be:

$ ssh root@172.16.66.120

Then log in with the root password you defined when you started EVE-NG for the first time. Now we are logged into the EVE-NG VM on a terminal window. We’ll use this terminal window to set up images and make configuration changes in EVE-NG.

The next step is to update EVE-NG to the latest version. To update EVE-NG, run the following commands in the EVE-NG terminal window:

# apt-get update
# apt-get upgrade

After upgrading, connect to the EVE-NG graphical user interface using a browser. I used Firefox. I started Firefox and entered the IP address that appears in the EVE-NG console window: http://172.16.66.120.

The default userid for the graphical user interface is admin. The password is unl.

  • Userid = admin
  • Password = unl

Now the EVE-NG graphical user interface appears. Congratulations! you have set up the EVE-NG virtual machine on a Linux system.

In the rest of this post, we will verify that EVE-NG works with open-source images by adding a Linux image and creating a simple network topology with the new image. I’ll also demonstrate that the Firefox browser can open the protocol handlers launched by EVE-NG to open VNC connections to the Linux nodes and to open Wireshark to capture network traffic.

Add images to EVE-NG

EVE-NG does not come with images already provided. Users must find software images to support the nodes that will run in the EVE-NG network emulation scenario they wish to create. Users must download images to directories on the EVE-NG virtual machine.

EVE-NG comes with templates configured to support various commercial routers and network appliances and also provides templates for a few open-source alternatives such as VyOS and Linux. Templates are stored in the folder /opt/unetlab/html/templates/. The default Linux template provided by EVE-NG supports Linux nodes as simple end-points on a network to emulate users or edge devices, specifies a Linux system that boots from a CDROM or DVD image (an ISO file), and uses VNC to connect.

To keep this post at a reasonable length, I will discuss how EVE-NG can support full-featured Linux nodes with persistent file systems in a future post. For now, we’ll use the default Linux template and download a Linux ISO file that is compatible with it. In this case, I chose to use Puppy Linux.

First, create the directory in which you will store the image. Each image is stored in a sub-directory of the /opt/unetlab/addons/qemu/ directory. EVE-NG requires the name of the directory is in a specific format: the image’s directory name must have a prefix that matches the template name, followed by some additional text chosen by the user to uniquely identify the image.

For example, each image compatible with the “Linux” template must be stored in its own directory and the directory name must start with “linux-“. The dash is important. The unique text that completes the directory name must follow the dash. In my case, I named the directory “linux-puppy”.

In the EVE-NG terminal window, enter the following command:

# mkdir -p /opt/unetlab/addons/qemu/linux-puppy

Next, go to that directory and download the Puppy Linux ISO:

# cd /opt/unetlab/addons/qemu/linux-puppy
# wget http://distro.ibiblio.org/puppylinux/puppy-tahr/iso/tahrpup64-6.0.5/tahr64-6.0.5.iso

Change the name of the file to cdrom.iso. EVE-NG expects that every ISO image will be named cdrom.iso.

# mv tahr64-6.0.5.iso cdrom.iso

Finally, ensure that permissions are set up correctly. EVE-NG provides a script to fix any permission problems. You should run this whenever you add a new image:

# /opt/unetlab/wrappers/unl_wrapper -a fixpermissions

Now the image is set up and we can use it in EVE-NG.

Create a new project

Now that we have an image prepared to use in EVE-NG, go back to the browser window displaying the EVE-NG user interface.

First, I will create a new folder. This is optional and you may create labs in the root directory if you want to.

The EVE-NG user interface main window displays a file manager. To create a new folder, enter the new folder name in the text box and click on the green Add folder button. In this example, I am creating a folder named brian.

We see the new folder in the EVE-NG user interface. Open the folder by double-clicking on it. Next, select the Add new Lab icon from the tool bar:

A dialog box will open requesting information about the lab. Here you must enter the lab name and the version. Other optional fields are available, such as the Description field, so you can provide information to future users who may open this lab file.

Click on the Save button to create the lab file. You will see the lab file appear in the EVE-NG window. Click on the file to see a thumbnail image of the lab topology — which is just a blank page right now — and the lab description if you populated that field in the lab configuration.

Below the lab thumbnail and description is a set of buttons that allow a user to manage the lab. You may open the lab, edit the lab information, or delete the lab file.

Click on the Open button. The EVE-NG network topology will appear. Currently, we have nothing configured in the topology so it is blank. We use the toolbar on the left to create and manage elements of the lab topology.

To add a new node, click on the Add an object tool — the “plus” sign at the top of the tool bar — and then select Node from the menu that appears.

Move the node to your preferred location in the window and then click to configure it. The Add a New Node dialog box appears. You may select the template you wish to use. Scroll down and select the Linux tempate.

The template form appears. Here we can add details about the nodes we will create. In this case, we chose the linux_puppy image we added earlier and reduced the RAM to 512 MB. We also set the Number of nodes to add field value to “2”. This will create two nodes at the same time.

After clicking on Save, two nodes appear on the EVE-NG canvas. Notice that each one uses the name configured in the previous form with a number appended to it. Arrange the nodes as shown below.

Add a link between both nodes. Use the Connect node tool from the toolbar.

The Connect node tool will now be colored red. Now click on each node and select the interfaces that will be connected together. For example: we click on the node named Linux1 and delect interface e0.

Then we click on the node named Linux2 and select interface e0.

Now we have a connection between the two nodes.

Click on the Connect node tool again to de-select it. It will turn gray again.

To start the network emulation scenario, click on the More actions tool and select Start all nodes.

The little square symbol (the “stop” icon) beside each node’s name should change to a sideways triangle (the “play” icon). Now both nodes are running — but it may take a few more seconds for them to complete their boot processes.

Connect to nodes

Now that the two Linux nodes are running, we need to connect to the user interface on each one so we can configure it and execute commands.

To connect to a node, click on it in the EVE-NG window. A new window opens that asks you which application should connect to the node. Choose the Remote Desktop Viewer, which will open the VNC application.

A VNC window will appear that displays the desktop on the node. Click on the other node to view its desktop, also. Now you can run applications on each node.

However, there is a problem. The mouse pointer in the VNC viewer does not track exactly with the mouse inputs from the host computer. This makes it difficult to click on icons or toolbars in the Puppy Linux desktop on either node.

For example, in the screen shot above, you can see two mouse pointers. The VNC mouse pointer does not track host mouse pointer. I could not find a fix for this issue but it seems to be a known problem.

One workaround is to reduce the size of the desktop in the VNC window. The smaller desktop makes it easier to match the mouse in the VNC window with the mouse input from the host computer. To do this, launch the terminal window on the Puppy Linux desktop of each node.

It may be difficult to click on the Console icon because the mouse will not cooperate. You may also open a terminal window in Puppy Linux by right-clicking anywhere on the desktop and selecting Utility –> Urxvt terminal emulator from the menu.

In the terminal window on each node, enter the following command:

# xrandr -s 800x600

Now the desktop is much smaller and you can realign the mouse pointer by moving off the edge of the screen. This does not solve the mouse pointer issue but it does make it easier to work with it.

Capture data

To launch Wireshark and capture data on the network interfaces in the EVE-NG emulation scenario, right-click on a node and then select the interface from which you wish to capture data.

A new window will appear asking you which application should be used. Select UNetLab-X-Integration.

An OpenSSH window appears and asks for the EVE-NG VM’s root password. Enter the root password you configured previously in the section titled Start EVE-NG VM for the first time.

Now go back to the VNC viewer and enter the following commands in the terminal window in each node.

On Linux1:

# ip addr add 192.168.1.100/24 dev eth0 broadcast 192.168.1.255
# ip link set eth0 up

On Linux2:

# ip addr add 192.168.1.101/24 dev eth0 broadcast 192.168.1.255
# ip link set eth0 up

From Linux2, ping Linux1. Execute the following command on Linux2:

# ping -c 1 192.168.1.100

Now you should see some packets appear in the Wireshark window, This simple scenario is not very interesting but it shows that packet capture is working.

Add a Cloud Interface

To make Cloud interfaces work correctly when the EVE-NG virtual machine is running on a Linux host computer, we previously changed the permissions on the VMware virtual interfaces and modified the EVE-NG VM’s network interfaces configuration file. Let’s test to see if everything works now.

In EVE-NG, a Cloud interface allows a network node to connect to a network external to the EVE-NG VM. Most of the time, you will use a Cloud interface to connect to the Internet so you may download software or other files to a node running in EVE-NG.

We’ve already configured the EVE-NG VM to connect to the Internet via the first VMware NAT interface, vmnet0, which is connected to a bridge, pnet0 on the EVE-NG VM. See the EVE-NG VM’s /etc/network/interfaces file to view the bridge configuration.

Add a new network

To create a cloud interface, create a new network that is connected to the bridge pnet0. First click on the Add an Object icon in the EVE-NG tool bar and select Network. In the Add a New Network configuration window, Give the network a name (or use the default name) and select pnet0 in the Type field. The click Save.

A new network appears as a cloud icon on the EVE-NG user interface.

In this example, since we will not configure any routes on the nodes, I will add a new Linux node and connect its’ interface e0 to the cloud interface Net. The network topology will appear as shown below:

Click on the new Linux node to open a VNC viewer and start a Terminal window on the Linux node. Ping Google’s DNS server to test the connection to the Internet:

$ ping -c 1 8.8.8.8

We should see that the ping comand is successful. Enter Ctrl-C to stop the command.

Show that we can install software on a node from remote repositories by running apt commands:

$ sudo apt-get update

Again, this command should complete successfully.

Now we know that we correctly configured VMware, the Linux Host computer, and the EVE-NG virtual machine so that Cloud interfaces work correctly. This means that any network node we create in future network topologies can, if also connected to a properly configured Cloud interface, download files and install software from remote repositories.

Stop lab

Now we are done testing the EVE-NG virtual machine. We will stop the lab and exit the virtual machine.

To stop the running nodes, click on the More actions tool in the toolbar and select Stop all nodes.

Next, close the lab by clicking on Close lab in the toolbar.

Now that we have some nodes configured in the lab, EVE-NG displays an image of the lab topology in the file manager window. This helps us quickly identify labs when we have more than one lab in the file manager.

Quit the EVE-NG user interface by click on the Sign out button.

Finally, in the EVE-NG terminal window, shut down the virtual machine by running the command:

# shutdown -h now

Conclusion

We downloaded the EVE-NG VM and set it up in VMware Player. We integrated the EVE-NG media handlers with the Firefox browser and we configured the Linux host computer, VMware Player, and the EVE-NG VM to ensure Cloud interfaces worked correctly. Then we demonstrated a very basic network topology using the QEMU hypervisor in EVE-NG.

To make further use of network nodes powered by open-source software in the EVE-NG network emulator, we need to explore more of EVE-NG’s features. We will create custom node templates and build images running open-source software in EVE-NG. Finally, we will use those images to create more complex network topologies. I will cover these topics is a future post.

As a lower-priority followup project, I am investigating how to set up and run EVE-NG on a Linux system using only QEMU/KVM instead of the commercial VMware Player application. As far as I know, QEMU/KVM should support the nested virtualization features that EVE-NG requires. I will try to create a fully open-source tool chain when working in EVE-NG with open-source routers and network appliances.


  1. Reference: forwardingflows.net

  2. Reference: https://www.youtube.com/watch?v=GyY4F9Hl67E 

4 responses to How to set up the UNetLab or EVE-NG network emulator on a Linux system

Trackbacks and Pingbacks:

  1. Build a custom Linux Router image for UNetLab and EVE-NG network emulators | Open-Source Routing and Network Simulation - March 8, 2017

    […] up the EVE-NG user interface in your browser. Remember, we set up the EVE-NG virtual machine on a Linux host computer in my previous […]

Leave a Reply

Text formatting is available via select HTML. <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

*