Starting, Stopping, and Listing Standard Emulations from the Command Line

You can use a command-line interface (CLI) with the Eggplant Network Emulator to control or get information about your network emulations. This page documents all the commands related to locating defined standard emulations, starting standard emulations, and stopping standard emulations. Standard emulations refers to emulations that are not scenarios (i.e., not changing between standard emulations over time).

Note: The examples on this page assume you're using the command-line Python script, epncli.py, which you can download from the Eggplant downloads page for Eggplant Network.

Listing All Defined Emulations

Standard emulations are defined (created and saved) in the web GUI. They can be launched through the LCD panel and the CLI/API. The question is what standard emulations are available. The following command lists all the saved standard emulations present on the Emulator.

Syntax:

--getDefinedEmulations [--type (ptp|multihop|profiled)]

This command lists all the currently defined standard emulations belonging to the --user {user} or those stored as public on the Emulator. If you include the optional filter argument --type, the command returns only the defined standard emulations for that particular type.

Output:

--names "{number of results};;{type 1};{name 1};{type 2};{name 2};{type 3};{name 3};..."

In the output, {number of results} is the number of defined standard emulations found on the Emulator for the user (this number includes public emulations that the user has access to).

Example:

$ python epncli.py --host 192.168.202.194 --user admin -password admin --getdefinedemulations

--names

12;ptp;3G_Slow_PoorQuality;ptp;Satellite_Slow_PoorQuality;multihop;Wan10MbpsToWan155Mbps;ptp;WAN_10Mbps_PoorQuality;ptp;2G_Slow_GoodQuality;multihop;WiFi56MbpsToADSLGood;ptp;ADSL_Medium_GoodQuality;ptp;LAN_No_Impairment;ptp;WiFi_56Mbps_PoorQuality;ptp;LAN_1Gbps_AvgQuality;ptp;4G_Slow_PoorQuality;ptp;SDSL_Slow_GoodQuality;

The output shows there are 12 standard emulations, and then lists them as type;name pairs.

Starting a Standard Emulation

To start any standard emulation, it must be present on the Emulator. Standard emulations are started by specifying a name and the port pair you want the standard emulation to start on.

Syntax:

--startEmulation {name} --portPair (0|1)

This command starts a standard emulation with the name specified on the specified port pair. If you're in doubt about names, you can get a list of defined standard emulations by using --getDefinedEmulations.

Output:

--ok if the named standard emulation is successfully started on the port pair.

--error <error message> if there is already a standard emulation on the port pair or named standard emulation doesn’t exist. The error message indicates the actual error.

Example:

$ python epncli.py --host 192.168.202.194 --user admin -password admin --startEmulation 3G_Slow_PoorQuality -portPair 0

--ok

And if you try again without stopping the first:

$ python epncli.py --host 192.168.202.194 --user admin -password admin --startEmulation 3G_Slow_PoorQuality -portPair 0

--error "Emulation is already running on port pair 0"

Note: If the standard emulation name contains a space, you'll need to put the name in quotes: –startEmulation "Mobile Test 1"

Stopping a Standard Emulation

The --stopEmulation command stops whatever emulation is running on the specified port pair. After stopping the emulation, no traffic passes on that port pair.

Syntax:

--stopEmulation --portPair (0|1)

If no emulation is running on the specified port pair, the command returns an error.

Output:

--ok if a running emulation is stopped successfully.

--error "<error message>" if there is no emulation running on the port pair.

Example:

With an emulation running on the specified port pair:

C:\Users\Lara>python epncli.py --host 192.168.202.194 --user admin --password admin --stopemulation --portPair 0

--ok

With no emulation running on the specified port pair:

C:\Users\Lara>python epncli.py --host 192.168.202.194 --user admin --password admin --stopemulation --portPair 0

--error "No emulation is running on the port pair"

Stop All Standard Emulations

The --stopAllEmulations command stops all emulations running on any port pair. It’s a good way of ensuring you’re back to the Emulator’s initial state with no emulations running.

Syntax:

--stopAllEmulations

Unlike --stopEmulation, this command always returns --ok even if there is no emulation running on any port pair.

