Go to the top of the directory where the rift-python repository was cloned (in this example we assume it was cloned into your home directory):
$ cd ${HOME}/rift-python
Make sure your virtual environment is activated. See installation instructions for instructions on how to setup your virtual environment.
$ source env/bin/activate (env) $
Start the rift package:
(env) $ python rift Command Line Interface (CLI) available on port 61375
As explained in the Command Line Interface (CLI) documentation, you can Telnet to the reported port number (61375 in the above example) to access the CLI.
Press Control-C to stop the RIFT protocol engine:
(env) $ python rift
Command Line Interface (CLI) available on port 61375
^C
Traceback (most recent call last):
File "main.py", line 47, in
rift_object.run()
File "/Users/brunorijsman/rift/rift.py", line 61, in run
scheduler.scheduler.run()
File "/Users/brunorijsman/rift/scheduler.py", line 32, in run
rx_ready, tx_ready, _ = select.select(self._rx_sockets, self._tx_sockets, [], timeout)
KeyboardInterrupt
The command-line option "-h" or "--help" displays help text about the available command-line options:
Example:
(env) $ python rift --help
usage: rift [-h] [-p | -n] [-l LOG_LEVEL]
[-i | --telnet-port-file TELNET_PORT_FILE]
[--multicast-loopback-enable | --multicast-loopback-disable]
[configfile]
Routing In Fat Trees (RIFT) protocol engine
positional arguments:
configfile Configuration filename
optional arguments:
-h, --help show this help message and exit
-p, --passive Run only the nodes marked as passive
-n, --non-passive Run all nodes except those marked as passive
-l LOG_LEVEL, --log-level LOG_LEVEL
Log level (debug, info, warning, error, critical)
-i, --interactive Start Command Line Interface (CLI) on stdin/stdout
instead of port
--telnet-port-file TELNET_PORT_FILE
Write telnet port to the specified file
--multicast-loopback-enable
Enable IP_MULTICAST_LOOP option on multicast send
sockets
--multicast-loopback-disable
Disable IP_MULTICAST_LOOP option on multicast send
sockets
If you start the RIFT protocol engine without any command-line arguments it starts a single RIFT node which runs on Ethernet interface "en0".
Note: en0 is the name of the Ethernet interface on a Macbook. A future version of the code will pick the default Ethernet interface in a more portable way.
You can provide the name of a configuration file when you start the RIFT protocol engine:
(env) $ python rift topology/two_by_two_by_two.yaml Command Line Interface (CLI) available on port 49178
The configuration file specifies a specifies the configuration attributes for the RIFT protocol instance, including the attribute of the RIFT node and the RIFT interfaces.
It is also possible to configure multiple RIFT nodes in the configuration file. This is used to build simulated network topologies that can be tested on a single physical computer. In the above example, the configuration file "two_by_two_by_two.yaml" contains 10 simulated nodes with names core_1, core_2, agg_101, agg_102, etc.
By default, when you start the RIFT engine, it reports a port number on which it is listening for incoming Command Line Interface (CLI) sessions:
(env) $ python rift topology/two_by_two_by_two.yaml Command Line Interface (CLI) available on port 49697
You can connect to the CLI using Telnet using the reported port:
$ telnet localhost 49697 Trying ::1... telnet: connect to address ::1: Connection refused Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. agg_101>
This mode of operation is called the non-interactive mode because the RIFT engine does not interact directly with the user; all interactions happen through a Telnet session. As a result, the RIFT engine can run as a daemon.
The command-line option "-i" or "--interactive" runs the RIFT engine in interactive mode. In the interactive mode it is not possible to connect to the RIFT engine using Telnet; instead the RIFT engine itself provides the CLI on stdin and stdout:
(env) $ python rift --interactive topology/two_by_two_by_two.yaml agg_101>
As mentioned above, by default, when you start the RIFT engine, it reports a port number on which it is listening for incoming Command Line Interface (CLI) sessions:
(env) $ python rift topology/two_by_two_by_two.yaml Command Line Interface (CLI) available on port 49697
You can use the --telnet-port-file filename option to write this port number to a file instead of reporting it on stdout. This is useful when using a script to connect to the RIFT engine.
For example, you can start the RIFT engine in the background:
(env) $ python rift --telnet-port-file /tmp/rift-telnet-port topology/two_by_two_by_two.yaml < /dev/null & [1] 20717 (env) $
You can then connect to the RIFT engine as follows:
(env) $ telnet localhost $(cat /tmp/rift-telnet-port) Trying ::1... telnet: connect to address ::1: Connection refused Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. agg_101> agg_101>
The command-line option "-p" or "--passive" runs only those RIFT nodes in the configuration file that are marked as "passive".
The command-line option "-n" or "--non-passive" runs only those RIFT nodes in the configuration file that are not marked as "passive".
These two command line options are intended for interoperability testing between Python RIFT (this implementation) and other implementations that also understand the same configuration file format, such as the Juniper RIFT implementation. Both implementation can read the same configuration file; one implementation can run the passive nodes and the other implementation can run the non-passive nodes.
(env) $ python rift --passive topology/two_by_two_by_two_ztp.yaml Command Line Interface (CLI) available on port 52482
If the RIFT engine runs a multi-node topology on a single host, then every multicast packet which is sent by a node on the host needs to be received exactly once by another node running on the same host.
When a node sends a single multicast packet on a transmit socket, it may be received zero times, one time, or two times on a receive socket on the same host.
The exact behavior depends on a number of factors:
-
Whether or not the IP_MULTICAST_LOOP socket option is enabled on the sending socket.
-
The make, model, and configuration of router to which the host is connected.
-
Possibly also the operating system running on the host.
See this StackOverflow question for more details.
By default, the RIFT code uses an auto-detection mechanism to figure out whether or not it needs to enable the IP_MULTICAST_LOOP flag on transmit sockets.
The auto-detect mechanism uses the following rules:
-
First it disables the IP_MULTICAST_LOOP flag and sends a single multicast packet. It then checks how many copies of the multicast packet are received. If a single copy is received, it uses IP_MULTICAST_LOOP = disabled as the auto-detected value.
-
Otherwise it enables the IP_MULTICAST_LOOP flag and sends a single multicast packet. It then checks how many copies of the multicast packet are received. If a single copy is received, it uses IP_MULTICAST_LOOP = enabled as the auto-detected value.
-
If any other behavior is observed it generates an assertion failure with a message describing the observed behavior.
The auto-detection mechanism takes between 1 and 2 seconds to complete, which causes a noticeable delay during startup.
You can use the following command-line options to disable the auto-detection mechanism (and hence avoid the startup delay).
The command-line option "--multicast-loopback-enable" forces IP_MULTICAST_LOOP = enabled.
The command-line option "--multicast-loopback-disable" forces IP_MULTICAST_LOOP = disabled.
The RIFT protocol engine writes log messages to the file rift.log in the same directory as where the RIFT protocol engine was started.
Note: when the RIFT protocol engine starts, it does not erase the existing rift.log file, it just appends to it. If you log at level DEBUG (see below) the rift.log file can become extremely large and fill up your disk. It is recommended to configure log rotation (e.g. using Linux logrotate).
It is useful to monitor the log file as the RIFT protocol engine is running using the tail -f command:
(env) $ tail -f rift.log 2018-07-29 13:03:20,682:INFO:node.fsm:[2001] Start FSM, state=COMPUTE_BEST_OFFER 2018-07-29 13:03:20,682:INFO:node.fsm:[2001] FSM push event, event=COMPUTATION_DONE 2018-07-29 13:03:20,682:INFO:node:[2002] Create node 2018-07-29 13:03:20,682:INFO:node.if:[2002-if_2002_201] Create interface 2018-07-29 13:03:20,682:INFO:node.if.fsm:[2002-if_2002_201] Create FSM 2018-07-29 13:03:20,682:INFO:node.if:[2002-if_2002_202] Create interface 2018-07-29 13:03:20,682:INFO:node.if.fsm:[2002-if_2002_202] Create FSM 2018-07-29 13:03:20,683:INFO:node.fsm:[2002] Create FSM 2018-07-29 13:03:20,683:INFO:node.fsm:[2002] Start FSM, state=COMPUTE_BEST_OFFER 2018-07-29 13:03:20,683:INFO:node.fsm:[2002] FSM push event, event=COMPUTATION_DONE 2018-07-29 13:05:38,323:INFO:node:[1] Create node 2018-07-29 13:05:38,324:INFO:node.if:[1-if_1_101] Create interface 2018-07-29 13:05:38,324:INFO:node.if.fsm:[1-if_1_101] Create FSM 2018-07-29 13:05:38,324:INFO:node.if:[1-if_1_102] Create interface 2018-07-29 13:05:38,325:INFO:node.if.fsm:[1-if_1_102] Create FSM ...
By default, the RIFT protocol engine only writes log messages at severity INFO and higher to the log file. This eliminates log messages at severity DEBUG which are used to report very common non-interesting events such timer tick processing, receiving and sending periodic messages, etc.
The command-line option "-l LOG_LEVEL" or "--log-level LOG_LEVEL" logs messages at the specified LOG_LEVEL or higher. Valid values for LOG_LEVEL are debug, info, warning, error, or critical.