Get Started

There are two ways to get started with nf.io.

• Option 1: Download a pre-packaged VirtualBox Appliance for nf.io
  • Download the appliance from here
  • Import the appliance in VirtualBox. Instructions can be found here
  • username/password: nfuser/nfpass
  • update the nf.io git repository
    cd ~/nf.io && git pull
  • check out the tag v0.1.1
    git checkout tags/v.0.1.1
  • update the nf.io-docker-images git repository
    cd ~/nf.io-docker-images && git pull
• Option 2: Install from source
  • Step 0: It is assumed that you are starting from a fresh Ubuntu installation. nf.io has been tested on ubuntu 14.04 and 15.04. It should run on other versions as long as the following dependencies are satisfied:
    • python 2
    • FUSE 2.6.0 or above
    • Docker python client version 1.1.0: docker-py
    • Docker remote API 1.15. Support for other versions will be added in the future.
  • Step 1: Install the following tools/utilities:
    • git
    • wget
    • python-pip
    sudo apt-get install git wget python-pip
  • Step 2: Install FUSE. Follow the instructions on github.com: libfuse
  • Step 3: Add your username to the group fuse
    sudo addgroup <username> fuse
    Log out of the machine and back in for this to take effect!
  • Step 4: Install Docker. Follow the instruction on docker.com: Install Docker
    Add your user to the "docker" group
    sudo addgroup <username> docker
    Log out of the machine again and back in for this to take effect!
  • Step 5: Install the docker-py client 1.1.0
    sudo pip install docker-py==1.1.0
    Run the following command to allow remote API calls
    sudo sed -i 's@.*DOCKER_OPTS=.*@DOCKER_OPTS="--ipv6=true -H unix:///var/run/docker.sock -H tcp://0.0.0.0:4444"@g' /etc/default/docker
    Note: we need to enable ipv6 network here as some VNFs (e.g., ufw) require ipv6 kernel modules.
    Restart the Docker daemon
    sudo service docker restart
  • Step 6: Clone the nf.io Git repository
    git clone https://github.com/WatNFV/nf.io.git
  • Step 7: Create the initial directories for nf.io
    sudo mkdir /vnfsroot
sudo mkdir -p /vnfsroot/nf-types
sudo chown -R <username>:<username> /vnfsroot
sudo mkdir /nfio
sudo chown -R <username>:<username> /nfio
    

Build Docker images for VNFs

• Step 1: Git clone the WatNFV/nf.io-docker-images repository
  Note: You can skip this step if you are using the downloaded VM image. However, please update the VNF image specifications by running git pull inside the directory nf.io-docker-images before going to step 2
  git clone https://github.com/WatNFV/nf.io-docker-images.git
• Step 2: cd to a VNF directory, e.g., cd ufw and build the docker image following the provided directions. These directions may differ for different VNF types, so, follow the directions provided in each VNF's own directory.

Running nf.io

• Inside the nf.io/src directory run the following command:
  python nfio.py --nfio_root /vnfsroot --nfio_mount /nfio
• Command line options for nfio.py can be seen by running the command
  python nfio.py -h
  

  usage: nfio.py [-h] --nfio_root NFIO_ROOT --nfio_mount NFIO_MOUNT
                 [--hypervisor HYPERVISOR]
                 [--middlebox_module_root MIDDLEBOX_MODULE_ROOT]
                 [--log_level LOG_LEVEL]
  
  nf.io File System for NFV Orchestration
  
  optional arguments:
    -h, --help            show this help message and exit
    --nfio_root NFIO_ROOT
                          Absolute path of nf.io root (default: None)
    --nfio_mount NFIO_MOUNT
                          Absolute path of nf.io mount point (default: None)
    --hypervisor HYPERVISOR
                          Hypervisor to use for VNF deployment (Docker/Libvirt)
                          (default: Docker)
    --middlebox_module_root MIDDLEBOX_MODULE_ROOT
                          Module directory inside the source tree containing
                          middlebox specific implementation of system calls
                          (default: middleboxes)
    --log_level LOG_LEVEL
                          [debug|info|warning|error] (default: info)
  
              

nf.io Abstraction

Deploy your first VNF using nf.io

• Run nfio.py as shown above if it is not running already
• Build the docker image for a VNF, e.g., here we will use ufw as a firewall
  cd nf.io-docker-images/ufw
docker build -t firewall .
  
• Create a directory for firewall
  cd /nfio/nf-types
mkdir firewall
• Create a directory for a VNF instance
  cd firewall
mkdir edge-ufw-1
  The files and directories representing a firewall will be automatically created under the directory edge-ufw-1
• Provide the configurations required for deployment
  cd edge-ufw-1
echo -n '127.0.0.1' > machine/ip
echo -n 'firewall' > machine/vm.image
  Note: here -n is used with echo to avoid parsing issues with the \n character.
• Deploy and start the VNF
  echo -n 'activate' > action
  Other possibles actions are:
  
  • stop  stops a running VNF
  • start  starts a stopped VNF
  • destroy  destroys a running/stopped VNF
• Get the current status of the VNF
  cat status && echo
  Note: a \n is not returned after the status (or any read data) to enable command pipes
• Get the number of bytes transferred by this VNF
  cat stats/tx_bytes && echo
• login to the deployed VNF
  ssh root@$(cat machine/vm.ip)
  The default password is pass

Multi-host deployment

• nf.io can be deployed on multiple hosts. One host will run the nfio.py program (nf.io-master) and the other hosts will run docker containers (nf.io-minions).
• On each minion it is required to active Docker remote API call by the following commands:
  sudo sed -i 's@.*DOCKER_OPTS=.*@DOCKER_OPTS="--ipv6=true -H unix:///var/run/docker.sock -H tcp://0.0.0.0:4444"@g' /etc/default/docker
  Note: we need to enable ipv6 network here as some VNFs (e.g., ufw) require ipv6 kernel modules.
  Then restart the Docker daemon
  sudo service docker restart
• nf.io-master can also serve as a nf.io-minion