Output:

--ok (in all cases)

Example:

C:\Users\Lara>python epncli.py --host 192.168.202.194 --user admin --password admin --stopallemulations

--ok

Show the Running Emulations

Shows you what emulations are running, either in total for all port pairs available, or for a specified port pair.

Syntax:

--getEmulationsByPortPair [--portPair (0|1)]

Without the optional parameter, the command lists the currently running emulations for port pair 0 (ports 0 and 1) and port pair 1 (ports 2 and 3). If you include the optional --portPair <number> parameter, the command returns only the emulations running on the port pair specified by <number>.

Output:

Without the --portPair <number> argument:

--emulations "{number of results};;{port pair id};;{emulation name};{port pair id};{ emulation name};;"

With --portPair <number> arguments:

--emulations "1;;{port pair id};;{name}"

Example:

C:\Users\Lara>python epncli.py --host 192.168.202.194 --user admin --password admin --getEmulationsByPortPair

--emulations "2;0;3G_Slow_PoorQuality;1;;"

The output shows that two emulations follow: First, port pair 0 is running 3G_Slow_PoorQuality. Then, port pair 1 is running nothing (;;).

List Compatible (Similar) Standard Emulations with a Started Emulation

This produces a list of all the standard compatible emulations started on a port pair.

Syntax:

--getCompatibleEmulations --startedOnPortPair (0|1)

For an emulation to be compatible with the current one, it must have the same links in the same positions. The links and endpoints do not need to have the same names or be in the same states (enabled/disabled). Multi-hop emulations are not compatible with single-hop emulations.

Sample Output:

--names "{number of results};{type};{emulation name};{type};{emulation name};"

Example:

C:\Users\Lara>Python necli.py --host 192.168.202.194 --user admin --password admin --getCompatibleEmulations –-startedOnPortPair 0

--names "{9;ptp;2G_Slow_GoodQuality; ptp;4G_Slow_PoorQuality;ptp;ADSL_Medium_GoodQuality;ptp; LAN_1Gbps_AvgQuality;ptp;LAN_No_Impairment;ptp;SDSL_Slow_GoodQuality;ptp;Satellite_Slow_PoorQuality;ptp;WAN_10Mbps_PoorQuality;ptp;WiFi_56Mbps_PoorQuality;"

List Compatible (Similar) Standard Emulations with a Named Emulation

This produces a list of all the compatible standard emulations to named (template) emulation. It operates in a similar way to List Compatible (Similar) Emulations with a Started Emulation, above. See that section for the definition of a compatible emulation.

Syntax:

--getCompatibleEmulations --templateEmulation <name>

Where <name> is the name of a template emulation, i.e. the one that is used as a basis for determining compatibility.

Output:

--names "{number of results};{type};{emulation name};{type};{emulation name};"

Dynamically Change an Emulation without Stopping

This allows you to change (update) the current running standard emulation parameters (on a port pair) to those of a compatible (similar) standard emulation. Links retain the names of the emulation that was started with –start or via the GUI. It does not matter if links are enabled or disabled differently; their statuses change as required.

Syntax:

--changeToEmulation <name> --portPair (0|1) [--force]

The option --force performs an emulation stop if the new emulation is not compatible with the running emulation.

Examples:

  1. Compatible change

    C:\Users\Lara>Python necli.py --host 192.168.202.194 --user admin --password admin –-changeToEmulation 2G_Slow_GoodQuality –portPair 0

    --ok

  2. Not compatible change, no force

    C:\Users\Lara>Python necli.py --host 192.168.202.194 --user admin --password admin –-changeToEmulation Wan10MbpsToWan155Mbps –-portPair 0

    --error "Cannot change to emulation: incompatible configuration"

  3. Not compatible change, force

    C:\Users\Lara>Python necli.py --host 192.168.202.194 --user admin --password admin –-changeToEmulation Wan10MbpsToWan155Mbps –-portPair 0 --force

    --ok

 

This topic was last updated on July 02, 2020, at 02:52:01 PM.

Eggplant icon Eggplantsoftware.com | Documentation Home | User Forums | Support | Copyright © 2020 Eggplant