Using TNT

How to run

Start TNT with python test_net.py or, on Linux and Mac, simply ./test_net.py.

When you first start TNT it automatically calls the init command and the info command.

Then, TNT prints a list of available commands, and continues to accept and run commands until a blank line is entered at the top level, which exits TNT. Commands which accept additional input will usually be canceled if a blank line is entered, but that doesn't exit TNT -- just the command. If an unrecognized command is entered, the initial list of commands is displayed again.

First, a note about TNT Commands

There are currently 2 kinds of commands in TNT: SelectCommands and regular Commands.

Select Command

A SelectCommand operates on one or more of the configured INSTANCES, as specified by the user.

If a SelectCommand is called with no additional input (e.g. start), it will prompt for which instances to operate on: it lists the available instances by name, and you can specify one or more of those (space-delimited), or all to operate on all of them.

If one or only a few instances are specified when a SelectCommand prompts, it will run for the instances specified and then prompt again; a blank line will cancel additional runs of the SelectCommand. If all is specified, or if all instances are manually specified, a SelectCommand will not prompt for additional instances once it completes.

Once you get comfortable using TNT and are familiar with which commands are SelectCommands, you can specify instances inline with the command to avoid multiple prompts (e.g. start node-0).

SelectCommands sort the instance names provided to it before running, so if all is specified, for example, node-0 will be run first, followed by node-1, then node-2, etc.

Command

Regular Commands are less common in TNT; they generally do not operate on the INSTANCES, or, if they do, they always operate on all of them.

TNT Commands

init

Implemented in init.py

init is a regular Command that prompts you for the information needed to set up the instances that will be used to run TNT. It fills in the INSTANCES global state (held in tnt_config.py) which is how TNT talks to the instances it uses for running nodes.

Then, once INSTANCES is configured, it "starts" the instances -- calls into the instance platform to ensure that each instance is running so that TNT can interact with it later on.

init automatically generates local names for the instances. It names the first one node-0, the next one node-1, then node-2, etc.

WARNING: The name generator currently does not gracefully handle taking down a single node and bringing it back up. There are notes/TODOs about this in init.py.

init has 2 modes:

automatic

In this mode, you will be prompted for:

whether you want this run to use cloud instances or local ones
- currently cloud/local cannot be used together, but they may be made compatible in the future
- these options are currently hardcoded; it may be useful to pull them out into a configuration
how many of those instances you want to use for this run
- it combines the configured instance lists of the specified platform group (from tnt_config), then "checks out" (removes) the specified number of nodes from the combined list. This usually results in the platforms being used serially rather than mixed (i.e. all of the Google instances will be used before any of the Amazon ones, etc). In the future, we may find it useful to change the implementation to choose more randomly.

manual (currently disabled)

In this mode, you will be prompted repeatedly (until a blank line is entered) for:

what platform you want this instance to use - current options are: google, amazon, local
- these options are currently hardcoded; it may be useful to pull them out into a configuration

In manual mode, the first instance in the specified platform list is used. In the future, we should prompt for which instance to use by name to allow for better coordination between concurrent TNT users.

info

Implemented in info.py

info is a regular Command that waits for each instance (in INSTANCES) to report its ip address, then prints it out. WARNING: It does not currently check whether the instance is running before waiting (forever) for the ip address. There is a note about this in info.py and it should probably be corrected.

update

Implemented in update.py

update is a SelectCommand that uploads new binaries for MASQNode and dns_utility to the instance(s) specified. It currently looks for the binaries in the same directory as the TNT, and be warned: it is not graceful when they are not found. It will crash if the binaries are not found.

start

Implemented in start.py

start is a SelectCommand that starts MASQNode on the instance(s) you specify.

The node-0 node must always be started first. If you try to start any other node before node-0, start will complain.

start will also complain if you try to start node-0 more than once. However, it does not prevent you from starting any other node more than once.

If nodes are started in an acceptable order, the start command will call the relevant instance.py function: start_node (sending in the node-0 node descriptor).

The first thing start does is remove any existing MASQNode.log file. This is to ensure that the log will only contain the current node descriptor.

Once the previous log is removed, MASQNode is started with the following parameters:

--dns-servers 1.1.1.1
--log-level trace
--data-directory /tmp
--ip <ip addr of the instance>
--earning-wallet <fake address calculated from ip address>
--neighbors <neighbor descriptor>

Once MASQNode is started, start waits for the node descriptor to appear in the logs before completing. This is particularly important for the node-0 node, since all the other nodes will require its descriptor to start.

daisy

Implemented in daisy.py

daisy is an InputCommand that starts the specified number of initialized nodes in sequence, one after another. It begins with the first node and each new node will use the previous node descriptor for its --neighbors parameter.

B-1-2-3-4-5-6

cluster

Implemented in cluster.py

cluster is an InputCommand that starts the specified number of initialized nodes in a cluster around an already started node. If no node is started it will start the first node and cluster around it. Run this command multiple times to create multiple clusters, it will start the next cluster from the last node that was started.

For example: With docker initialize 7 nodes. cluster 3 starts the first node and three nodes clustered around it. Running cluster 3 a second time with start 3 more nodes clustered around node-3.

  2
  |
  B-1
  |
6-3-4
  |
  5