diff --git a/docs/experimental.md b/docs/experimental.md new file mode 100644 index 00000000..7fdd896e --- /dev/null +++ b/docs/experimental.md @@ -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) diff --git a/docs/grpc.md b/docs/grpc.md new file mode 100644 index 00000000..d9743506 --- /dev/null +++ b/docs/grpc.md @@ -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() +``` diff --git a/docs/index.md b/docs/index.md index c4dd2a24..6d0a0477 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 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 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. diff --git a/docs/scripting.md b/docs/scripting.md index efb77ff7..9f8594ea 100644 --- a/docs/scripting.md +++ b/docs/scripting.md @@ -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)