core-extra/docs/services.md

CORE Services

• Table of Contents {:toc}

Services

CORE uses the concept of services to specify what processes or scripts run on a node when it is started. Layer-3 nodes such as routers and PCs are defined by the services that they run.

Services may be customized for each node, or new custom services can be created. New node types can be created each having a different name, icon, and set of default services. Each service defines the per-node directories, configuration files, startup index, starting commands, validation commands, shutdown commands, and meta-data associated with a node.

NOTE: Network namespace nodes do not undergo the normal Linux boot process using the init, upstart, or systemd frameworks. These lightweight nodes use configured CORE services.

Default Services and Node Types

Here are the default node types and their services:

• router - zebra, OSFPv2, OSPFv3, and IPForward services for IGP link-state routing.
• host - DefaultRoute and SSH services, representing an SSH server having a default route when connected directly to a router.
• PC - DefaultRoute service for having a default route when connected directly to a router.
• mdr - zebra, OSPFv3MDR, and IPForward services for wireless-optimized MANET Designated Router routing.
• prouter - a physical router, having the same default services as the router node type; for incorporating Linux testbed machines into an emulation.

Configuration files can be automatically generated by each service. For example, CORE automatically generates routing protocol configuration for the router nodes in order to simplify the creation of virtual networks.

To change the services associated with a node, double-click on the node to invoke its configuration dialog and click on the Services... button, or right-click a node a choose Services... from the menu. Services are enabled or disabled by clicking on their names. The button next to each service name allows you to customize all aspects of this service for this node. For example, special route redistribution commands could be inserted in to the Quagga routing configuration associated with the zebra service.

To change the default services associated with a node type, use the Node Types dialog available from the Edit button at the end of the Layer-3 nodes toolbar, or choose Node types... from the Session menu. Note that any new services selected are not applied to existing nodes if the nodes have been customized.

The node types are saved in a ~/.core/nodes.conf file, not with the .imn file. Keep this in mind when changing the default services for existing node types; it may be better to simply create a new node type. It is recommended that you do not change the default built-in node types. The nodes.conf file can be copied between CORE machines to save your custom types.

Customizing a Service

A service can be fully customized for a particular node. From the node's configuration dialog, click on the button next to the service name to invoke the service customization dialog for that service. The dialog has three tabs for configuring the different aspects of the service: files, directories, and startup/shutdown.

NOTE: A yellow customize icon next to a service indicates that service requires customization (e.g. the Firewall service). A green customize icon indicates that a custom configuration exists. Click the Defaults button when customizing a service to remove any customizations.

The Files tab is used to display or edit the configuration files or scripts that are used for this service. Files can be selected from a drop-down list, and their contents are displayed in a text entry below. The file contents are generated by the CORE daemon based on the network topology that exists at the time the customization dialog is invoked.

The Directories tab shows the per-node directories for this service. For the default types, CORE nodes share the same filesystem tree, except for these per-node directories that are defined by the services. For example, the /var/run/quagga directory needs to be unique for each node running the Zebra service, because Quagga running on each node needs to write separate PID files to that directory.

NOTE: The /var/log and /var/run directories are mounted uniquely per-node by default. Per-node mount targets can be found in /tmp/pycore.nnnnn/nN.conf/ (where nnnnn is the session number and N is the node number.)

The Startup/shutdown tab lists commands that are used to start and stop this service. The startup index allows configuring when this service starts relative to the other services enabled for this node; a service with a lower startup index value is started before those with higher values. Because shell scripts generated by the Files tab will not have execute permissions set, the startup commands should include the shell name, with something like sh script.sh.

Shutdown commands optionally terminate the process(es) associated with this service. Generally they send a kill signal to the running process using the kill or killall commands. If the service does not terminate the running processes using a shutdown command, the processes will be killed when the vnoded daemon is terminated (with kill -9) and the namespace destroyed. It is a good practice to specify shutdown commands, which will allow for proper process termination, and for run-time control of stopping and restarting services.

Validate commands are executed following the startup commands. A validate command can execute a process or script that should return zero if the service has started successfully, and have a non-zero return value for services that have had a problem starting. For example, the pidof command will check if a process is running and return zero when found. When a validate command produces a non-zero return value, an exception is generated, which will cause an error to be displayed in the Check Emulation Light.

