The Command Line Interface (or CLI) is contained within a class named TextUI. To start the CLI simply run the file named 'runCLI.bat' (in Windows) included in Public Release 1 which will invoke the TextUI class.
The Java Firewall Simulator CLI is just like any other CLI. Simply type a command in and press enter. Start by typing help to display a list of available commands. You can then get additional help on each command by providing an additional parameter help <command>. For example:
help ADDINTERFACETOLINK
The commands are case insensitive so you can type:
help addinterfacetolink
to achieve the same result.
There are also shortcuts to many of the commands for example after you've typed help addinterfacetolink. The first line of text displayed is:
*** ADDINTERFACETOLINK (ADDI)
You can also use the command in parantheses ADDI instead of ADDINTERFACETOLINK. So we can go:
help addi
or
addi pc1 eth0 Link1
the same applies to many other commands, if you think a command is too long, use the help feature to find the shortcut for it.
When the CLI starts, it already creates a Simulation for you. But we can't do anything interesting yet. We need to set up a networking environment. If you can imagine we have an empty room or building (our Simulation), in order to do any networking type stuff we will need PCs, Switches, Routers and plenty of cable. We also need networking software Protocols on each device so they can talk to each other. The same principles apply in our Simulation.
Our first step in setting up a networking environment is to add some Nodes. There are currently 2 different Nodes we can add to our Simulation, PC and Router. To add PCs to our Simulation we use the command:
ADDPC <name>
where name is the name you want to give to the PC. You will ofcourse need more than 1 PC in order to simulate a network. Example:
ADDPC pc1
addpc pc2
You can also add Routers to the Simulation using:
ADDROUTER <name>
Now that we have some Nodes in our Simulation they will need NIC's (Network Interface Cards) or similar in order to be able to connect with each other. We call these NIC's Network Interfaces.
By default when adding a PC Node using ADDPC, a NetworkInterface named eth0 is added to the PC automatically.
However, after adding a Router to the Simulation you need to add the Network Interfaces to the Router manually. A Router can have many Network Interfaces. To add a Network Interface we use the command:
ADDINTERFACE <interfacename> <nodename>
For example:
ADDINTERFACE eth1 router1
To display the Nodes you have added to the Simulation and their Network Interfaces use the command:
DISPLAYNODES
Remember: The addpc command also adds a default NetworkInterface to the PC named eth0.
After adding some Nodes, we need to connect them somehow. If we think back to our empty room, we now have a room with PCs and/or Routers in it, each PC has 1 NetworkInterface and each Router can have many. But there is no cable connecting our Nodes together. So we need to add a Link with the following command:
ADDLINK <name>
where name is the name you want to give to the Link. You can think of a Link as a piece of cable that can be plugged into many NetworkInterfaces. However, this command simply creates the piece of cable, it's not connected to anything yet, so we need to "plug it in" to each NetworkInterface that we want. We do this with the following command:
ADDINTERFACETOLINK <nodename> <interfacename> <linkname>
where nodename is the name of the Node, interfacename being the name of the Network Interface (eth0 on PC nodes) to plug our link into, and linkname being the name of the Link to plug into the specified Network Interface.
Example:
ADDINTERFACETOLINK pc1 eth0 link1
The above command will connect the Link named link1 to the Network Interface (eth0) of the PC named pc1
To display all of the Links in the Simulation and their connected NetworkInterfaces you can type:
DISPLAYLINKS
Ofcourse, each Link needs to be connected to at least 2 NetworkInterfaces, no use having a cable running from 1 PC to nowhere. However, if you do try sending something to nowhere, the Simulation will still try to send it, so you may like to try to send something to nowhere to see what happens.
There's one more step in setting up our environment. We need to set the addresses of the Nodes. Each Network Interface of a Node has an IP address associated with it. Our Routers can have many IP addresses, one for each Network Interface. By default when we created our Network Interfaces a default IP was set 192.168.0.1. We'll need to change this so we have no duplicates. We use the following command:
SETADDRESS <nodename> <interfacename> <address>
Example:
SETADDRESS pc1 eth0 192.168.0.5
If you don't set these addresses a warning will be given about duplicate IP address errors before you attempt to send anything (by running the script, more on that later). You can continue to attempt to send something, but beware anything could happen! In the real world if you set 2 different Nodes IP addresses to the same IP, many conflicts arise. It's the same in our Simulation.
We still haven't mentioned how Nodes are going to talk to each other. At the moment all of the Protocols required for Nodes to communicate are set up automatically for you (either when you add a Node or add a Network Interface to a Node) so you don't have to worry about a thing. However, in the future the Simulation will support different sets of Protocols that you could use.
Now that we've set up our networking environment we can now send something from 1 PC to another. To do this, we add commands to a Script which is contained in the Simulation. When the Script is run, every command in the Script is executed by the Simulation. Currently the Simulation only contains one Script.
At the moment there's only one command that the Script can execute, SENDAPPDATA. This sends an ApplicationData message from one Node to another. You can think of an ApplicationData message as any block of data that might be sent by an Application, such as an HTTP GET request from a web browser. We can however add as many SENDAPPDATA commands to the Script as we like. The syntax for the command is as follows:
SENDAPPDATA <source nodename> <destination address> <AppData name> <AppData data>
The source nodename is the name of the Node that you want to send data from. destination address is the IP address of the destination PC that you want to send the data to. AppData name is just a name to give the ApplicationData message and AppData data is the actual data sent by an Application.
Example:
SENDAPPDATA pc1 192.168.0.4 Message1 HTTP GET http://jfirewallsim.sourceforge.net/
After adding a command to the Script you can display the Script's contents with the command:
DISPLAYSCRIPT
You can remove a specific line from the script with the command:
REMOVECOMMAND <line number>
where line number is the line in the script you wish to remove. You can also remove all contents from the script with the command:
CLEARSCRIPT
After we have at least 1 command in the Script we can then run it by using the command:
RUNSCRIPT
Before the script runs checks are done on the Simulation environment to make sure you set things up properly. If problems are found a warning message is given, you have the choice to continue to try and run the Script or go back and correct the problems. Let's look at an example, say we've just started the program, we've got a new Simulation with nothing in it and we type the following commands:
addpc pc1
addpc pc2
sendappdata pc1 192.168.0.5 message1 HTTP GET http://jfirewallsim.sourceforge.net/
runscript
We'll get an error message like so:
There were problems in the Simulation environment
-------------------------------------------------
Warning: NetworkInterface 'eth0' of Node 'pc1' is not connected to a Link
Warning: NetworkInterface 'eth0' of Node 'pc2' is not connected to a Link
Duplicate IP Error: 192.168.0.1 in Node: pc2 is already contained in Node: pc1
Continue to try to run the script anyway? (Yes/No)
You can still try to run the script. But unexpected results could possibly occur, this wasn't tested thoroughly.
Checking is also done on commands contained in the Script. If errors are found the Script will not run. It is possible to enter incorrect sendappdata commands. However, the Simulation will not let you run those incorrect commands.
For example, if we have a script with the following commands:
sendappdata This_is_not_an_existing_node 192.168.0.5 message1 blah blah blah
sendappdata pc1 This.is.not.a.real.IP.address message2 blah blah blah
If we then try to call runscript the script will not run and error messages containing the reasons why will be displayed.
Assuming there are no errors in our environment or in the script commands, the commands contained in the script will execute and a send process will begin for each sendappdata command.
The CLI will then output ALOT of information which a part of may look like this:
Ethernet: Received Packet: Packet from: TcpIp
Ethernet Sending Packet: Packet to eth0
eth0: Received Packet: Packet from: Ethernet
eth0 Sending Packet: Packet to link1
link1: Received Packet: Packet from: eth0
Basically, each Object in the Simulation, the Node, each Protocol, NetworkInterface and Link splits, passes around, checks, adds headers to and manipulates the original data sent from the Application until eventually it gets to it's destination. This mimics the way real world networks operate. To fully understand and appreciate all of the processes involved from sending a simple packet look up some networking resources online. See the Networking-concepts-HOWTO (if the link is broken do a google search). This page briefly explains the different layers in the OSI and TCP/IP networking models.
There is currently one option that can be used when running the Script. By default, each command in the Script is run simultaneously, that is, at the same time. By default each send process triggered by the SENDAPPDATA command will run at the same time through the use of Threads. You can toggle this option to instead run sequentially. Each command in the script will then run one at a time. The 1st command will run, once it is finished, the 2nd command is run, once the 2nd is finished the 3rd will run and so on and so forth. To toggle these options use the following commands:
RUNSEQUENTIALLY
RUNSIMULTANEOUSLY
Here's our OSI and TCP/IP networking models.
The Simulation has a feature that wraps up all of the information contained at each layer during a send process and stores it.
After we run the Script, the Simulation stores the information about what happened at each Layer of the send process (or processes, depending on the number of commands in the Script) in a sequential fashion. The CLI can then retrieve this information one step at a time. So, after running a script, use the command:
DISPLAYINFO
This displays the Information for the next layer of the sending process. The first time you type it will be the first Layer of information stored by the Simulation.
We can retrieve all of the information in a timely manner by using the command:
DISPLAYALLINFO
This will get the next Layer of information from the Simulation and display it every 5 seconds by default. We can slow this process down or speed it up by using the command:
SETTIMER <seconds>
where seconds is the delay between retrieving and displaying each Layer of information. We can also stop the DISPLAYALLINFO command by using:
STOPINFO
This Layer information feature was included mainly for a GUI, although a more advanced CLI could well take advantage of it. The idea is that the GUI will be able to retrieve each Layer of information from the Simulation whenever it wants through user input (like a "Next" button) or via Timers. The GUI can then display the information how it wants.
Note: The Layer Information is reset each time the script is run. So if there is still Information in the Simulation it will be removed and replaced if the Script is run again.
The Routers in our Simulation environments contain routing tables. These routing tables are configured automatically each time the Script is run. We can also configure them manually ourselves before running the script by using the command:
CONFIGUREROUTERS
We can then display the routing tables of every Router in our Simulation with:
DISPLAYROUTINGTABLES
The Routers update their routing tables in a way that's very similar to RIP (Routing Information Protocol) but without actually sending any Packets. The routing ability in the Simulation is in it's early stages (in public release 1), some of the fields in the routing table are not used yet and features such as subnet masking are not implemented. But the routing works and you can send something from one PC to another PC with many Routers in between and the Packet will reach it's destination.
In public release 1 of our Java Firewall Simulator there were a number of test scenarios set up by us developers to test various things. The scenarios are as follows:
To set up one of these test environments simply type one of the following commands after starting the program:
test
test2
test3
test4
You must restart the CLI each time you want to set up a new test scenario.
A warning about test2, or scenario 2. This scenario was set up to test a certain issue with the routing. Use at your own risk, if you try to run a script using this scenario get ready to hit CTRL-C.
Author: Tristan Veness
Version: 1.0
Date: 18 June 2004