Welcome to the second API tutorial. In this tutorial, you will use the CLI to create your first topology, populate it with elements and a connection, start it, access the console, and then tear it down.
Please connect a CLI to the API in order to continue.
Creating a topology is easy: simply run
The return value of
topology_create is the topology info of the new topology.
Not all functions in the ToMaTo API are idempotent. When executing an API call, think about its effects first!
Oh no! You forgot to store the result of this API call in a variable! - No problem, the result of the last call can always be accessed as
We will need the topology ID very often, this is why we store it here. Note that new topologies are initialized with a timeout of one hour. We don’t want to learn while having time preasure, so we should increase the timeout. Renewing a topology is an action.
This will set the topology timeout to two days in the future.
The syntax for actions is always the same. The functions
element_action take the arguments
(id, action_name, kwargs) where
action_name is a string constant, and
kwargs is a dictionary.
We should assign a nice name to the topology, so that it will have a meaningful name in the topology list.
This looks way better.
The syntax for modify functions is always the same. The functions
account_modify and so on take two arguments, the first being the id of the entity that should be modified, and the second being a dictionary. This dictionary only contains the attributes that should be changed.
Our topology is empty, so we should now create two devices. We create two container-based devices with the default template.
create functions usually return the created entity’s info. Also, most
create functions accept an optional
args argument, which has the same functionality as in the
The newly created elements do not have positions in the workspace assigned to them. When you open the topology, the editor will randomly set positions. You can use the
_pos attribute to select positions: It is a dict containing two coordinates, each is a float between 0 and 1.
Now, we should connect these elements. While the editor automatically creates interfaces for us, we have to do this manually here.
Then, we can connect the two interfaces:
We don’t need to pass the topology ID to
connection_create as the topology is already defined by the elements. You cannot connect elements from different topologies.
We can use the topology start action to start the whole topology:
This function call will block until everything is started.
You can use the editor to access the devices’ console to see for yourself that the devices are properly connected to each other.
ifconfig you may notice that our devices do not have IP addresses assigned to them. We simply forgot this. Luckily, we can do this while the devices are running:
Now, we can run a ping test between the devices.
Old topologies that are still running waste a huge amount of resources. Be fair and clean up after your experiments.
We should now stop and remove our topology.
You can simply run
topology_action(top_id, "destroy") instead of doing this manually. This was just for demonstration purposes.
topology_remove will recursively remove all child elements and connections.
You have now learned how to use the API to conduct experiments.
By now, you should have understood the meaning and basic syntax of the different
In the next tutorial, you will learn how to import a topology and upload an executable archive via the CLI.