User Manual

Setting Up A Go Workspace

The first thing you need to do is install golang. A guide for this can be found here: Getting Started With Go

Once you complete this tutorial, you should have a workspace directory for go, pointed to by $GOPATH. This directory should contain a src/, bin/, and pkg/. If they are not there, create them. Once golang is installed and you have this directory, with $GOPATH pointing to it, and $GOBIN pointing to the /bin directory within it, you are ready for the next step.

Setting Up A redis Database

Download, compile, and install redis. Use redis-server to start a local instance of the redis server, and use redis-cli to talk to the redis server using the command line. To check if the redis server is working by typing redis-cli ping. It will return PONG if it is running. To save your data base use redis-cli shutdown to save the server.

To create a server to be accessed not only no your machine follow these steps. Make sure that the redis server and cli executables are in /usr/local/bin . Also create a directory to store your config files and data, /etc/redis /var/redis. Copy the init script that you'll find in the Redis distribution under the utils directory into /etc/init.d. We suggest calling it with the name of the port where you are running this instance of redis. Make sure to modify the REDISPORT according to the port you are using. The pid file path and the configuration file name depend on the port number.

Run this command to copy a template file into /etc/redis using sudo cp redis.conf /etc/redis/6379.conf. Create a directory inside /var/redis that will work as data and working directory for your working redis instance name it the name of your port.

Edit the configuration file, making sure to perform the following changes:

Set daemonize to yes (by default it is set to no).

Set the pidfile to /var/run/redis_6379.pid (modify the port if needed).

Change the port accordingly. In our example it is not needed as the default port is already 6379.

Set your preferred loglevel.

Set the logfile to /var/log/redis_6379.log

Set the dir to /var/redis/6379 (very important step!)

Finally add the new redis init script to all the default runlevels using the following command: sudo update-rc.d redis_6379 defaults You are done! Now you can try running your instance with: /etc/init.d/redis_6379 start

This was created by using the official redis quick start guide which can be found at this link, http://redis.io/topics/quickstart.

Installing The Code

Assuming that your golang install is correct and you have set up a redis database, you will need to install one more thing before running our code, dot a program for visualizing graphs. Dot may be found at http://www.graphviz.org/ for all platforms, alternatively packages for dot are available on most linux distributions. Once you have dot you may download the file install.sh from this repository (available on the topmost level), and run it in your terminal using ./install.sh The install will take some time, but once it is complete, you will be able to run the client in all its glory. If you are not on a platform that supports shell scripts of this file type you may read this file and use its contents as a set of instructions/list to install the appropriate packages necessary to build this project.

Writing A Topology File

To use the client, you're going to need a topology file. You can write one of these very easily yourself. Simply write a text file with the following form describing each edge:src dst cost where src is the label for the source node, dst is the label for the destination (both strings of any kind), and cost is a positive integer representing a cost, with tabs separating them all.

For example,

1 2 3 describes an edge from nodes 1 to 2 with a weight or cost of 3.

purple red 1.5 describes an edge from nodes purple to red with a weight or cost of 1.5

Since graphs are undirected, each path should only be entered once.

Running the Client

To run the client, use go run $PATH_TO_CLIENT/client.go. Using the client (a command line utility) should be fairly straight forward as you will be prompted for all interactions. First you are asked for a databases ip address and port (redis' default is 6379). Next you will enter a topology name if it is present in the database you will be connected to it, if not you will have the option to create a new topology from a specified file with that name. After you have been connected to a database (preexisting or newly created) you will be asked if you wish to find a shortest path, if you do you will enter a source and destination node label, and if those labels are indeed in the topology the shortest path string will be returned in the format "s 1 2 3 ... d | l". In this string s is the source node label, 1 2 3 ... are the intermediate node labels, d is the destination label, and l is the length or cost of the path (sum of the weights of edges traversed on this path).

Running the Web-Interface

To run the web interface use go run $PATH_TO_WEBINTF/webintf.go, the program will then prompt you for an ip address to use to connect to the database. Once the interface knows what ip to connect to it will run and print "Ready." once this happens you may connect to the interface by entering "localhost:8080" into your browser of choices URL bar. This will bring you to a page enumerating all topologies currently in the database.

Upon selecting a specific topology you will be presented a graphical representation of the topology you selected who's nodes will be click-able.

Clicking a specific node will present you with a graph will add to your page a view of the neighbors of that node in another graph, as well as links with destination nodes to compute paths using the current node as a source. This graph will show the paths from source to destination by highlighting the source node red, destination node green, and intermediate nodes and edges blue. The destination node may be changed by choosing different nodes from the graph the current path is being displayed on. In general the majority of this interface should be fairly intuitive in the sense that destinations and sources are linked in mostly sensible places so if it looks like you can click a node in a certain graph then you probably know what it will do.

The layout for the web interface cascades in a way that was initially an error linking between pages, but as a result of the utility of being able to scroll down to asses the topology and source neighbors while viewing a specific path this was kept.

Notes And Troubleshooting.

If you need any help of any kind, please email [email protected], or submit an issue on this repository.