Making a New EI Service

When you’re making an EI Service, there are a number of files that contain different parts of the service itself. Knowing what these files are and their purpose will aid you in quickly beginning to write your own service!

This document will review all of the files needed for an EI service that implements a host module. The host module is not required. If you wish for your service to not use a host module, simply delete the host/ folder that is created when using the automatic service creation script.

To use the automatic service creation script, run the following in the ei/ folder:

./scripts/deploy_new_service <SERVICE_NAME> <SERVICE_ID>

The variables SERVICE_NAME and SERVICE_ID should be the name of the new service, and the desired ID for the service. This ID cannot conflict with any other service currently within EI. The ID 99 is a special ID reserved for internal messages. All of the included services have IDs under 10, and the skeleton service has an ID of 88.

This script will create the new service with all of the necessary files within it. See below for a description of each file and what to add to it.

To make a new service manually, simply make a subdirectory in the ei/ folder. The name of the folder should roughly match the name of the service, but does not need to be exact. Then manually create all of the files listed below, though you should still use another service’s files as a template.

Files in an EI Service’s Folder

  • CMakeLists.txt

    The CMake file for the service. Typically you will not need to modify this, but if your service interfaces with external libraries as part of its functionality, change it as needed to include them during compilation. If your service needs quiche, uncomment the relevant lines.

  • ei_sm.meta

    This file lets the EI build script know that this subdirectory is a service, what service ID it is, and whether the service uses quiche. If the service uses quiche, set the relevant line to True instead of False.

  • headers.h

    This is part of the example skeleton service that gets copied in by the automatic service creation script. It contains a packet format for a packet used by the service. This file isn’t strictly necessary, but most services will want one to define their packet headers in.

  • __init__.py

    A small shim file used to initialize the service when Pox runs it, mainly by running service.py.

  • service.py

    This file contains the Python module that runs the EI service itself. This is what EI actually interfaces with, and can be modified to perform various tasks, set up watchers, and communicate with the C++ portion of the service runtime.

  • service.cpp

    The core of the C++ portion of the service runtime. Processes and sends packets given to it over pipes, and can also perform interfacing with any other C/C++ libraries that may be necessary to provide the functionality desired by the service.

  • service.h

    The header file for service.cpp.

  • host/CMakeLists.txt

    The CMake file for the host stack, if one is desired by the service. This typically should not be modified, as its only purpose is to ensure the host module object file is created for the Pipe Terminus to use.

  • host/host_module.cpp

    The core of the host module itself. Contains IPC handler code and handles messages to and from the service module for the host stack.

  • host/_ipc_structs.h

    The list of IPCs that must be implemented in host_module.cpp. Definitions here are translated by the build step before any compilation, so this file is never actually compiled.

  • scripts/make_ctypes.sh

    A script to compile the C++ portion of the service module into bindings usable in Python by __init__.py. Typically never needs to be changed for any reason.

Using IPCs in Applications

The IPCs defined in host/_ipc_structs.h are compiled using clang2py into a Python module that Python applications can access. We also provide a script, scripts/seymour.py, that can load this module and parse out the compiled ctypes IPC objects into more usable object formats. Many of our test scripts use this library, such as odns/scripts/basic_lookup.py.