Documentation

Using gBuilder

As mentioned before, gBuilder is an effective tool in designing and experimenting with virtual networks. It provides a friendly user interface for configuring topologies followed by a simple compilation step to create the corresponding xml file needed by gLoader. It also handles running gLoader and provides an easy way of interacting with running devices within a topology. Many tools have been integrated into gBuilder to facilitate the creation of topologies, by providing automation and easy accessibility. This tutorial will explain how to use gBuilder as well as briefly describe the tools integrated into it.

Configuring gBuilder

All of the configuration options of gBuilder can be found under 'Config' on the main menu:
Environment Configuration
The 'DTD file' specifies the format of the xml file created by gBuilder and used by gLoader. The 'File System' is the file system used to run UMLs. These are already set by default to those included with GINI. It is not recommended to use any other files without first consulting the administrators of GINI.
Toggle ip/mac Auto-gen
This is a helpful tool for auto-computing ip and mac addresses at compilation so the user does not need to configure each element in the topology manually. It only requires that all subnet addresses are provided (e.g. the 'subnet' property for the Subnet element, and the 'subnet' property for Wireless access points). This feature is disabled by default, as it is important for students to first learn how to configure the elements manually before relying on auto-computation. It will also overwrite manually entered ip and mac addresses if present.
Toggle Auto-routing
This tool provides the ability to automatically compute routes, mainly for the use of Routers and connected UMLs. By default, it is enabled, although it is a good idea to learn this manually. If disabled, a table will show up under the properties of the affected elements so that the user can specify the routes from there.
Remote Distribution
Certain topologies can contain too many elements for one machine to run at once, so the remote distribution feature was designed to run elements remotely. In the remote configuration, the user will be presented with a list of devices in the current topology. With this list, one can distribute the devices to specified machines by right-clicking on an element and choosing where to send it. For any machine to receive an element, it must first be enabled, by clicking on the checkbox next to the name. The machine is specified in an scp-like fashion, where the format is username@hostname:directory (directory is where the data files will be placed). It is not required to specify the username if it is the same on the machine that the user is currently on, but it is still recommended to provide it anyway. For the remote distribution to work smoothly, it is required that ssh keys be set up (please speak with an administrator for help). There is a short test that is provided to verify that the remote machines are accessible. If ssh keys are not properly set up, then one or more of the machines may be prompting for a password (check the terminal that initially ran gBuilder). After the remote configuration is done, clicking 'OK' or 'Apply' will save the configuration into a file with the same name as the topology, but with an appended '_rdist'.

Making a topology

Modes
All of the basic New/Open/Close commands are provided in the 'File' menu. Running gBuilder by default will create a new canvas to create a topology on. With the components directly under the main menu, the user can click on one and place it on the canvas by clicking again. When a component is clicked, gBuilder begins an "adding" mode, where the user can then click several times to add multiple instances of the same component. To exit "adding" mode, the user can simply right click, and the cursor will change back to the normal one ("selecting" mode). To connect different components, the user can navigate to a component, press and hold the right click, and then drag it to its destination before releasing. The user can recognise the "connecting" mode by the cursor changing into a pencil, as well as a line appearing from the source to the user's current mouse cursor location. If the connection is successful, a line should appear between the two components. Whether components are connected or not, they are still movable from "selecting" mode. The user can hold left click over a component, drag it wherever and release it at the component's new location.
Component configuration
It is also possible to delete components, by right clicking on one and selecting 'Delete' from the popup menu. Note that deleting a component will also delete any connection lines associated with it. Another important option from the right click popup menu important for creating a topology is 'Properties'. This is where each component can be configured manually, mainly by specifying addresses. A quick way to view these properties without having to open the 'Properties' of a component is to move the mouse cursor over it and wait for an information popup to appear.

Connection rules

There are specific ways to connect GINI components. Provided below is a list of components and the corresponding components that they can be connected to
UML
Switch, Subnet, Bridge, Hub, Wireless_access_point
Router
Subnet, Wireless_access_point
Switch
UML, Subnet
Bridge
UML, Subnet
Hub
UML, Subnet
Wireless_access_point
UML, Mobile, Router
Subnet
UML, Switch, Router, Bridge, Hub, Firewall
Mobile
Wireless_access_point, Mobile
Firewall
Subnet
Additionally:

Compiling

When the topology is ready to be loaded into gLoader (the program that runs the devices), gBuilder must first provide the xml file, created by the 'Compile' option under the 'Compile' menu. The compiler will check that all the required properties are specified as well as address correctness and if all tests pass, the xml file will be created as filename.xml, where filename is the name of the current topology. The behaviour of the compiler will vary according to which settings (auto-gen or auto-routing) are enabled.

Running a topology