TIP: To start, stop, and restart services during run-time, right-click a node and use the Services... menu.

Creating new Services

Services can save time required to configure nodes, especially if a number of nodes require similar configuration procedures. New services can be introduced to automate tasks.

The easiest way to capture the configuration of a new process into a service is by using the UserDefined service. This is a blank service where any aspect may be customized. The UserDefined service is convenient for testing ideas for a service before adding a new service type.

To introduce new service types, a myservices/ directory exists in the user's CORE configuration directory, at ~/.core/myservices/. A detailed README.txt file exists in that directory to outline the steps necessary for adding a new service. First, you need to create a small Python file that defines the service; then the custom_services_dir entry must be set in the /etc/core/core.conf configuration file. A sample is provided in the myservices/ directory.

NOTE: The directory name used in custom_services_dir should be unique and should not correspond to any existing Python module name. For example, don't use the name subprocess or services.

If you have created a new service type that may be useful to others, please consider contributing it to the CORE project.

Here is an example service with documentation describing functionality: Example Service

Available Services

BIRD Internet Routing Daemon

The BIRD Internet Routing Daemon is a routing daemon; i.e., a software responsible for managing kernel packet forwarding tables. It aims to develop a dynamic IP routing daemon with full support of all modern routing protocols, easy to use configuration interface and powerful route filtering language, primarily targeted on (but not limited to) Linux and other UNIX-like systems and distributed under the GNU General Public License. BIRD has a free implementation of several well known and common routing and router-supplemental protocols, namely RIP, RIPng, OSPFv2, OSPFv3, BGP, BFD, and NDP/RA. BIRD supports IPv4 and IPv6 address families, Linux kernel and several BSD variants (tested on FreeBSD, NetBSD and OpenBSD). BIRD consists of bird daemon and birdc interactive CLI client used for supervision.

In order to be able to use the BIRD Internet Routing Protocol, you must first install the project on your machine.

BIRD Package Install

sudo apt-get install bird

BIRD Source Code Install

You can download BIRD source code from it's official repository.

./configure
make
su
make install
vi /etc/bird/bird.conf

The installation will place the bird directory inside /etc where you will also find its config file.

In order to be able to do use the Bird Internet Routing Protocol, you must modify bird.conf due to the fact that the given configuration file is not configured beyond allowing the bird daemon to start, which means that nothing else will happen if you run it. Keeran Marquis has a very detailed example on Configuring BGP using Bird on Ubuntu which can be used as a building block to implement your custom routing daemon.

FRRouting

FRRouting is a routing software package that provides TCP/IP based routing services with routing protocols support such as BGP, RIP, OSPF, IS-IS and more. FRR also supports special BGP Route Reflector and Route Server behavior. In addition to traditional IPv4 routing protocols, FRR also supports IPv6 routing protocols. With an SNMP daemon that supports the AgentX protocol, FRR provides routing protocol MIB read-only access (SNMP Support).

FRR currently supports the following protocols:

• BGP
• OSPFv2
• OSPFv3
• RIPv1
• RIPv2
• RIPng
• IS-IS
• PIM-SM/MSDP
• LDP
• BFD
• Babel
• PBR
• OpenFabric
• EIGRP (alpha)
• NHRP (alpha)

FRRouting Package Install

sudo apt install curl
curl -s https://deb.frrouting.org/frr/keys.asc | sudo apt-key add -
FRRVER="frr-stable"
echo deb https://deb.frrouting.org/frr $(lsb_release -s -c) $FRRVER | sudo tee -a /etc/apt/sources.list.d/frr.list
sudo apt update && sudo apt install frr frr-pythontools

FRRouting Source Code Install

Building FRR from source is the best way to ensure you have the latest features and bug fixes. Details for each supported platform, including dependency package listings, permissions, and other gotchas, are in the developer’s documentation.

FRR’s source is available on the project GitHub page.

git clone https://github.com/FRRouting/frr.git

Change into your FRR source directory and issue:

./bootstrap.sh

Then, choose the configuration options that you wish to use for the installation. You can find these options on FRR's official webpage. Once you have chosen your configure options, run the configure script and pass the options you chose:

