OESS - Open Exchange Software Suite
https://globalnoc.github.io/OESS/
Copyright 2011 Trustees of Indiana University AND University Corporation for Advanced Internet Development (UCAID d.b.a. Internet2)
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
OESS is an application to configure and control OpenFlow Enabled switches through a very simple and user friendly User Interface. OESS provides layer2 and layer3 circuit provisioning, automatic failover, per-interface permissions, and automatic per-Vlan statistics.
OESS requires several packages to work, the core is built on Apache, and MySQL howevever there are several other packages needed. One of which is SNAPP collector.
OESS is easy to setup, with our provided oess_setup.pl script. This script (installed in /usr/bin/oess_setup.pl via RPM) takes a user step by step to get base OESS configuration up and running. Once the base installation is complete the rest of the configuration is done through the Administrator Interface located (http://localhost/oess/admin/admin_index.cgi). This UI allows for the creation of new users, the acceptance of new Nodes and links and the setup and configuration of workgroups.
To start the OESS services, there is an init script /etc/init.d/oess that should start all of the individual pieces of OESS in the proper order.
OESS needs a few ports to be able to operator 6633 - OpenFlow protocol 443/80 - Apache/SSL
The Admin UI provides the ability to control almost every aspect of the OESS software. Including users, workgroups, ports, nodes, and links. Any user that can reach the administrative UI can make any changes. This should be locked down to allowed users, through use of a different HTPASSWD file or a different authentication mechanism. Once this is done, users can be added and put into workgroups. The workgroups allow permissions to be assigned to users as groups instead of individuals. This way an entity can have multiple people with the same permissions. Workgroups are given access to individual interfaces on devices. Any workgroup can provision over trunk interfaces.
Once a user and workgroup are configured, the network devices need to be approved. This depends on the network devices being configured to talk to the openflow controller now running on the host. If the devices are talking to the controller then they will appear in the Discovery section of the admin UI. Clicking a row in under the devices table, allows the user to set the device name, and set a lat and longitude. Once the device is confirmed, any links detected between other confirmed devices will appear in the links table. Select a row in the Links table to approve a link for usage. Once all of the devices and links have been confirmed the available non-trunk interfaces for the devices will appear in the Workgroups add Edge Port page. Add any ports to the workgroup to allow that group to provision any circuits.
IF YOU RAN THE oess_setup.pl SCRIPT SKIP THIS SECTION!
If you do not use the oess_setup.pl script then manual configuration must occur. First you need a mysql instance running, and need to create an OESS mysql user and set the password, finally create the database named (oess?) and do a grant all on oess.* to your oess user.
Once the OESS user is installed and granted privileges on the OESS Database, you can now install the schema. The schema will be located with the OESS::Database perl module. It will be called nddi.sql. Import the schema into your mysql instance.
Once the OESS schema is installed, you need to set a few bits of information, for example it needs a local network/domain. This needs to be inserted into the network table, and the is_local bit needs to be set to 1.
At this point in time the OESS database is all set, but the OESS configuration is not done. OESS needs to know how to talk to the database, the configuration file that contains this information needs to be located in /etc/oess/database.xml this configuration file should contain all of the information on how to connect to the mysql database, and oscars configuration details. The config file should look like this...
At this point OESS is configured, but services like SNAPP are not. To set them up, you'll need to first set up the snapp database. The SQL file for this will be located in /usr/share/oess-core/ and will be called snapp.mysql.sql. Insert it into a database called snapp. If you don't already, create a user called snapp for the database, and within SQL, run:
`GRANT ALL PRIVILEGES ON snapp.* to 'snapp'\@'localhost'`Afterwards, you will need to go and create a config file for SNAPP. Run these commands:
`/bin/mkdir -p /SNMP/snapp`Then with your favorite text editor, create an xml file at this location:
`/SNMP/snapp/snapp_config.xml`Add this in there for the configuration. Don't forget to replace the password field with your database password!
Now, for SNAPP to be of any use to you, you will need to set up a location for the rrd files. To set that up, run these commands.
`/bin/mkdir /SNMP/snapp/db/`
`/bin/chown _snapp:_snapp /SNMP/snapp/db/ -R`Now, open up MYSQL and run these commands:
`use snapp`
`update global set value = '/SNMP/snapp/db/' where name = 'rrddir'`For the next command, replace the ? with the interval you want OESS to collect VLAN per Interface statistics. (By default, oess_setup.pl will set this to 10)
`insert into collection_class (name,description,collection_interval,default_cf,default_class) VALUES ('PerVlanPerInterface','FlowStats',?,'AVERAGE',0)` Take note of the id created from the last command. You'll need it in the next step.
Run this command:
`select * from oid_collection where name = 'in-octets' or name = 'out-octets' or name = 'in-packets' or name = 'out-packets'`Several rows should be returned to you. For each row returned, do an insert command like so:
`insert into oid_collection_class_map (collection_class_id,oid_collection_id,order_val,ds_name) VALUES (<collection_class_id_I_told_you_to_get_above>,<oid_collection_id_from_group_of_rows_from_above_select_command>,20,<name_from_above_select_command>)`The next step is to set up RRA handling. Two questions to answer here before the mysql command needed for this:
How many data points do I want consolidated? (Default is one with the oess setup);
How long do I want to retain RRD data? (Default is 100 days)
With these in mind, run this command.
`insert into rra (collection_class_id,step,cf,num_days,xff) VALUES (<the_collection_class_id_told_you_to_save,<how_many_data_points_you_want_consolidated>,'AVERAGE',<number_of_days_you_put_in>,0.8)`;Repeat the above steps if you want another RRA. Otherwise, move on.
You will now need to create an admin workgroup. Run these commands to do so:
`use oess` (or whatever you decided to name your oess database)
`insert into workgroup (name,type) values ('admin','admin')`;We now need to make a frontend user for OESS. Assuming you are using htpasswd for auth:
If it doesn't exist already, make a path /usr/share/oess-frontend/www/ with octal permission of 755
In the www directory, run this command:
htpasswd -c <user_name_of_your_choice>The command will prompt you for a password. Type it in, and the password file should be good to go.
Ideally, using the same username you used for the htpasswd file, go back in MYSQL, and run these commands to create an admin user:
`use oess` (or whatever you decided to name your oess database)
`insert into user (email, given_names, family_name, type) values ('<your_email>', '<your_given_name>', '<your_family_or_last_name>', 'admin')`;
`select * from user` and take note of the user id it returns for the user you created. With that in hand:
insert into remote_auth (auth_name, user_id) values ('<user_name_in_htpasswd_file>',<user_id_from_above_select_command>)`Now we need to associate the new user with the admin workgroup. To do that:
`select * from workgroup`;Take note of the id of the admin workgroup I had you create:
`insert into user_workgroup_membership (workgroup_id, user_id) values (<workgroup_id>, <user_id>)`;Exit MySQL, and if you want to jump right into working with OESS, run this command:
`/etc/init.d/oess start`And OESS should be good to go!
Banana
//\
V \
\ _
\,'.-. |\. . ( \. `-. ,.-:\
\ \ .-. ..--' ,-';/
\ .-. `-....---' .--' ,'/
.. `-. ..--' ,' /
.- ``--..'' .-' ,'
-_-._ ,--' ,'
`-. ----""" __.-' --..___..--'
Where to go for Help
Downloading the Code
Supported devices
So far OESS has been tested against the NEC Rack switch model G8264
OESS only works with OSCARS 0.6. An OSCARS distribution that has been tested to work with OESS is included with this distribution. Configuring OSCARS is covered in the OSCARS documentation. Configuring OESS to work with OSCARS is covered below.
Presuming you have an OSCARS 0.6 instance setup and running, it is very simple to import all of the remote topologies into your OESS instance. A script called populate_remote_information.pl pulls down topology from the configured Topology Service and populates the node and interface data into the Database. This is then used when provisioning Interdomain circuits in OESS. To configure remote links to other networks in OESS, use the Administration UI, and select the Remote Links tab. To add a new Link, first select the confirmed node, then pick the local interface the remote link is on. At this point you will get a popup that ask for the name and the remote urn. The name will be the name for the link in your topology that will be submitted to the Topology service. The remote URN should be the remote IDCs endpoint which this port connects to. When you are done adding remote links click the submit topology button, to submit your topology to your configured Topology Service
You probably need to restart OSCARS now to make it not cache the topology. At this point if you have a peering up, you should be able to do interdomain circuits
If you want to test and play with OESS but do not have any OpenFlow capable switches then MiniNet is for you. MiniNet provides software defined OpenFlow switches that can process flow rules according to the openflow specification.
MiniNet can be obtained here http://yuba.stanford.edu/foswiki/bin/view/OpenFlow/MininetGettingStarted
Save the following as /home/openflow/mininet/custom/oess.py from mininet.topo import Topo, Node
class MyTopo( Topo ): "Simple topology example."
def init( self, enable_all = True ): "Create custom topo."
# Add default members to class.
super( MyTopo, self ).__init__()
# Set Node IDs for hosts and switches
northSwitch = 1
southSwitch = 2
eastSwitch = 3
westSwitch = 4
eastHost = 5
westHost = 6
northHost = 7
# Add nodes
self.add_node( northSwitch, Node( is_switch=True ) )
self.add_node( southSwitch, Node( is_switch=True ) )
self.add_node( eastSwitch, Node( is_switch=True ) )
self.add_node( westSwitch, Node( is_switch=True ) )
self.add_node( eastHost, Node( is_switch=False ) )
self.add_node( westHost, Node( is_switch=False ) )
self.add_node( northHost, Node( is_switch=False ) )
# Add edges
self.add_edge( eastSwitch, northSwitch )
self.add_edge( eastSwitch, southSwitch )
self.add_edge( westSwitch, northSwitch )
self.add_edge( westSwitch, southSwitch )
#self.add_edge( northSwitch, southSwitch )
self.add_edge( eastSwitch, eastHost )
self.add_edge( westSwitch, westHost )
self.add_edge( northSwitch, northHost )
# Consider all switches and hosts 'on'
self.enable_all()topos = { 'oess_example': ( lambda: MyTopo() ) }
then run the following on the mini-net host
cd /home/openflow/mininet; sudo mn --controller remote --ip