afonso/core-extra
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

small tweaks to documentation, initial add of a section for grpc, moved ns3 to experimental section

Browse source
This commit is contained in:
Blake Harnden 2019-06-11 12:05:04 -07:00
parent 1d1eba84fc
commit 5b1c9a6e68
4 changed files with 161 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
docs/experimental.md Normal file
View file

@ -0,0 +1,9 @@
# Experimental Features
Below are current features that are considered experimental and will likely have issues.
# NS3
Experimental support for scripting CORE nodes with NS3.
[NS# Overview](ns3.md)

121
docs/grpc.md Normal file
View file

@ -0,0 +1,121 @@
# Using the gRPC API
By default the gRPC API is currently not turned on by default. There are a couple ways that this can be enabled
to use.
## Enabling gRPC
### HTTP Proxy
Since gRPC is HTTP2 based, proxy configurations can cause issue. Clear out your proxy when running if needed.
### Daemon Options
The gRPC API is enabled through options provided to the **core-daemon**.
```shell
usage: core-daemon [-h] [-f CONFIGFILE] [-p PORT] [-n NUMTHREADS] [--ovs]
[--grpc] [--grpc-port GRPCPORT]
[--grpc-address GRPCADDRESS]
CORE daemon v.5.3.0 instantiates Linux network namespace nodes.
optional arguments:
-h, --help show this help message and exit
-f CONFIGFILE, --configfile CONFIGFILE
read config from specified file; default =
/etc/core/core.conf
-p PORT, --port PORT port number to listen on; default = 4038
-n NUMTHREADS, --numthreads NUMTHREADS
number of server threads; default = 1
--ovs enable experimental ovs mode, default is false
--grpc enable grpc api, default is false
--grpc-port GRPCPORT grpc port to listen on; default 50051
--grpc-address GRPCADDRESS
grpc address to listen on; default localhost
```
### Enabling in Service Files
Modify service files to append the --grpc options as desired.
For sysv services /etc/init.d/core-daemon
```shell
CMD="PYTHONPATH=/usr/lib/python3.6/site-packages python3 /usr/bin/$NAME --grpc"
```
For systemd service /lib/systemd/system/core-daemon.service
```shell
ExecStart=@PYTHON@ @bindir@/core-daemon --grpc
```
### Enabling from Command Line
```shell
sudo core-daemon --grpc
```
## Python Client
A python client wrapper is provided at **core.api.grpc.client.CoreGrpcClient**.
Below is a small example using it.
```python
import logging
from builtins import range
from core.api.grpc import client, core_pb2
def log_event(event):
logging.info("event: %s", event)
def main():
core = client.CoreGrpcClient()
with core.context_connect():
# create session
response = core.create_session()
logging.info("created session: %s", response)
# handle events session may broadcast
session_id = response.session_id
core.events(session_id, log_event)
# change session state
response = core.set_session_state(session_id, core_pb2.SessionState.CONFIGURATION)
logging.info("set session state: %s", response)
# create switch node
switch = core_pb2.Node(type=core_pb2.NodeType.SWITCH)
response = core.add_node(session_id, switch)
logging.info("created switch: %s", response)
switch_id = response.node_id
# helper to create interfaces
interface_helper = client.InterfaceHelper(ip4_prefix="10.83.0.0/16")
for i in range(2):
# create node
position = core_pb2.Position(x=50 + 50 * i, y=50)
node = core_pb2.Node(position=position)
response = core.add_node(session_id, node)
logging.info("created node: %s", response)
node_id = response.node_id
# create link
interface_one = interface_helper.create_interface(node_id, 0)
response = core.add_link(session_id, node_id, switch_id, interface_one)
logging.info("created link: %s", response)
# change session state
response = core.set_session_state(session_id, core_pb2.SessionState.INSTANTIATION)
logging.info("set session state: %s", response)
if __name__ == "__main__":
logging.basicConfig(level=logging.DEBUG)
main()
```

43
docs/index.md
View file

@ -2,9 +2,13 @@
## Introduction
CORE (Common Open Research Emulator) is a tool for building virtual networks. As an emulator, CORE builds a representation of a real computer network that runs in real time, as opposed to simulation, where abstract models are used. The live-running emulation can be connected to physical networks and routers. It provides an environment for running real applications and protocols, taking advantage of virtualization provided by the Linux operating system.
CORE (Common Open Research Emulator) is a tool for building virtual networks. As an emulator, CORE builds a
representation of a real computer network that runs in real time, as opposed to simulation, where abstract models are
used. The live-running emulation can be connected to physical networks and routers. It provides an environment for
running real applications and protocols, taking advantage of virtualization provided by the Linux operating system.
CORE is typically used for network and protocol research, demonstrations, application and platform testing, evaluating networking scenarios, security studies, and increasing the size of physical test networks.
CORE is typically used for network and protocol research, demonstrations, application and platform testing, evaluating
networking scenarios, security studies, and increasing the size of physical test networks.
### Key Features
* Efficient and scalable
@ -14,22 +18,31 @@ CORE is typically used for network and protocol research, demonstrations, applic
## Topics
* [Architecture](architecture.md)
* [Installation](install.md)
* [Using the GUI](usage.md)
* [Python Scripting](scripting.md)
* [Node Types](machine.md)
* [CTRLNET](ctrlnet.md)
* [Services](services.md)
* [EMANE](emane.md)
* [NS3](ns3.md)
* [Performance](performance.md)
* [Developers Guide](devguide.md)
| Topic | Description|
|-------|------------|
|[Architecture](architecture.md)|Overview of the architecture|
|[Installation](install.md)|Installing from source, packages, & other dependencies|
|[Using the GUI](usage.md)|Details on the different node types and options in the GUI|
|[Python Scripting](scripting.md)|How to write python scripts for creating a CORE session|
|[gRPC API](grpc.md)|How to enable and use the gRPC API|
|[Node Types](machine.md)|Overview of node types supported within CORE|
|[CTRLNET](ctrlnet.md)|How to use control networks to communicate with nodes from host|
|[Services](services.md)|Overview of provided services and creating custom ones|
|[EMANE](emane.md)|Overview of EMANE integration and integrating custom EMANE models|
|[Performance](performance.md)|Notes on performance when using CORE|
|[Developers Guide](devguide.md)|Overview of topics when developing CORE|
|[Experimental](experimental.md)|Experimental features for use with or within CORE|
## Credits
The CORE project was derived from the open source IMUNES project from the University of Zagreb in 2004. In 2006, changes for CORE were released back to that project, some items of which were adopted. Marko Zec <zec@fer.hr> is the primary developer from the University of Zagreb responsible for the IMUNES (GUI) and VirtNet (kernel) projects. Ana Kukec and Miljenko Mikuc are known contributors.
The CORE project was derived from the open source IMUNES project from the University of Zagreb in 2004. In 2006,
changes for CORE were released back to that project, some items of which were adopted. Marko Zec <zec@fer.hr> is the
primary developer from the University of Zagreb responsible for the IMUNES (GUI) and VirtNet (kernel) projects. Ana
Kukec and Miljenko Mikuc are known contributors.
Jeff Ahrenholz has been the primary Boeing developer of CORE, and has written this manual. Tom Goff designed the Python framework and has made significant contributions. Claudiu Danilov, Rod Santiago, Kevin Larson, Gary Pei, Phil Spagnolo, and Ian Chakeres have contributed code to CORE. Dan Mackley helped develop the CORE API, originally to interface with a simulator. Jae Kim and Tom Henderson have supervised the project and provided direction.
Jeff Ahrenholz has been the primary Boeing developer of CORE, and has written this manual. Tom Goff designed the
Python framework and has made significant contributions. Claudiu Danilov, Rod Santiago, Kevin Larson, Gary Pei,
Phil Spagnolo, and Ian Chakeres have contributed code to CORE. Dan Mackley helped develop the CORE API, originally to
interface with a simulator. Jae Kim and Tom Henderson have supervised the project and provided direction.
Copyright (c) 2005-2018, the Boeing Company.

6
docs/scripting.md
View file

@ -17,8 +17,8 @@ Here are the basic elements of a CORE Python script:
```python
from core.emulator.coreemu import CoreEmu
from core.emulator.emudata import IpPrefixes
from core.enumerations import EventTypes
from core.enumerations import NodeTypes
from core.emulator.enumerations import EventTypes
from core.emulator.enumerations import NodeTypes
# ip generator for example
prefixes = IpPrefixes(ip4_prefix="10.83.0.0/16")
@ -34,7 +34,7 @@ session.set_state(EventTypes.CONFIGURATION_STATE)
switch = session.add_node(_type=NodeTypes.SWITCH)
# create nodes
for _ in xrange(options.nodes):
for _ in range(2):
node = session.add_node()
interface = prefixes.create_interface(node)
session.add_link(node.id, switch.id, interface_one=interface)