./configure \
    --prefix=/usr \
    --enable-exampledir=/usr/share/doc/frr/examples/ \
    --localstatedir=/var/run/frr \
    --sbindir=/usr/lib/frr \
    --sysconfdir=/etc/frr \
    --enable-pimd \
    --enable-watchfrr \
    ...

After configuring the software, you are ready to build and install it in your system.

make && sudo make install

If everything finishes successfully, FRR should be installed.

Docker

Docker service allows running docker containers within CORE nodes. The running of Docker within a CORE node allows for additional extensibility to the CORE services. This allows network applications and protocols to be easily packaged and run on any node.

This service will add a new group to the services list. This will have a service called Docker which will just start the docker service within the node but not run anything. It will also scan all docker images on the host machine. If any are tagged with 'core' then they will be added as a service to the Docker group. The image will then be auto run if that service is selected.

This requires a recent version of Docker. This was tested using a PPA on Ubuntu with version 1.2.0. The version in the standard Ubuntu repo is to old for this purpose (we need --net host).

Docker Installation

To use Docker services, you must first install the Docker python image. This is used to interface with Docker from the python service.

sudo apt-get install docker.io
sudo apt-get install python-pip
pip install docker-py

Once everything runs successfully, a Docker group under services will appear. An example use case is to pull an image from Docker. A test image has been uploaded for this purpose:

sudo docker pull stuartmarsden/multicastping

This downloads an image which is based on Ubuntu 14.04 with python and twisted. It runs a simple program that sends a multicast ping and listens and records any it receives. In order for this to appear as a docker service it must be tagged with core. Find out the id by running 'sudo docker images'. You should see all installed images and the one you want looks like this:

stuartmarsden/multicastping    latest              4833487e66d2        20 hours
ago        487 MB

The id will be different on your machine so use it in the following command:

sudo docker tag 4833487e66d2 stuartmarsden/multicastping:core

This image will be listed in the services after we restart the core-daemon:

sudo service core-daemon restart

Quagga Routing Suite

Quagga is a routing software suite, providing implementations of OSPFv2, OSPFv3, RIP v1 and v2, RIPng and BGP-4 for Unix platforms, particularly FreeBSD, Linux, Solaris and NetBSD. Quagga is a fork of GNU Zebra which was developed by Kunihiro Ishiguro. The Quagga architecture consists of a core daemon, zebra, which acts as an abstraction layer to the underlying Unix kernel and presents the Zserv API over a Unix or TCP stream to Quagga clients. It is these Zserv clients which typically implement a routing protocol and communicate routing updates to the zebra daemon.

Quagga Package Install

sudo apt-get install quagga

Quagga Source Install

First, download the source code from their official webpage.

sudo apt-get install gawk

Extract the tarball, go to the directory of your currently extracted code and issue the following commands.

./configure
make
sudo make install

Software Defined Networking

Ryu is a component-based software defined networking framework. Ryu provides software components with well defined API that make it easy for developers to create new network management and control applications. Ryu supports various protocols for managing network devices, such as OpenFlow, Netconf, OF-config, etc. About OpenFlow, Ryu supports fully 1.0, 1.2, 1.3, 1.4, 1.5 and Nicira Extensions. All of the code is freely available under the Apache 2.0 license.

Installation

Prerequisites

sudo apt-get install gcc python-dev libffi-dev libssl-dev libxml2-dev libxslt1-dev zlib1g-dev

Ryu Package Install

pip install ryu

Ryu Source Install

git clone git://github.com/osrg/ryu.git
cd ryu; pip install .

Security Services

The security services offer a wide variety of protocols capable of satisfying the most use cases available. Security services such as IP security protocols, for providing security at the IP layer, as well as the suite of protocols designed to provide that security, through authentication and encryption of IP network packets. Virtual Private Networks (VPNs) and Firewalls are also available for use to the user.

Installation

sudo apt-get install ipsec-tools racoon openvpn

UCARP

UCARP allows a couple of hosts to share common virtual IP addresses in order to provide automatic failover. It is a portable userland implementation of the secure and patent-free Common Address Redundancy Protocol (CARP, OpenBSD's alternative to the patents-bloated VRRP).

Strong points of the CARP protocol are: very low overhead, cryptographically signed messages, interoperability between different operating systems and no need for any dedicated extra network link between redundant hosts.

Installation

sudo apt-get install ucarp