Adding a Dev User Guide

config/opennsa.conf.template

 # Sample docker configuration file
 
 [service]
-domain=dockertest.net
+domain=dockertest.net:2021
 # log to stdout
 logfile=
 #peers=example.org@http://example.org:9080/NSI/topology/example.org.xml

docs/config.md

@@ -38,7 +38,7 @@ These are the options for the service block:
 `nrmmap`   : Path to port/topology NRM description file
 
 `peers`    : URLs to NSAs to peer with control-plane wise.
-             Seperate multiple entries with newline (only peers= on the first
+             Separate multiple entries with newline (only peers= on the first
              line). If using multiple lines, the following peer urls must be in
              indented at least pass the `=` on the first line (parser limitation).
              Optional. No peers will put OpenNSA into UPA mode.
@@ -46,20 +46,20 @@ These are the options for the service block:
 `policies` : What policies are required. Currently `requiretrace`, `requireuser`,
              and `aggregator` are the possible options. These require a connection
              trace, a user security attribute, and allow proxy aggregation
-             respecitively. Optional.
+             respectively. Optional.
 
 `serviceid_start` : Initial service id to set in the database. Requires a plugin
                     to use. Optional.
 
-`database` : Name of the PostgreSQL databse to connect to. Mandatory.
+`database` : Name of the PostgreSQL database to connect to. Mandatory.
 
 `dbuser`   : Username to use when connecting to database. Mandatory.
 
 `dbpassword` : Password to use when connecting to database. Mandatory.
 
-`dbhost`   : Host to connect to for database. Optional. If not specificed,
+`dbhost`   : Host to connect to for database. Optional. If not specified,
              OpenNSA will connect to PostgreSQL over the unix domain socket
-             OpenNSA does not require anything big from the datebase, so using a
+             OpenNSA does not require anything big from the database, so using a
              different host/vm is almost surely a waste of resources. It is
              however useful when running a PostgreSQL in docker.
 
@@ -126,7 +126,7 @@ resource do not get double booked.
               Use '-' if not connected to any network (termination inside the network).
 
 `label` : STP configuration options. Currently `vlan` and `mpls` are supported.
-          Note that not all backend support those. Can specify single values and ranges. Comma seperated.
+          Note that not all backend support those. Can specify single values and ranges. Comma separated.
           Use '-' if no labels are to be used (i.e., ethernet trunk).
 
 `bandwidth` : The available bandwidth on the port (or the bandwidth that is
@@ -134,7 +134,7 @@ resource do not get double booked.
 
 `interface` : The interface / port on the network device.
 
-`attributes` : A list of comma seperated attributes that describes security
+`attributes` : A list of comma separated attributes that describes security
                attributes or policies for the port. Security attributes always have the form
               `key=value`, otherwise it is a policy. Despite the name, security attributes
                are not very secure.

docs/developer_guide.md

+# Quick Developer Guide
+
+
+## Server Setup
+
+For this guide we are assuming you are using the configuration templates and examples provided by default.  Any commands
+will likely need to be updated accordingly for your own topology and configuration.
+
+We'll assume that you are either running the server locally.  Both of those cases will require a running postgres database.  For simplicity sake I'm going to assume you have a docker-compose stack running.  
+
+```
+./generate-docker-config  ## will create a .env file and config/opennsa.conf
+docker-compose up -d 
+```
+## Usage Guide
+
+All operations in this case will be triggered via the client titled onsa which can be found in the root of the project.
+
+There are a few 'base' operation that are supported by the Network Service Interface (NSI) Spec which you can find [here](GFD.237.pdf).  Others that are not listed in the document serve as a convenience method.
+
+All operation are usually a sequence of: reserve, reserveCommit, provision, release, terminate.
+query related requests are for diagnostic purposes.
+
+### Endpoints
+
+The following endpoints will then be accessible if everything works as advertised.
+
+  - http://localhost:9080/NSI/dockertest.net:2021:topology.nml.xml
+  - http://localhost:9080/NSI/discovery.xml
+
+
+### Step 0 NSI Domain knowledge
+
+#### Assumptions:
+
+  - TLS is not enabled.
+  - running locally and exposed 9080 locally.
+  - hostname is set to dockertest.net:2021 or similar value in the format of:
+
+```
+{domain_name}:year
+```
+
+In our example and sample file we use `dockertest.net:2021`
+
+#### URN
+
+All resources are mapped using a URN pattern.  
+
+http://localhost:9080/NSI/dockertest.net:2021:topology.nml.xml will show you your current topology.
+
+Resources are reference by URN which are in the following format:
+
+`<prefix>:<organization>:<type>`  example value is: `urn:ogf:network:dockertest.net:2021:topology:ps#vlan=1780`
+
+ - prefix:  should be `urn:ogf:network`
+ - organization: <domain_name>:year
+ - type: in our example would `topology`
+ - resource: <name>#<label={vlan or mpls}>=<ID aka 1780>
+ 
+More info can be found in the [config](config.md) documentation.
+
+#### Selecting Source / Destination
+
+## Reservation: Step 1
+
+NOTES: Currently the -s and -d strip away the prefix.  Please be aware when using the CLI client.
+
+```sh
+onsa reserve \
+    -u http://localhost:9080/NSI/services/CS2 \  ##service from Docker 
+    -g urn:uuid:d7a6a2ff-2cb5-4892-8bec-2a50140a6342 \ ##Global ID
+    -s "dockertest.net:2021:topology:ps#vlan=1780" \  ## Source
+    -d "dockertest.net:2021:topology:port1#vlan=1787" \  ## Destination
+    -b 100 \  # bandwidth in Megabits
+    -a 2022-09-24T20:00:00 \  #start date/time (has to be in the future)
+    -e 2022-09-24T21:00:00 \  ## end date/time (again in the future)
+    -p dockertest.net:2021:nsa \  ## provider
+    -r dockertest.net:2021:sense \ ##requested 
+    -h 192.168.1.64 \  ## OpenNSA Server host (localhost won't work if using docker)
+    -o 8543 \  #Port 
+    -v \  ## verbose
+    -q ##dump payload message
+```
+
+### Query Validation
+
+We're going to query the data for the reservation we just created.
+
+```sh
+ ./onsa query \ 
+ -u http://localhost:9080/NSI/services/CS2  \ 
+ -p "dockertest.net:2021:nsa"  \
+ -r "dockertest.net:2021:sense" \
+ -h 192.168.1.64 -o 8543 \
+ -q
+```
+
+Output:
+
+```
+Connection   DO-8108e03315 (urn:ogf:network:dockertest.net:2021:nsa)
+Global ID    urn:uuid:d7a6a2ff-2cb5-4892-8bec-2a50140a6342
+Description  Test Connection
+States       ReserveStart, Released, Created
+Dataplane    Active : False, Version: 0, Consistent False
+Start-End    2022-09-24 20:00:00 - 2022-09-24 21:00:00
+Path         dockertest.net:2021:topology:ps?vlan=1780 -- dockertest.net:2021:topology:port1?vlan=1787
+Bandwidth    100
+Direction    Bidirectionall
+```
+
+## Provision Step 2
+
+We'll need the Connection ID from the query above for this step.
+
+```sh
+./onsa provision \ 
+    -c  DO-8108e03315 \  ## Connection 
+    -u http://localhost:9080/NSI/services/CS2 \
+    -p "dockertest.net:2021:nsa" \
+    -r "dockertest.net:2021:sense" \
+    -h 192.168.1.64 -o 8543 \
+    -v -q
+```
+
+Same Query as above should now show a new state of: 
+
+```
+States       **ReserveHeld**, Provisioning, Created
+```
+
+# Clean up Operations
+
+## Release Step 3 
+
+```sh
+./onsa release \ 
+    -c  DO-8108e03315 \  
+    -u http://localhost:9080/NSI/services/CS2 \
+    -p "dockertest.net:2021:nsa" \
+    -r "dockertest.net:2021:sense" \
+    -h 192.168.1.64 -o 8543 \
+    -v -q
+```
+
+## Terminate Step 4
+
+```sh
+./onsa terminate \ 
+    -c  DO-8108e03315 \ 
+    -u http://localhost:9080/NSI/services/CS2 \
+    -p "dockertest.net:2021:nsa" \ 
+    -r "dockertest.net:2021:sense" \
+    -h localhost -o 8543 \
+    -v -q
+``` 
+
+

docs/cli.md → docs/onsa_cli.md

-Open NSA CLI
------------
+# Open NSA CLI
 
 A short primer on the onsa command line tool.
 

docs/rest-interface.md

@@ -23,7 +23,7 @@ In [service] section add `rest=true`
 
 ### Create a connection
 
-Example minimal json payload to create connnection:
+Example minimal json payload to create connection:
 
 ```json
 {
@@ -59,13 +59,13 @@ curl -X POST -d "PROVISION" http://localhost:9080/connections/TE-03b16eea46/stat
 It will return an ACK, and start working on provisioning the link.
 The link will be up and ready to use when the `provision_state` is `Provisioned` and `data_plane_active` is `true`.
 
-### Terminatning a connectiond
+### Terminating a connection
 
 ```
 curl -X POST -d "TERMINATE" http://localhost:9080/connections/TE-03b16eea46/status
 ```
 
-The conneciton will then go into `lifecycle_state` `Terminating`, and when everything is released it will end up in `lifecycle_state` `Terminated`.
+The connection will then go into `lifecycle_state` `Terminating`, and when everything is released it will end up in `lifecycle_state` `Terminated`.
 
 ### Other supported status operations