Run command
In general, there should only be one instance of gBuilder running per user on a machine (different users should work), and the rule is stricter for running topologies. Both gBuilder and gLoader will check for this, and they will not continue if another running topology is detected. If nothing is running and the topology compiled without error, then it is ready for the 'Run' option from the 'Run' menu. 'Run remotely' will use the previously mentioned Remote Distribution configuration to run the topology on multiple machines.
Running states
If the topology ran successfully (the log at the bottom of gBuilder will provide this information), then there should be a few colored lights appearing shortly. These lights represent the state of certain devices, specifically those that the user can now interact with by double clicking on them. Both the interaction and state are provided by a program called Screen (a virtual terminal) which can run other programs in attachable/detachable terminals. The corresponding device terminals are attached when the user double clicks on them and they are detached (but not killed) when the window is closed. These states are interpreted by gBuilder's Task Manager (described next) which creates the colored lights by the devices. The legend for the colored states is as follows:
green
running and attached screen
orange
running and detached screen
red
killed (not running)
Task Manager
The Task Manager was created to manage several (but not all) processes of a running topology. It is useful to those who are not familiar with unix process management or the processes created by GINI. When running a topology, there is no guarantee that each device will perform flawlessly, as with any process on a real machine. The Task Manager is there to provide control in the case of a device crashing, without the need of killing it from an outside terminal.
Device management
Generally, killing processes through the Task Manager should not be overused. gBuilder also provides the ability to stop or restart devices by right clicking on them on the canvas and choosing one of the corresponding options. Also, most of the devices provide the command-line ability to do so as well (halt/reboot). To stop a whole topology, the user can choose the 'Stop' option in the 'Run' menu. This is a required step if the user wants to start another or the same topology again, even if all processes related to the old topology were killed.
Statistics
Some of the devices can provide statistics, which can be accessed by the devices manually (through terminal commands) but gBuilder provides friendly user interfaces for two specific sets: graphs for the input and output queues of the Router, and the amount of packets sent, received and dropped for each Mobile (these can be accessed manually through the Wireless access point). The graphs can be viewed by right clicking on a Router (while running) and selecting 'Graph' from the popup menu. There are 4 graphs, one for the throughput of the output queue, one for the queue sizes of the output queue, one for the throughput of each input queue and one for the queue sizes of each input queue. As for the Mobile statistics, the user can move their mouse cursor over any Mobile on a running topology and a small popup should appear displaying TX packets (transmitted), RX packets (received) and Fading error rate (dropped). These statistics will vary according to distance from each other (next).
Mobility
The Mobiles have coordinates as part of their properties, which can be viewed by moving the mouse cursor over them. These coordinates correspond to the coordinates on the canvas and so they will change according to where they are moved, even while the topology is running. This will potentially affect the packet statistics of each Mobile. Note that these coordinates do not correspond to the those accessible from the Wireless access point. gBuilder must first transform the canvas coordinates relative to the location of the Wireless access point and then scale them down before inputting them into the Wireless access point.

Troubleshooting

Cleaning Mconsole
UMLs are launched with the support of a program called uml_mconsole. This program creates files used to manage UMLs, and is important in identifying and shutting them down. These files are created in a directory called .uml in the user's home directory. For example, if the user's name was 'bob', then the targetted directory to be cleaned is "/home/bob/.uml". Subdirectories are created with the name of the UML (eg. UML_1 would create the directory "/home/bob/.uml/UML_1", and the 'Clean mconsole' option from the 'File->Clean' menu will remove all of these. A good sign that the .uml directory requires cleaning is the presence of randomly generated folder names.
Cleaning .cow files
To share a single file system over multiple UMLs, GINI must create .cow files. In general, if a .cow file gets corrupted or the original file system gets changed, the UMLs will not work properly. If this is the case, then the 'Clean cow' option from the 'File->Clean' menu will take care of this, but for all UMLs. This will erase any configurations or data stored on each UML, which may not be necessary. If there are few UMLs to be cleaned, then the best option would be to delete the .cow files manually. The default location to store these .cow files is in '/home/bob/GINI/data/UML_#', where # is the identifying number in the name of a UML. The above also applies to Mobiles, which are just renamed UMLs.
Leftovers in a stopped topology
It is possible that running the stop command does not fully stop a topology. Certain elements may have overlooked the killing signals or there was a problem in identifying the device to send the signal to. The best way to fix this is by using the Task Manager, from which the user can see which processes have not been terminated properly. First the user should consider what type of device is not responding to signals. It is most likely a UML, which is an attachable device. If this is the case, then the user should first try to attach the device (given as an option in the right click menu of the Task Manager) and then shut it down manually using 'halt'. If this does not work, then the next step is to try killing it through the Task Manager, and if that is also unsuccessful, then the user will have to try and kill it through the command line. For non-attachable devices, killing through the Task Manager is the easiest way.
Pyro errors
Pyro stands for PYthon Remote Objects, which is used to communicate between gBuilder and the Task Manager so they can remain separate programs. Pyro errors are less obvious because exceptions occur remotely, and usually do not output very useful information for debugging. If this type of error occurs, simply close everything related to GINI (closing gbuilder should handle most of it) and start it back up again. If the same error occurs again, contact an administrator.