From 8155cdc6178aebab5c6d1cf6e5f337fb4068aa03 Mon Sep 17 00:00:00 2001 From: "Blake J. Harnden" Date: Thu, 17 Aug 2017 15:25:12 -0700 Subject: [PATCH] documentation theme update, version bumping to 5.0, changes to cleanup pass for ns3 code --- Changelog | 2 +- configure.ac | 2 +- daemon/Makefile.am | 2 +- daemon/ns3/examples/ns3wifi.py | 2 +- daemon/ns3/examples/ns3wifirandomwalk.py | 2 +- daemon/ns3/setup.py | 2 +- daemon/requirements.txt | 2 -- daemon/setup.py | 2 +- doc/conf.py.in | 5 ++-- doc/intro.rst | 30 ++++++++----------- doc/requirements.txt | 2 ++ doc/scripting.rst | 37 ++++++++++++------------ packaging/deb/changelog | 8 ++++- packaging/rpm/core.spec.in | 8 +++-- 14 files changed, 54 insertions(+), 52 deletions(-) create mode 100644 doc/requirements.txt diff --git a/Changelog b/Changelog index 37a1e36b..ad95ea76 100644 --- a/Changelog +++ b/Changelog @@ -7,7 +7,7 @@ - leverage "logzero" module to make easy usage of the standard logging module - improvements to documentation across the code base - initial work to separate the dependence on TCP API messaging from the core library (easier core scripting) - - beta support for running core in openvswitch mode, leveraging ovs bridges, instead of linux bridges + - beta support for running core in Open vSwitch mode, leveraging Open vSwitch bridges, instead of Linux bridges * SERVICES: - added Ryu SDN controller service - added Open vSwitch service diff --git a/configure.ac b/configure.ac index c5c4a773..c0f533d5 100644 --- a/configure.ac +++ b/configure.ac @@ -12,7 +12,7 @@ # # this defines the CORE version number, must be static for AC_INIT # -AC_INIT(core, m4_esyscmd_s([./revision.sh 4.8]), core-dev@pf.itd.nrl.navy.mil) +AC_INIT(core, m4_esyscmd_s([./revision.sh 5.0]), core-dev@pf.itd.nrl.navy.mil) VERSION=$PACKAGE_VERSION CORE_VERSION=$PACKAGE_VERSION CORE_VERSION_DATE=m4_esyscmd_s([./revision.sh -d]) diff --git a/daemon/Makefile.am b/daemon/Makefile.am index fde0871c..2bbfc299 100644 --- a/daemon/Makefile.am +++ b/daemon/Makefile.am @@ -97,7 +97,7 @@ uninstall-local: # Python package uninstall uninstall-hook: - yes | pip uninstall core_python + yes | pip uninstall core-python rm -f ${pythondir}/core_python_netns-1.0-py${PYTHON_VERSION}.egg-info rm -rf ${pythondir}/core rmdir -p $(coreexservicesdir) || true diff --git a/daemon/ns3/examples/ns3wifi.py b/daemon/ns3/examples/ns3wifi.py index b548458a..bc29ca80 100755 --- a/daemon/ns3/examples/ns3wifi.py +++ b/daemon/ns3/examples/ns3wifi.py @@ -41,7 +41,7 @@ def add_to_server(session): """ global server try: - server.addsession(session) + server.add_session(session) return True except NameError: return False diff --git a/daemon/ns3/examples/ns3wifirandomwalk.py b/daemon/ns3/examples/ns3wifirandomwalk.py index 363fafb3..fc37cce4 100755 --- a/daemon/ns3/examples/ns3wifirandomwalk.py +++ b/daemon/ns3/examples/ns3wifirandomwalk.py @@ -30,7 +30,7 @@ def add_to_server(session): """ global server try: - server.addsession(session) + server.add_session(session) return True except NameError: return False diff --git a/daemon/ns3/setup.py b/daemon/ns3/setup.py index f972a9c7..811f5adb 100644 --- a/daemon/ns3/setup.py +++ b/daemon/ns3/setup.py @@ -2,7 +2,7 @@ from setuptools import setup setup( name="corens3-python", - version="5.0.0", + version="5.0", packages=[ "corens3", ], diff --git a/daemon/requirements.txt b/daemon/requirements.txt index 831a7390..8d1241db 100644 --- a/daemon/requirements.txt +++ b/daemon/requirements.txt @@ -7,5 +7,3 @@ pycco==0.5.1 pytest==3.0.7 pytest-cov==2.5.1 pytest-runner==2.11.1 -sphinx==1.4.8 -sphinx_rtd_theme==0.1.9 diff --git a/daemon/setup.py b/daemon/setup.py index 376081f8..fd764a5f 100644 --- a/daemon/setup.py +++ b/daemon/setup.py @@ -8,7 +8,7 @@ Defines how CORE will be built for installation. from setuptools import setup setup(name="core-python", - version="5.0.0", + version="5.0", packages=[ "core", "core.addons", diff --git a/doc/conf.py.in b/doc/conf.py.in index a76eab0e..eb0d034c 100644 --- a/doc/conf.py.in +++ b/doc/conf.py.in @@ -12,6 +12,7 @@ # serve to show the default. import sys, os +import sphinx_rtd_theme # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -91,7 +92,7 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +html_theme = 'sphinx_rtd_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -99,7 +100,7 @@ html_theme = 'default' #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". diff --git a/doc/intro.rst b/doc/intro.rst index d0428b77..d0ddc0c2 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -30,17 +30,11 @@ demonstrations, application and platform testing, evaluating networking scenarios, security studies, and increasing the size of physical test networks. What's New? -================= -For readers who are already familiar with CORE and have read this manual before, below is a list of what changed in version 4.8: - -* :ref:`Configuration_Files` - a new XML format has been defined by the U.S. Naval Research Lab (NRL) for the Network Management Framework. . - -* :ref:`EMANE` - `Release 0.9.2 of EMANE `_ included a new capability that, in order to be leveraged, needs changes on how it is deployed by CORE. The EMANE section of this document has been updated with new method of connecting together the deployed instances. -* :ref:`Control_Network` - with EMANE 0.9.2, the CORE control network has become an important component of CORE. Auxiliary control networks have been added to the primary control network to host EMANE traffic. As a result, the discussion on the control network has been elevated to a top level topic. -* `Tips, Hints, Important Information` - miscellaneous information added to several chapters in the document. - - +=========== +For readers who are already familiar with CORE and have read this manual before, below is a list of what changed in version 5.0: +* :ref:`Services` - Added Ryu SD and Open vSwitch services +* :ref:`Python_Scripting` - Updated script examples to reflect code changes .. index:: single: CORE; components of @@ -109,7 +103,7 @@ and FreeBSD systems. The primary platform used for development is Linux. single: LXC single: network namespaces -* :ref:`Linux` CORE uses Linux network namespace virtualization to build virtual nodes, and ties them together with virtual networks using Linux Ethernet bridging. +* :ref:`Linux` CORE uses Linux network namespace virtualization to build virtual nodes, and ties them together with virtual networks using Linux Ethernet bridging. * :ref:`FreeBSD` CORE uses jails with a network stack virtualization kernel option to build virtual nodes, and ties them together with virtual networks using BSD's Netgraph system. @@ -154,7 +148,7 @@ running programs. Starting with FreeBSD 8.0, a new `vimage` kernel option extends BSD jails so that each jail can have its own virtual network stack -- its own networking variables such as addresses, interfaces, routes, counters, protocol state, socket information, etc. The existing networking algorithms and -code paths are intact but operate on this virtualized state. +code paths are intact but operate on this virtualized state. Each jail plus network stack forms a lightweight virtual machine. These are named jails or *virtual images* (or *vimages*) and are created using a the @@ -172,13 +166,13 @@ added this functionality to the mainline 8.0-RELEASE and newer kernels. .. index:: - single: FreeBSD; Netgraph + single: FreeBSD; Netgraph The FreeBSD Operating System kernel features a graph-based networking subsystem named Netgraph. The netgraph(4) manual page quoted below -best defines this system: +best defines this system: - The netgraph system provides a uniform and modular system for the + The netgraph system provides a uniform and modular system for the implementation of kernel objects which perform various networking functions. The objects, known as nodes, can be arranged into arbitrarily complicated graphs. Nodes have hooks which are used to connect two nodes together, @@ -202,8 +196,8 @@ best defines this system: Prior Work ========== -The Tcl/Tk CORE GUI was originally derived from the open source -`IMUNES `_ +The Tcl/Tk CORE GUI was originally derived from the open source +`IMUNES `_ project from the University of Zagreb as a custom project within Boeing Research and Technology's Network Technology research group in 2004. Since then they have developed the CORE @@ -212,7 +206,7 @@ Python framework, and made numerous user- and kernel-space developments, such as support for wireless networks, IPsec, the ability to distribute emulations, simulation integration, and more. The IMUNES project also consists of userspace and kernel components. Originally, one had to download and apply a patch for -the FreeBSD 4.11 kernel, but the more recent +the FreeBSD 4.11 kernel, but the more recent `VirtNet `_ effort has brought network stack virtualization to the more modern FreeBSD 8.x kernel. diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 00000000..7f923e5c --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,2 @@ +sphinx==1.6.3 +sphinx_rtd_theme==0.2.4 diff --git a/doc/scripting.rst b/doc/scripting.rst index 5693702d..8879981c 100644 --- a/doc/scripting.rst +++ b/doc/scripting.rst @@ -21,10 +21,10 @@ or online via interactive Python. The best starting point is the sample scripts that are included with CORE. If you have a CORE source tree, the example script files can be found under :file:`core/daemon/examples/netns/`. When CORE is installed -from packages, the example script files will be in +from packages, the example script files will be in :file:`/usr/share/core/examples/netns/` (or the :file:`/usr/local/...` prefix when installed from source.) For the most part, the example scripts -are self-documenting; see the comments contained within the Python code. +are self-documenting; see the comments contained within the Python code. The scripts should be run with root privileges because they create new network namespaces. In general, a CORE Python script does not connect to the @@ -37,20 +37,19 @@ allow for GUI connections. Here are the basic elements of a CORE Python script: :: - #!/usr/bin/python + from core.session import Session + from core.netns import nodes - from core import pycore - - session = pycore.Session(persistent=True) - node1 = session.addobj(cls=pycore.nodes.CoreNode, name="n1") - node2 = session.addobj(cls=pycore.nodes.CoreNode, name="n2") - hub1 = session.addobj(cls=pycore.nodes.HubNode, name="hub1") + session = Session(persistent=True) + node1 = session.add_object(cls=nodes.CoreNode, name="n1") + node2 = session.add_object(cls=nodes.CoreNode, name="n2") + hub1 = session.add_object(cls=nodes.HubNode, name="hub1") node1.newnetif(hub1, ["10.0.0.1/24"]) node2.newnetif(hub1, ["10.0.0.2/24"]) node1.icmd(["ping", "-c", "5", "10.0.0.2"]) session.shutdown() - + The above script creates a CORE session having two nodes connected with a hub. The first node pings the second node with 5 ping packets; the result is @@ -63,19 +62,19 @@ a test ping to the other. The CORE Python modules are documented with comments in the code. From an interactive Python shell, you can retrieve online help about the various -classes and methods; for example *help(pycore.nodes.CoreNode)* or -*help(pycore.Session)*. +classes and methods; for example *help(nodes.CoreNode)* or +*help(Session)*. An interactive development environment (IDE) is available for browsing the CORE source, the -`Eric Python IDE `_. +`Eric Python IDE `_. CORE has a project file that can be opened by Eric, in the source under :file:`core/daemon/CORE.e4p`. This IDE has a class browser for viewing a tree of classes and methods. It features syntax highlighting, auto-completion, indenting, and more. One feature that is helpful with learning the CORE Python modules is the ability to generate -class diagrams; right-click on a class, choose *Diagrams*, and +class diagrams; right-click on a class, choose *Diagrams*, and *Class Diagram*. .. index:: daemon versus script @@ -90,12 +89,12 @@ class diagrams; right-click on a class, choose *Diagrams*, and does not need to be running for your script to work. The session created by a Python script may be viewed in the GUI if certain -steps are followed. The GUI has a :ref:`File_Menu`, *Execute Python script...* +steps are followed. The GUI has a :ref:`File_Menu`, *Execute Python script...* option for running a script and automatically connecting to it. Once connected, normal GUI interaction is possible, such as moving and double-clicking nodes, activating Widgets, etc. -The script should have a line such as the following for running it from +The script should have a line such as the following for running it from the GUI. :: @@ -113,14 +112,14 @@ A global ``server`` variable is exposed to the script pointing to the ''' global server try: - server.addsession(session) + server.add_session(session) return True except NameError: return False :: - session = pycore.Session(persistent=True) + session = Session(persistent=True) add_to_server(session) @@ -129,7 +128,7 @@ otherwise they will be grouped at the coordinates ``<0, 0>``. First sketching the topology in the GUI and then using the *Export Python script* option may help here. :: - + switch.setposition(x=80,y=50) diff --git a/packaging/deb/changelog b/packaging/deb/changelog index 1f9f83fe..df81cda5 100644 --- a/packaging/deb/changelog +++ b/packaging/deb/changelog @@ -1,3 +1,9 @@ +core (5.0-0ubuntu1) precise; urgency=low + + * Added Ryu SD and Open vSwitch services, code cleanup and refactoring + + -- CORE Developers XXX, XX XXX 2017 00:00:00 -0700 + core (4.8-0ubuntu1) precise; urgency=low * Support for NRL Network Modeling Framework (NMF) XML representation, bugfixes @@ -18,7 +24,7 @@ core (4.6-0ubuntu1) precise; urgency=low core (4.5-0ubuntu1) precise; urgency=low - * XML support, SDT3D support, EMANE 0.8.1, ns-3 locations, code cleanup, + * XML support, SDT3D support, EMANE 0.8.1, ns-3 locations, code cleanup, bugfixes, and more. -- Jeff Ahrenholz Thu, 11 Apr 2013 14:19:05 -0700 diff --git a/packaging/rpm/core.spec.in b/packaging/rpm/core.spec.in index 7cf28a7b..f76be06e 100644 --- a/packaging/rpm/core.spec.in +++ b/packaging/rpm/core.spec.in @@ -16,7 +16,7 @@ Release: 1%{?dist} Source: core-%{version}.tar.gz URL: http://www.nrl.navy.mil/itd/ncs/products/core Version: %{version} -%description +%description The Common Open Research Emulator provides Python modules and a GUI for building virtual networks using Linux network namespace containers and bridging. @@ -48,7 +48,7 @@ Provides: core-daemon # python-sphinx %description daemon The Common Open Research Emulator provides Python modules for building virtual -networks using Linux network namespace containers and bridging. +networks using Linux network namespace containers and bridging. %package gui Summary: Common Open Research Emulator GUI front-end @@ -59,7 +59,7 @@ BuildRequires: make automake autoconf Provides: core-gui %description gui The Common Open Research Emulator canvas-based Tcl/Tk GUI for easily drawing -virtual network topologies. +virtual network topologies. %prep @@ -410,6 +410,8 @@ fi %{_sbindir}/vnoded %changelog +* XXX XXX X 2017 CORE Developers - 5.0 +- Added Ryu SD and Open vSwitch services, code cleanup and refactoring * Fri Jun 5 2015 CORE Developers - 4.8 - Support for NRL Network Modeling Framework (NMF) XML representation, bugfixes * Wed Aug 6 2014 Jeff Ahrenholz - 4.7