INSTALL.md

Installation

This installation based on GNS3 Installation for linux.

If you use GNS3 VM or need to connect a remote server, use install remote document for setup remote server.

Requirement

• Linux (Ubuntu 20.04, Debian 10 or other supported linux)
• GNS3
• Docker
• Cisco router image

Install tools

We prefer to use pre-build VM from GNS3 github. Also, you can use last long term support (LTS) branch of Ubuntu or Debian linux to setup GNS3.

Client & Server (pre-build VM)

You can setup your desktop connect to remote server. Pre-build VMs can downloaded from this url. Download local executable (.exe or .dmg) and the VM image according to your hypervisor and install it.

Don't need to install full GNS3 client. You can disable local server package (WebClient, VM (download manually), WinPCAP (for windows 10), NPcap (for os before windows 10), Dynamips, QEMU, VPCS, CPU-limit). Also you can don't install SolarWind terminal package (in Windows OS) and use putty terminal instated.

Setup remote server

After download and boot your remote-server, you need setup your local GNS3 as client of the remote-server (maybe you need change the VM network config into bridge). For do this, got into Preferences > Server > Main server and then disable local server. In the new panel, set remote Host=displayed-ip, Port=80 and disable Auth.

After setup the remote-server on your client, you need download docker images in server shell (Get docker images). All the other setup, can do in client GUI like local GNS3 (Setup GNS3).

Ubuntu (18.04, 20.04, 20.10, 21.04)

You can install all needed tools with bellow commands on Ubuntu x64 based linux:

# echo "deb http://ppa.launchpad.net/gns3/ppa/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/gns3-ubuntu.list
sudo add-apt-repository ppa:gns3/ppa
sudo apt update
sudo apt install gns3-gui gns3-server wireshark

## To install preview of gns3 webclient, uncomment this line
# sudo apt install gns3-webclient-pack

## to install open source edition of docker use "Free"
## else use "CE" to install community edition of docker
DockerType="Free" # "CE"
if [ $DockerType == "Free" ]; then
  sudo apt install docker.io
else
  sudo apt remove docker docker-engine docker.io
  sudo apt-get install apt-transport-https ca-certificates curl software-properties-common
  curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
  sudo add-apt-repository \
  "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
  sudo apt update
  sudo apt install docker-ce
fi

verify installation:

sudo docker run hello-world

adding your user to the “docker” group:

for i in ubridge libvirt kvm docker wireshark; do
 sudo usermod -aG $i $USER
done
# loading new user group config
sudo su $USER

Debian 10

sudo apt update
sudo apt install -y python3-pip python3-pyqt5 python3-pyqt5.qtsvg \
python3-pyqt5.qtwebsockets \
qemu qemu-kvm qemu-utils libvirt-clients libvirt-daemon-system virtinst \
wireshark xtightvncviewer apt-transport-https \
ca-certificates curl gnupg2 software-properties-common

sudo pip3 install gns3-server
sudo pip3 install gns3-gui
# if install with user pip3, it will be installed into "$HOME/.local/bin"
# add 'export PATH="$HOME/.local/bin:$PATH"' into end of .bashrc

echo "deb http://ppa.launchpad.net/gns3/ppa/ubuntu focal main" | sudo tee /etc/apt/sources.list.d/gns3.list
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys F88F6D313016330404F710FC9A2FD067A2E3EF7B

sudo apt-get update
sudo apt install dynamips ubridge

## to install open source edition of docker use "Free"
## else use "CE" to install community edition of docker
DockerType="Free" # "CE"
if [ $DockerType == "Free" ]; then
  sudo apt install docker.io
else
  sudo apt remove docker docker-engine docker.io
  sudo apt-get install apt-transport-https ca-certificates curl software-properties-common
  curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
  sudo add-apt-repository \
  "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable"
  sudo apt update
  sudo apt install docker-ce
fi

verify installation:

sudo docker run hello-world

adding your user to the “docker” group:

for i in ubridge libvirt kvm docker wireshark sudo; do
 sudo usermod -aG $i $USER
done
# loading new user group config
sudo su $USER

Ubuntu Distribution Upgrade

If you upgrade your ubuntu distribution, you need to remove old GNS3 repository and add again.

sudo rm /etc/apt/sources.list.d/gns3*
sudo add-apt-repository ppa:gns3/ppa
sudo apt-get update
sudo apt-get -y -u dist-upgrade

Commented

Reference [1] : https://docs.docker.com/install/linux/docker-ce/ubuntu/#supported-storage-drivers

Get docker images

After install docker, you need to get utnetlab images and add into GNS3.

docker pull utnetlab/term
docker pull utnetlab/gui

Also you can pull this images from github package section. But you need to add docker tag.

# may be need login to github:
# https://docs.github.com/en/packages/guides/configuring-docker-for-use-with-github-packages
docker pull docker.pkg.github.com/hpnl/docker-tools/term:latest
docker tag docker.pkg.github.com/hpnl/docker-tools/term:latest utnetlab/term:latest
docker pull docker.pkg.github.com/hpnl/docker-tools/gui:latest
docker tag docker.pkg.github.com/hpnl/docker-tools/gui:latest utnetlab/gui:latest

Get from proxy

If you need to use proxy, you can use one of the following way. You can replace the dockerhub.ir with any proxy host.

Set in docker deamon file

echo '{
  "registry-mirrors": ["https://dockerhub.ir"]
}' | sudo tee /etc/docker/daemon.json
sudo systemctl restart docker

Pull from proxy

docker pull dockerhub.ir/utnetlab/term:latest
docker tag dockerhub.ir/utnetlab/term:latest utnetlab/term:latest
docker pull dockerhub.ir/utnetlab/gui:latest
docker tag dockerhub.ir/utnetlab/gui:latest utnetlab/gui:latest

Setup GNS3

To load template Figures you need to add Cisco 3725 firmware and utnetlab docker images into GNS3. In this section we configure and setup base hosts and router images.

Docker images

To add Docker images, you need to open Preferences menu (under Edit in Linux/Windows and GNS3 in Mac OS).

Under Docker > Docker containers you can add new images to GNS3.

In the New dialog, you can select existing image (load local images) or new image (use docker pull) with image name.

Set image name like utnetlab-gui.

Set adaptor count to 1.

Not need to set start command. But can set for custom start command (like add to start service at docker startup).

Set console type for your image.

• telnet for command line environments
• vnc for GUI image output (has a but and random disconnect (need to restart host))
• http & https for web based service

We made new docker image utnetlab/gui to bypass vnc bug and see vnc output on http or https port. In this case, after select https type, you need edit http port and set to 443.

If need custom environments variable for your image, set variables in this page, else left it empty.

Edit the utnetlab-gui item and set HTTP port in the container from 80 into 443.

Set configuration as below for two docker (use value according to key at each setup dialog).

GUI:

{
  image: "utnetlab/gui",
  name: "utnetlab-gui",
  adaptor: 1,
  startCommand: null, // or empty
  ConsoleType: "https",
  env: null // or empty
}

For terminal image (utnetlab/term) select telnet for ConsoleType and not need to change http port value.

Terminal:

{
  image: "utnetlab/term",
  name: "utnetlab-term",
  adaptor: 1, // number of eth adaptor
  startCommand: null, // or empty
  ConsoleType: "telnet",
  env: null // or empty
}

Cisco images

To load Cisco images into GNS3, you need got into Preferences > Dynamips > IOS routers and add new images.

Select file in Browse dialog and click on next.

Set name to c3725 for new router.

Under Memory section, set Default RAM to 144 MB at minimum (prefer set to 160/192 MB for correct NAT setup).

Skip slots step until get Idle-PC step.

Click on Idle-PC finder to find local idle-PC number if it was empty and then press Finish. (Default value for idle-PC is 0x602467a4)