This chapter describes how to set up a CORE machine. Note that the easiest way to install CORE is using a binary package on Ubuntu or Fedora (deb or rpm) using the distribution’s package manager to automatically install dependencies, see Installing from Packages.
Ubuntu and Fedora Linux are the recommended distributions for running CORE. Ubuntu 12.04 or 12.10 and Fedora 17 or 18 ship with kernels with support for namespaces built-in. They support the latest hardware. However, these distributions are not strictly required. CORE will likely work on other flavors of Linux, see Installing from Source.
The primary dependencies are Tcl/Tk (8.5 or newer) for the GUI, and Python 2.6 or 2.7 for the CORE daemon.
CORE files are installed to the following directories. When installing from source, the /usr/local prefix is used in place of /usr by default.
| Install Path | Description |
|---|---|
| /usr/bin/core | GUI startup command |
| /usr/sbin/cored | Daemon startup command |
| /usr/sbin/ | Misc. helper commands/scripts |
| /usr/lib/core | GUI files |
| /usr/lib/python2.7/dist-packages/core | Python modules for daemon/scripts |
| /etc/core/ | Daemon configuration files |
| ~/.core/ | User-specific GUI preferences and scenario files |
| /usr/share/core/ | Example scripts and scenarios |
| /usr/share/man/man1/ | Command man pages |
| /etc/init.d/core | System startup script for daemon |
Under Fedora, /site-packages/ is used instead of /dist-packages/ for the Python modules, and /etc/systemd/system/core-emulator.service instead of /etc/init.d/core for the system startup script.
The Linux or FreeBSD operating system is required. The GUI uses the Tcl/Tk scripting toolkit, and the CORE daemon require Python. Details of the individual software packages required can be found in the installation steps.
Any computer capable of running Linux or FreeBSD should be able to run CORE. Since the physical machine will be hosting numerous virtual machines, as a general rule you should select a machine having as much RAM and CPU resources as possible.
A general recommendation would be:
The computer can be a laptop, desktop, or rack-mount server. A keyboard, mouse, and monitor are not required if a network connection is available for remotely accessing the machine. A 3D accelerated graphics card is not required.
CORE requires the Linux or FreeBSD operating systems because it uses virtualization provided by the kernel. It does not run on the Windows or Mac OS X operating systems (unless it is running within a virtual machine guest.) There are two different virtualization technologies that CORE can currently use: Linux network namespaces and FreeBSD jails, see How Does it Work? for virtualization details.
Linux network namespaces is the recommended platform. Development is focused here and it supports the latest features. It is the easiest to install because there is no need to patch, install, and run a special Linux kernel.
FreeBSD 9.0-RELEASE may offer the best scalability. If your applications run under FreeBSD and you are comfortable with that platform, this may be a good choice. Device and application support by BSD may not be as extensive as Linux.
The CORE GUI requires the X.Org X Window system (X11), or can run over a remote X11 session. For specific Tcl/Tk, Python, and other libraries required to run CORE, refer to the Installation section.
Note
CORE Services determine what runs on each node. You may require other software packages depending on the services you wish to use. For example, the HTTP service will require the apache2 package.
The easiest way to install CORE is using the pre-built packages. The package managers on Ubuntu or Fedora will automatically install dependencies for you. You can obtain the CORE packages from the CORE downloads page.
First install the Ubuntu 12.04 or 12.10 operating system.
Note
Linux package managers (e.g. software-center, yum) will take care of installing the dependencies for you when you use the CORE packages. You do not need to manually use these installation lines. You do need to select which Quagga package to use.
Optional: install the prerequisite packages (otherwise skip this step and have the package manager install them for you.)
# make sure the system is up to date; you can also use synaptic or # update-manager instead of apt-get update/dist-upgrade sudo apt-get update sudo apt-get dist-upgrade sudo apt-get install bash bridge-utils ebtables iproute libev-dev python tcl8.5 tk8.5 libtk-img
Install Quagga for routing. If you plan on working with wireless networks, we recommend installing OSPF MDR (replace amd64 below with i386 if needed to match your architecture):
export URL=http://downloads.pf.itd.nrl.navy.mil/ospf-manet wget $URL/quagga-0.99.21mr2.2/quagga-mr_0.99.21mr2.2_amd64.deb sudo dpkg -i quagga-mr_0.99.21mr2.2_amd64.deb
or, for the regular Ubuntu version of Quagga:
sudo apt-get install quagga
Install the CORE deb packages for Ubuntu, using a GUI that automatically resolves dependencies (note that the absolute path to the deb file must be used with software-center):
software-center /home/user/Downloads/core-daemon_4.5-0ubuntu1_precise_amd64.deb software-center /home/user/Downloads/core-gui_4.5-0ubuntu1_precise_all.deb
or install from command-line:
sudo dpkg -i core-daemon_4.5-0ubuntu1_precise_amd64.deb sudo dpkg -i core-gui_4.5-0ubuntu1_precise_all.deb
Start the CORE daemon as root.
sudo /etc/init.d/core start
Run the CORE GUI as a normal user:
core
After running the core command, a GUI should appear with a canvas for drawing topologies. Messages will print out on the console about connecting to the CORE daemon.
The commands shown here should be run as root. First Install the Fedora 17 or 18 or CentOS 6.x operating system. The x86_64 architecture is shown in the examples below, replace with i686 is using a 32-bit architecture. Also, fc15 is shown below for Fedora 15 packages, replace with the appropriate Fedora release number.
CentOS only: in order to install the libev prerequisite package, you first need to install the EPEL repo (Extra Packages for Enterprise Linux):
wget http://dl.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm
yum localinstall epel-release-6-8.noarch.rpm
Optional: install the prerequisite packages (otherwise skip this step and have the package manager install them for you.)
# make sure the system is up to date; you can also use the # update applet instead of yum update yum update yum install bash bridge-utils ebtables iproute libev python tcl tk tkimg
Optional (Fedora 17+): Fedora 17 and newer have an additional prerequisite providing the required netem kernel modules (otherwise skip this step and have the package manager install it for you.)
yum install kernel-modules-extra
Install Quagga for routing. If you plan on working with wireless networks, we recommend installing OSPF MDR:
export URL=http://downloads.pf.itd.nrl.navy.mil/ospf-manet wget $URL/quagga-0.99.21mr2.2/quagga-0.99.21mr2.2-1.fc16.x86_64.rpm yum localinstall quagga-0.99.21mr2.2-1.fc16.x86_64.rpm
or, for the regular Fedora version of Quagga:
yum install quagga
Install the CORE RPM packages for Fedora and automatically resolve dependencies:
yum localinstall core-daemon-4.5-1.fc18.x86_64.rpm --nogpgcheck yum localinstall core-gui-4.5-1.fc18.noarch.rpm --nogpgcheck
or install from the command-line:
rpm -ivh core-daemon-4.5-1.fc18.x86_64.rpm rpm -ivh core-gui-4.5-1.fc18.noarch.rpm
Turn off SELINUX by setting SELINUX=disabled in the /etc/sysconfig/selinux file, and adding selinux=0 to the kernel line in your /etc/grub.conf file; on Fedora 15 and newer, disable sandboxd using chkconfig sandbox off; you need to reboot in order for this change to take effect
Turn off firewalls with systemctl disable iptables.service, systemctl disable ip6tables.service (chkconfig iptables off, chkconfig ip6tables off) or configure them with permissive rules for CORE virtual networks; you need to reboot after making this change, or flush the firewall using iptables -F, ip6tables -F.
Start the CORE daemon as root. Fedora uses the systemd start-up daemon instead of traditional init scripts. CentOS uses the init script.
# for Fedora using systemd:
systemctl daemon-reload
systemctl start core-emulator.service
# or for CentOS:
/etc/init.d/core start
Run the CORE GUI as a normal user:
core
After running the core command, a GUI should appear with a canvas for drawing topologies. Messages will print out on the console about connecting to the CORE daemon.
This option is listed here for developers and advanced users who are comfortable patching and building source code. Please consider using the binary packages instead for a simplified install experience.
To build CORE from source on Ubuntu, first install these development packages. These packages are not required for normal binary package installs.
sudo apt-get install bash bridge-utils ebtables iproute libev-dev python \
tcl8.5 tk8.5 libtk-img \
autoconf automake gcc libev-dev make python-dev libreadline-dev pkg-config imagemagick help2man
You can obtain the CORE source from the CORE source page. Choose either a stable release version or the development snapshot available in the nightly_snapshots directory. The -j8 argument to make will run eight simultaneous jobs, to speed up builds on multi-core systems.
tar xzf core-4.5.tar.gz cd core-4.5 ./bootstrap.sh ./configure make -j8 sudo make install
The CORE Manual documentation is built separately from the doc/ sub-directory in the source. It requires Sphinx:
sudo apt-get install python-sphinx cd core-4.5/doc make html make latexpdf
To build CORE from source on Fedora, install these development packages. These packages are not required for normal binary package installs.
yum install bash bridge-utils ebtables iproute libev python \ tcl tk tkimg \ autoconf automake make libev-devel python-devel ImageMagick help2man
Note
For a minimal X11 installation, also try these packages:
yum install xauth xterm urw-fonts
You can obtain the CORE source from the CORE source page. Choose either a stable release version or the development snapshot available in the nightly_snapshots directory. The -j8 argument to make will run eight simultaneous jobs, to speed up builds on multi-core systems. Notice the configure flag to tell the build system that a systemd service file should be installed under Fedora.
tar xzf core-4.5.tar.gz cd core-4.5 ./bootstrap.sh ./configure --with-startup=systemd make -j8 sudo make install
Note that the Linux RPM and Debian packages do not use the /usr/local prefix, and files are instead installed to /usr/sbin, and /usr/lib. This difference is a result of aligning with the directory structure of Linux packaging systems and FreeBSD ports packaging.
Another note is that the Python distutils in Fedora Linux will install the CORE Python modules to /usr/lib/python2.7/site-packages/core, instead of using the dist-packages directory.
The CORE Manual documentation is built separately from the doc/ sub-directory in the source. It requires Sphinx:
sudo yum install python-sphinx cd core-4.5/doc make html make latexpdf
To build CORE from source on CentOS/EL6, first install the EPEL repo (Extra Packages for Enterprise Linux) in order to provide the libev package.
wget http://dl.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm
yum localinstall epel-release-6-8.noarch.rpm
Now use the same instructions shown in Installing from Source on Fedora. CentOS/EL6 does not use the systemd service file, so the configure option –with-startup=systemd should be omitted:
./configure
To build CORE from source on SUSE or OpenSUSE, use the similar instructions shown in Installing from Source on Fedora, except that the following configure option should be used:
./configure --with-startup=suse
This causes a separate init script to be installed that is tailored towards SUSE systems.
The zypper command is used instead of yum.
For OpenSUSE/Xen based installations, refer to the README-Xen file included in the CORE source.
Rebuilding the FreeBSD Kernel
The FreeBSD kernel requires a small patch to allow per-node directories in the filesystem. Also, the VIMAGE build option needs to be turned on to enable jail-based network stack virtualization. The source code for the FreeBSD kernel is located in /usr/src/sys.
Instructions below will use the /usr/src/sys/amd64 architecture directory, but the directory /usr/src/sys/i386 should be substituted if you are using a 32-bit architecture.
The kernel patch is available from the CORE source tarball under core-4.5/kernel/symlinks-8.1-RELEASE.diff. This patch applies to the FreeBSD 8.x or 9.x kernels.
cd /usr/src/sys # first you can check if the patch applies cleanly using the '-C' option patch -p1 -C < ~/core-4.5/kernel/symlinks-8.1-RELEASE.diff # without '-C' applies the patch patch -p1 < ~/core-4.5/kernel/symlinks-8.1-RELEASE.diff
A kernel configuration file named CORE can be found within the source tarball: core-4.5/kernel/freebsd8-config-CORE. The config is valid for FreeBSD 8.x or 9.x kernels.
The contents of this configuration file are shown below; you can edit it to suit your needs.
# this is the FreeBSD 9.x kernel configuration file for CORE
include GENERIC
ident CORE
options VIMAGE
nooptions SCTP
options IPSEC
device crypto
options IPFIREWALL
options IPFIREWALL_DEFAULT_TO_ACCEPT
The kernel configuration file can be linked or copied to the kernel source directory. Use it to configure and build the kernel:
cd /usr/src/sys/amd64/conf cp ~/core-4.5/kernel/freebsd8-config-CORE CORE config CORE cd ../compile/CORE make cleandepend && make depend make -j8 && make install
Change the number 8 above to match the number of CPU cores you have times two. Note that the make install step will move your existing kernel to /boot/kernel.old and removes that directory if it already exists. Reboot to enable this new patched kernel.
Building CORE from Source on FreeBSD
Here are the prerequisite packages from the FreeBSD ports system:
pkg_add -r tk85
pkg_add -r libimg
pkg_add -r bash
pkg_add -r libev
pkg_add -r sudo
pkg_add -r python
pkg_add -r autotools
pkg_add -r gmake
Note that if you are installing to a bare FreeBSD system and want to SSH with X11 forwarding to that system, these packages will help:
pkg_add -r xauth
pkg_add -r xorg-fonts
The sudo package needs to be configured so a normal user can run the CORE GUI using the command core (opening a shell window on a node uses a command such as sudo vimage n1.)
On FreeBSD, the CORE source is built using autotools and gmake:
tar xzf core-4.5.tar.gz cd core-4.5 ./bootstrap.sh ./configure gmake -j8 sudo gmake install
Build and install the vimage utility for controlling virtual images. The source can be obtained from FreeBSD SVN, or it is included with the CORE source for convenience:
cd core-4.5/kernel/vimage make make install
On FreeBSD you should also install the CORE kernel modules for wireless emulation. Perform this step after you have recompiled and installed FreeBSD kernel.
cd core-4.5/kernel/ng_pipe make sudo make install cd ../ng_wlan make sudo make install
The ng_wlan kernel module allows for the creation of WLAN nodes. This is a modified ng_hub Netgraph module. Instead of packets being copied to every connected node, the WLAN maintains a hash table of connected node pairs. Furthermore, link parameters can be specified for node pairs, in addition to the on/off connectivity. The parameters are tagged to each packet and sent to the connected ng_pipe module. The ng_pipe has been modified to read any tagged parameters and apply them instead of its default link effects.
The ng_wlan also supports linking together multiple WLANs across different machines using the ng_ksocket Netgraph node, for distributed emulation.
The Quagga routing suite is recommended for routing, Quagga Routing Software for installation.
Virtual networks generally require some form of routing in order to work (e.g. to automatically populate routing tables for routing packets from one subnet to another.) CORE builds OSPF routing protocol configurations by default when the blue router node type is used. The OSPF protocol is available from the Quagga open source routing suite. Other routing protocols are available using different node services, Default Services and Node Types.
Quagga is not specified as a dependency for the CORE packages because there are two different Quagga packages that you may use:
Quagga - the standard version of Quagga, suitable for static wired networks, and usually available via your distribution’s package manager. .. index:: OSPFv3 MANET
OSPF MANET Designated Routers (MDR) - the Quagga routing suite with a modified version of OSPFv3, optimized for use with mobile wireless networks. The mdr node type (and the MDR service) requires this variant of Quagga.
If you plan on working with wireless networks, we recommend installing OSPF MDR; otherwise install the standard version of Quagga using your package manager or from source.
To install the standard version of Quagga from packages, use your package manager (Linux) or the ports system (FreeBSD).
Ubuntu users:
sudo apt-get install quagga
Fedora users:
yum install quagga
FreeBSD users:
pkg_add -r quagga
To install the Quagga variant having OSPFv3 MDR, first download the appropriate package, and install using the package manager.
Ubuntu users:
export URL=http://downloads.pf.itd.nrl.navy.mil/ospf-manet wget $URL/quagga-0.99.21mr2.2/quagga-mr_0.99.21mr2.2_amd64.deb sudo dpkg -i quagga-mr_0.99.21mr2.2_amd64.deb
Replace amd64 with i686 if using a 32-bit architecture.
Fedora users:
export URL=http://downloads.pf.itd.nrl.navy.mil/ospf-manet wget $URL/quagga-0.99.21mr2.2/quagga-0.99.21mr2.2-1.fc16.x86_64.rpm yum localinstall quagga-0.99.21mr2.2-1.fc16.x86_64.rpm
Replace x86_64 with i686 if using a 32-bit architecture.
To compile Quagga to work with CORE on Linux:
tar xzf quagga-0.99.21mr2.2.tar.gz
cd quagga-0.99.21mr2.2
./configure --enable-user=root --enable-group=root --with-cflags=-ggdb \
--sysconfdir=/usr/local/etc/quagga --enable-vtysh \
--localstatedir=/var/run/quagga
make
sudo make install
Note that the configuration directory /usr/local/etc/quagga shown for Quagga above could be /etc/quagga, if you create a symbolic link from /etc/quagga/Quagga.conf -> /usr/local/etc/quagga/Quagga.conf on the host. The quaggaboot.sh script in a Linux network namespace will try and do this for you if needed.
If you try to run quagga after installing from source and get an error such as:
error while loading shared libraries libzebra.so.0
this is usually a sign that you have to run sudo ldconfig to refresh the cache file.
To compile Quagga to work with CORE on FreeBSD:
tar xzf quagga-0.99.21mr2.2.tar.gz
cd quagga-0.99.21mr2.2
./configure --enable-user=root --enable-group=wheel \
--sysconfdir=/usr/local/etc/quagga --enable-vtysh \
--localstatedir=/var/run/quagga
gmake
gmake install
On FreeBSD 9.0 you can use make or gmake. You probably want to compile Quagga from the ports system in /usr/ports/net/quagga.
CORE is capable of running inside of a virtual machine, using software such as VirtualBox, VMware Server or QEMU. However, CORE itself is performing machine virtualization in order to realize multiple emulated nodes, and running CORE virtually adds additional contention for the physical resources. For performance reasons, this is not recommended. Timing inside of a VM often has problems. If you do run CORE from within a VM, it is recommended that you view the GUI with remote X11 over SSH, so the virtual machine does not need to emulate the video card with the X11 application.
A CORE virtual machine is provided for download, named VCORE. This is the perhaps the easiest way to get CORE up and running as the machine is already set up for you. This may be adequate for initially evaluating the tool but keep in mind the performance limitations of running within VirtualBox or VMware. To install the virtual machine, you first need to obtain VirtualBox from http://www.virtualbox.org, or VMware Server or Player from http://www.vmware.com (this commercial software is distributed for free.) Once virtualization software has been installed, you can import the virtual machine appliance using the vbox file for VirtualBox or the vmx file for VMware. See the documentation that comes with VCORE for login information.