# vim-emu: NFV Emulation Platform

> **Note:** vim-emu is no longer actively maintained by the OSM project. The information in this page is preserved for reference. If you are interested in contributing to its evolution or taking over its maintenance, please contact the OSM Technical Steering Committee (TSC) at <OSMsupport@etsi.org>.

## Overview

vim-emu is a Docker-based NFV emulation platform that allows developers to prototype, test, and evaluate NFV and SDN network services locally without requiring physical hardware. It was designed to be used as a VIM (Virtual Infrastructure Manager) plug-in for OSM, enabling lightweight emulation of network topologies.

vim-emu is based on [Containernet](https://containernet.github.io/), which extends the popular [Mininet](http://mininet.org/) network emulator to support Docker containers as emulated hosts.

**Key capabilities:**

- Emulate VNF deployments using Docker containers connected through virtual links.
- Support for multi-PoP (Point of Presence) scenarios emulating distributed NFV infrastructures.
- Integration with real SDN controllers via OpenFlow.
- REST API to control the emulated VIM from external orchestrators (including OSM).
- Lightweight execution on a single developer laptop or VM.

## Installation

### Requirements

- Ubuntu 16.04 LTS or later (Ubuntu 18.04 recommended)
- Docker Engine (17.x or later)
- Python 3.x
- [Containernet](https://containernet.github.io/) installed on the host

### Install Containernet

vim-emu builds on Containernet, which must be installed first. Follow the [Containernet installation guide](https://containernet.github.io/#installation).

### Install vim-emu

Clone the vim-emu repository and install:

```bash
git clone https://github.com/containernet/vim-emu.git
cd vim-emu
sudo python setup.py install
```

Alternatively, install directly from PyPI:

```bash
sudo pip install vim-emu
```

### Verify the installation

```bash
sudo python -c "import emuvim; print('vim-emu installed successfully')"
```

## Starting vim-emu as a VIM for OSM

vim-emu exposes a REST API that OSM's Resource Orchestrator (RO) can consume as an OpenStack-compatible VIM endpoint.

Start vim-emu with the OpenStack-compatible endpoint enabled:

```bash
sudo python start_emulator.py --endpoint_ip 0.0.0.0 --endpoint_port 6001
```

Once running, register it as a VIM in OSM using the CLI:

```bash
osm vim-create \
  --name vim-emu \
  --account_type openstack \
  --auth_url http://<vim-emu-host>:6001/v2.0 \
  --user admin \
  --password admin \
  --tenant default
```

Replace `<vim-emu-host>` with the IP address of the machine running vim-emu.

## Defining a Network Topology

vim-emu uses Python scripts to define the emulated infrastructure. A minimal two-datacenter topology looks like this:

```python
from mininet.log import setLogLevel
from emuvim.dcemulator.net import DCNetwork
from emuvim.api.rest.rest_api_endpoint import RestApiEndpoint

def create_topology():
    net = DCNetwork(monitor=False, enable_learning=True)

    # Create two emulated data centres
    dc1 = net.addDatacenter("dc1")
    dc2 = net.addDatacenter("dc2")

    # Connect them
    net.addLink(dc1, dc2, delay="20ms", bw=1000)

    # Add REST API endpoint
    api = RestApiEndpoint("0.0.0.0", 6001)
    api.connectDCNetwork(net)
    api.connectDatacenter(dc1)
    api.connectDatacenter(dc2)
    api.start()

    net.start()
    net.CLI()
    net.stop()

if __name__ == '__main__':
    setLogLevel('info')
    create_topology()
```

Save this as `topology.py` and run with:

```bash
sudo python topology.py
```

## Deploying VNFs

With vim-emu running, you can deploy Dockerized VNFs either through OSM or directly through the REST API.

### Deploy directly via REST API

```bash
curl -X POST http://localhost:6001/restapi/compute/dc1/<vnf-name> \
  -H 'Content-Type: application/json' \
  -d '{"image": "ubuntu:xenial", "command": "ping 8.8.8.8"}'
```

### List running VNFs

```bash
curl http://localhost:6001/restapi/compute/dc1
```

### Remove a VNF

```bash
curl -X DELETE http://localhost:6001/restapi/compute/dc1/<vnf-name>
```

## Monitoring

vim-emu provides basic resource monitoring via the REST API:

```bash
curl http://localhost:6001/restapi/monitor/dc1/<vnf-name>
```

Metrics (CPU usage, memory, network I/O) are returned as JSON.

## Further Resources

- [vim-emu GitHub repository](https://github.com/containernet/vim-emu)
- [Containernet documentation](https://containernet.github.io/)
- [vim-emu research paper](https://ieeexplore.ieee.org/document/7899408) — original publication describing the architecture