### Clone and enter cpdp-frr example Source: https://otg.dev/examples/otg-examples/docker-compose/cpdp-frr Clones the otg-examples repository recursively and changes into the cpdp-frr example directory. This is the first step of the quick start workflow. ```bash git clone --recursive https://github.com/open-traffic-generator/otg-examples.git cd otg-examples/docker-compose/cpdp-frr ``` -------------------------------- ### Install gosnappi with go get Source: https://otg.dev/clients/gosnappi Initializes a new Go module and installs the gosnappi package. Run these commands in a terminal to set up a project directory for writing gosnappi test scripts. ```bash mkdir tests && cd tests go mod init tests go get github.com/open-traffic-generator/snappi/gosnappi ``` -------------------------------- ### Run the TLDR make command Source: https://otg.dev/examples/otg-examples/clab/ixia-c-b2b/SCAPY Runs the full example workflow: installs dependencies, builds the snappi container image, deploys the lab, runs the scapy2otg test, and cleans up. After this, inspect p1.pcap and p2.pcap for captured packets. ```bash make install build deploy run-scapy clean ``` -------------------------------- ### Create and run a snappi test script (hello.py) Source: https://otg.dev/clients/snappi A complete Python example that creates an snappi API instance, configures a port and flow, sets packet size and duration, adds protocol headers, pushes the configuration, starts transmission, and fetches port metrics. The API uses HTTP transport by default; pass `transport=snappi.Transport.GRPC` to use gRPC instead. ```python import snappi # create a new API instance where location points to controller. # this will use HTTP transport by default; in order to use gRPC instead, # one can pass additional kwarg `transport=snappi.Transport.GRPC` api = snappi.api(location='https://localhost') # create a config object to be pushed to controller config = api.config() # add a port with location pointing to traffic engine prt = config.ports.port(name='prt', location='localhost:5555')[-1] # add a flow and assign endpoints flw = config.flows.flow(name='flw')[-1] flw.tx_rx.port.tx_name = prt.name # configure 100 packets to be sent, each having a size of 128 bytes flw.size.fixed = 128 flw.duration.fixed_packets.packets = 100 # add Ethernet, IP and TCP protocol headers with defaults flw.packet.ethernet().ipv4().tcp() # push configuration api.set_config(config) # start transmitting configured flows ts = api.transmit_state() ts.state = ts.START api.set_transmit_state(ts) # fetch & print port metrics req = api.metrics_request() req.port.port_names = [prt.name] print(api.get_metrics(req)) ``` -------------------------------- ### Clone the otg-examples repository Source: https://otg.dev/examples/otg-examples/clab/ixia-c-b2b/SCAPY Clones the otg-examples repository and changes into the ixia-c-b2b example directory. Required before running the other commands in this guide. ```bash git clone --recurse-submodules https://github.com/open-traffic-generator/otg-examples.git cd otg-examples/clab/ixia-c-b2b ``` -------------------------------- ### Install docker-compose Source: https://otg.dev/examples/otg-examples/docker-compose/b2b Downloads and installs docker-compose version 1.29.2 to /usr/local/bin and makes it executable. ```bash sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose ``` -------------------------------- ### Install git and envsubst Source: https://otg.dev/examples/otg-examples/hw/ixhw-b2b Installs git and envsubst (from gettext-base) on Ubuntu/Debian. These are typically installed by default but this command ensures they are present. ```bash sudo apt install git gettext-base -y ``` -------------------------------- ### Clone otg-examples and enter ixhw-b2b Source: https://otg.dev/examples/otg-examples/hw/ixhw-b2b Clones the otg-examples repository recursively and changes into the hw/ixhw-b2b directory. This is the working directory for the back-to-back hardware setup. ```bash git clone --recursive https://github.com/open-traffic-generator/otg-examples.git cd otg-examples/hw/ixhw-b2b ``` -------------------------------- ### Install otgen with curl or wget Source: https://otg.dev/clients/otgen Installs otgen via the installation script, which detects the OS and installs the relevant binary. The first command fetches the latest release, the second fetches a specific version (0.4.0), and the third uses wget instead of curl. May require sudo. ```shell # download and install the latest release (may require sudo) bash -c "$(curl -sL https://get.otgcdn.net/otgen)" # download a specific version - 0.4.0 in this example (may require sudo) bash -c "$(curl -sL https://get.otgcdn.net/otgen)" -- -v 0.4.0 # with wget bash -c "$(wget -qO - https://get.otgcdn.net/otgen)" ``` -------------------------------- ### Start protocols with curl Source: https://otg.dev/examples/otg-examples/docker-compose/cpdp-frr Starts all protocols by sending a control state request with choice 'protocol' and state 'start'. ```bash curl -k "${OTG_HOST}/control/state" \ -H "Content-Type: application/json" \ -d '{"choice": "protocol","protocol": {"choice": "all","all": {"state": "start"}}}' ``` -------------------------------- ### Install otgen CLI Source: https://otg.dev/examples/otg-examples/clab/ixia-c-b2b-lag Install the otgen CLI tool version 0.6.2 using the official installation script. ```bash bash -c "$(curl -sL https://get.otgcdn.net/otgen)" -- -v 0.6.2 ``` -------------------------------- ### Prepare KNE environment and start lab Source: https://otg.dev/examples/otg-examples/kne/bgp-ceos Runs the Makefile targets to prepare the KNE environment and start the lab. ```bash make prereqs deploy start ``` -------------------------------- ### Set up Multipass VM Source: https://otg.dev/examples/otg-examples/kne/bgp-ceos Creates a Multipass VM with 8 CPUs, 16GB RAM, and 64GB disk, then installs build-essential, Docker, curl, and git, and adds the user to the docker group. ```bash multipass launch 20.04 -n knevm -c8 -m16G -d64G multipass shell knevm sudo apt update && sudo apt upgrade -y sudo apt install build-essential -y sudo apt install docker.io curl git -y sudo usermod -aG docker $USER logout ``` -------------------------------- ### Install Go 1.19 via snap Source: https://otg.dev/examples/otg-examples/hw/ixhw-b2b Installs Go version 1.19 or later via snap. Required for building or running Go-based components. ```bash sudo snap install go --channel=1.19/stable --classic ``` -------------------------------- ### Clone and enter the lab directory Source: https://otg.dev/examples/otg-examples/clab/ixia-c-te-frr Clones the otg-examples repository recursively and changes into the lab directory for the Ixia-c TE FRR example. ```bash git clone --recursive https://github.com/open-traffic-generator/otg-examples.git cd otg-examples/clab/ixia-c-te-frr ``` -------------------------------- ### Install snappi with pip Source: https://otg.dev/clients/snappi Install or upgrade the snappi Python module using pip. This command installs the latest version from PyPI. ```bash python -m pip install --upgrade snappi ``` -------------------------------- ### Create Google Cloud VM for Containerlab Source: https://otg.dev/examples/otg-examples/clab/ixia-c-b2b Creates a VM named 'otg-demo' in the default VPC with Ubuntu 20.04 LTS, then installs Docker and Containerlab. ```bash gcloud compute instances create otg-demo \ --subnet=default \ --machine-type=e2-standard-8 \ --image-family=ubuntu-2004-lts \ --image-project=ubuntu-os-cloud \ --boot-disk-size=30GB \ --boot-disk-device-name=otg-demo \ --tags=otg-demo gcloud compute ssh otg-demo sudo apt update && sudo apt install docker.io -y bash -c "$(curl -sL https://get.containerlab.dev)" ``` -------------------------------- ### Set up Python virtualenv for snappi Source: https://otg.dev/examples/otg-examples/docker-compose/cpdp-b2b Create a Python virtual environment named snappi, activate it, and install the required Python packages from the snappi requirements files. ```bash mkdir -p $HOME/.venv python3.9 -m venv $HOME/.venv/snappi source $HOME/.venv/snappi/bin/activate pip install -r snappi/requirements.txt pip install -r snappi/conformance/requirements.txt ``` -------------------------------- ### Example OTG_LOCATION variables for ports 14 and 15 Source: https://otg.dev/examples/otg-examples/hw/ixhw-b2b Example of setting OTG_LOCATION_P1 and OTG_LOCATION_P2 for IxOS management IP 10.10.10.10, slot 2, ports 14 and 15. ```bash export OTG_LOCATION_P1="10.10.10.10;2;14" export OTG_LOCATION_P2="10.10.10.10;2;15" ``` -------------------------------- ### Start capture on ports with snappi Source: https://otg.dev/clients/snappi Starts capture on ports p1 and p2. The JSON shows the equivalent request body with state "start" and the same port names. ```python cs = api.capture_state() cs.state = ts.START cs.port_names = ['p1', 'p2'] api.set_capture_state(cs) ``` ```json { "port_names": [ "p1", "p2" ], "state": "start" } ``` -------------------------------- ### Navigate to lab folder Source: https://otg.dev/examples/otg-examples/clab/ixia-c-te-frr Navigates into the lab folder for the Ixia-c TE FRR example. ```bash cd otg-examples/clab/ixia-c-te-frr ``` -------------------------------- ### Start and configure KENG Hybrid Operator Source: https://otg.dev/examples/otg-examples/hybrid/fp-b2b Starts the operator and sends the configuration file to its API. ```bash sudo docker compose --project-directory "${OTGLABDIR}" up -d sleep 2 curl --data-binary @"${OTGLABDIR}/ixiatg-configmap.yml" http://localhost:35000/config ``` -------------------------------- ### Launch cpdp-frr lab with Docker Compose Source: https://otg.dev/examples/otg-examples/docker-compose/cpdp-frr Starts the Docker Compose lab from the cpdp-frr directory and lists running containers. Requires Docker Compose and the otg-examples repository. ```bash cd otg-examples/docker-compose/cpdp-frr docker-compose up -d sudo docker ps ``` -------------------------------- ### Example otgen environment variable exports Source: https://otg.dev/clients/otgen Shows example export commands that set the otgen environment variables to typical values for a local deployment. These values are used by otgen when no variables or arguments are provided. ```bash export OTG_API="https://localhost:8443" export OTG_LOCATION_P1="localhost:5555" # ixia-c-traffic-engine for p1 (tx) listening on localhost:5555 export OTG_LOCATION_P2="localhost:5556" # ixia-c-traffic-engine for p2 (rx) listening on localhost:5556 export OTG_FLOW_SMAC_P1="02:00:00:00:01:aa" export OTG_FLOW_DMAC_P1="02:00:00:00:02:aa" export OTG_FLOW_SMAC_P2="02:00:00:00:02:aa" export OTG_FLOW_DMAC_P2="02:00:00:00:01:aa" export OTG_FLOW_SRC_IPV4="192.0.2.1" export OTG_FLOW_DST_IPV4="192.0.2.2" export OTG_FLOW_SRC_IPV6="fe80::000:00ff:fe00:01aa" export OTG_FLOW_DST_IPV6="fe80::000:00ff:fe00:02aa" ``` -------------------------------- ### Install docker-compose and add user to docker group Source: https://otg.dev/examples/otg-examples/docker-compose/cpdp-frr Installs docker-compose, makes it executable, adds the current user to the docker group, and logs out for group changes to take effect. Requires sudo permissions. ```bash sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose sudo usermod -aG docker $USER logout ``` -------------------------------- ### Create Ubuntu VM with Multipass Source: https://otg.dev/examples/otg-examples/clab/ixia-c-b2b Creates an Ubuntu 20.04LTS VM named 'otg-demo' using Multipass, then installs Docker and Containerlab. Ubuntu 22.04 is not yet supported for this test. ```bash multipass launch 20.04 -n otg-demo -c4 -m8G -d32G multipass shell otg-demo sudo apt update && sudo apt install docker.io -y bash -c "$(curl -sL https://get.containerlab.dev)" ``` -------------------------------- ### Deploy Ixia-c lab with Docker Compose Source: https://otg.dev/examples/otg-examples/docker-compose/cpdp-b2b Navigate to the cpdp-b2b lab directory, start the Docker Compose deployment in detached mode, and list running containers to verify the lab is up. ```bash cd otg-examples/docker-compose/cpdp-b2b sudo docker compose up -d sudo docker ps ``` -------------------------------- ### Create Ubuntu VM with multipass Source: https://otg.dev/examples/otg-examples/hw/ixhw-b2b Launches an Ubuntu 22.04 VM named 'otg' with 4 CPUs, 8 GB RAM, and 32 GB disk, then opens a shell into it. This VM is used as the Linux host for the OTG hardware setup. ```bash multipass launch 22.04 -n otg -c4 -m8G -d32G multipass shell otg ``` -------------------------------- ### Launch deployment and adjust MTUs Source: https://otg.dev/examples/otg-examples/docker-compose/b2b Starts the Docker Compose deployment and sets the MTU to 9500 on both veth interfaces. ```bash sudo docker-compose up -d sudo ip link set veth0 mtu 9500 sudo ip link set veth1 mtu 9500 ``` -------------------------------- ### Deploy Google Cloud Compute instance Source: https://otg.dev/examples/otg-examples/kne/bgp-ceos Deploys a Google Cloud Compute instance with firewall rules allowing SSH, installs build-essential and Docker, and adds the user to the docker group. ```bash MYIP=`curl -s ifconfig.me` MYIPSTR="$(echo $MYIP | sed 's/\./-/g')" gcloud compute firewall-rules create otg-demo-allow-ssh-${MYIPSTR} --description="Allow tcp 22 ingress to any instance tagged as otg-demo-kne" --direction=INGRESS --priority=1000 --network=default --action=ALLOW --rules=tcp:22 --source-ranges="$MYIP/32" --target-tags=otg-demo-kne gcloud compute instances create otg-demo-kne \ --subnet=default \ --machine-type=e2-standard-16 \ --image-family=ubuntu-2004-lts \ --image-project=ubuntu-os-cloud \ --boot-disk-size=100GB \ --boot-disk-device-name=otg-demo-kne \ --tags=otg-demo-kne gcloud compute ssh otg-demo-kne sudo apt update && sudo apt upgrade -y sudo apt install build-essential docker.io -y sudo usermod -aG docker $USER logout ``` -------------------------------- ### Deploy and delete Containerlab VM in Google Cloud Source: https://otg.dev/examples/otg-examples/clab/rtbh Create a Google Cloud VM with firewall rules for ports 8008 and 8080, install Docker and Containerlab, then delete the VM and firewall rules after testing. Run the deletion commands one by one to confirm. ```bash MYIP=`curl ifconfig.me` gcloud compute firewall-rules create otg-demo-allow-8008 --description="Allow tcp 8008 ingress to any instance tagged as otg-demo" --direction=INGRESS --priority=1000 --network=default --action=ALLOW --rules=tcp:8008 --source-ranges="$MYIP/32" --target-tags=otg-demo gcloud compute firewall-rules create otg-demo-allow-8080 --description="Allow tcp 8080 ingress to any instance tagged as otg-demo" --direction=INGRESS --priority=1000 --network=default --action=ALLOW --rules=tcp:8080 --source-ranges="$MYIP/32" --target-tags=otg-demo gcloud compute instances create otg-demo \ --subnet=default \ --machine-type=e2-standard-8 \ --image-family=ubuntu-2004-lts \ --image-project=ubuntu-os-cloud \ --boot-disk-size=30GB \ --boot-disk-device-name=otg-demo \ --tags=otg-demo gcloud compute ssh otg-demo sudo apt update && sudo apt install docker.io build-essential -y bash -c "$(curl -sL https://get.containerlab.dev)" ``` ```bash gcloud compute instances delete otg-demo gcloud compute firewall-rules delete otg-demo-allow-8008 gcloud compute firewall-rules delete otg-demo-allow-8080 ``` -------------------------------- ### Clone repository and navigate to lab folder Source: https://otg.dev/examples/otg-examples/clab/ixia-c-b2b-lag Clone the otg-examples repository and navigate to the lab folder. Run the clone command once, then change into the lab directory. ```bash git clone --recurse-submodules https://github.com/open-traffic-generator/otg-examples.git ``` ```bash cd otg-examples/clab/ixia-c-one-b2b-lag ``` -------------------------------- ### Clone the repository Source: https://otg.dev/examples/otg-examples/clab/ixia-c-te-frr Clones the otg-examples repository to the Linux host. This is a one-time step. ```bash git clone https://github.com/open-traffic-generator/otg-examples.git ``` -------------------------------- ### Install Containerlab latest release Source: https://otg.dev/examples/otg-examples/docker-compose/cpdp-frr Installs the latest release of Containerlab for the Containerlab use case. See the linked installation options for more details. ```bash bash -c "$(curl -sL https://get.containerlab.dev)" ``` -------------------------------- ### Clone the otg-examples repository Source: https://otg.dev/examples/otg-examples/clab/ixia-c-b2b Clones the otg-examples repository with submodules to the Linux host. Run this only once. ```bash git clone --recurse-submodules https://github.com/open-traffic-generator/otg-examples.git ``` -------------------------------- ### Run all steps with make Source: https://otg.dev/examples/otg-examples/clab/ixia-c-te-frr Runs the full lab workflow with `make all` and then cleans up with `make clean`. This is the quick-start path used by the CI pipeline. ```bash make all make clean ``` -------------------------------- ### Start transmitting flows with curl Source: https://otg.dev/examples/otg-examples/docker-compose/cpdp-frr Starts transmitting flows by sending a control state request with choice 'traffic' and flow_transmit state 'start'. ```bash curl -sk "${OTG_HOST}/control/state" \ -H "Content-Type: application/json" \ -d '{"choice": "traffic", "traffic": {"choice": "flow_transmit", "flow_transmit": {"state": "start"}}}' ``` -------------------------------- ### Start transmitting flows Source: https://otg.dev/clients/curl Starts transmitting all configured traffic flows. Sends a JSON payload with state set to "start". ```bash curl -sk "${OTG_HOST}/control/transmit" \ -H "Content-Type: application/json" \ -d '{"state": "start"}' ``` -------------------------------- ### Start Flow Transmit (snappi and JSON) Source: https://otg.dev/clients/snappi Starts transmit on the specified flows (f1 and f2) by setting the transmit state to START and calling set_transmit_state. The JSON shows the equivalent request payload. ```python ts = api.transmit_state() ts.state = ts.START ts.flow_names = ['f1', 'f2'] api.set_transmit_state(ts) ``` ```json { "flow_names": [ "f1", "f2" ], "state": "start" } ``` -------------------------------- ### Deploy lab with Containerlab Source: https://otg.dev/examples/otg-examples/docker-compose/cpdp-frr Deploys the lab using Containerlab. Run from the otg-examples/docker-compose/cpdp-frr directory. Requires sudo. ```bash cd otg-examples/docker-compose/cpdp-frr sudo -E containerlab deploy ``` -------------------------------- ### Create a sample snappi config Source: https://otg.dev/clients/snappi Creates a snappi API instance and a config with a port and a flow. The API uses HTTP transport by default; pass transport=snappi.Transport.GRPC to use gRPC. ```python import snappi # create a new API instance where location points to controller. # this will use HTTP transport by default; in order to use gRPC instead, # one can pass additional kwarg `transport=snappi.Transport.GRPC`: # api = snappi.api(location="localhost:40051", transport=snappi.Transport.GRPC) api = snappi.api() config = api.config() config.ports.port(name='p1', location='localhost:5555') config.flows.flow(name='f1') ``` -------------------------------- ### Install Python3, pip, and venv Source: https://otg.dev/examples/otg-examples/hw/ixhw-b2b Installs Python 3, pip, and the venv module for Python 3.10 on Ubuntu/Debian. Required for the snappi Python environment. ```bash sudo apt install python3 python3-pip python3.10-venv -y ``` -------------------------------- ### Create ONDATRA binding file and set OTGB2B_BINDING Source: https://otg.dev/examples/otg-examples/hw/ixhw-b2b Create the ONDATRA binding file otgb2b.binding from the template otgb2b.template, substituting environment variables, and set OTGB2B_BINDING to its absolute path. ```bash cat otgb2b.template | envsubst > otgb2b.binding export OTGB2B_BINDING="$(pwd)/otgb2b.binding" ``` -------------------------------- ### Get port metrics with snappi Source: https://otg.dev/clients/snappi Gets port metrics for ports tx and rx, requesting frames_tx and frames_rx columns, then asserts they are equal. The JSON shows the equivalent request body with port_names p1 and p2. ```python req = api.metrics_request() req.port.port_names = ['tx', 'rx'] req.port.column_names = [req.port.FRAMES_TX, \ req.port.FRAMES_RX] res = api.get_metrics(req) assert res[0].frames_tx == res[1].frames_rx ``` ```json { "port": { "port_names": [ "p1", "p2" ], "column_names": [ "frames_tx", "frames_rx" ] }, "choice": "port" } ``` -------------------------------- ### Clone the repository Source: https://otg.dev/examples/otg-examples/docker-compose/b2b Clones the otg-examples repository recursively and changes to the b2b directory. ```bash git clone --recursive https://github.com/open-traffic-generator/otg-examples.git cd otg-examples/docker-compose/b2b ``` -------------------------------- ### otgen run --help - show built-in help Source: https://otg.dev/clients/otgen Shows built-in help for the otgen run command. ```bash otgen run --help ``` -------------------------------- ### otgen version - check version Source: https://otg.dev/clients/otgen Checks the installed otgen version. ```bash otgen version ``` -------------------------------- ### Initialize and build with GoReleaser Source: https://otg.dev/clients/otgen/BUILD Commands to initialize GoReleaser configuration and perform builds. The 'goreleaser init' creates a default configuration, 'build' compiles a single target snapshot, and 'release' creates a snapshot release. The '--rm-dist' flag removes the dist directory before building. ```bash goreleaser init goreleaser build --single-target --snapshot --rm-dist goreleaser release --snapshot --rm-dist ``` -------------------------------- ### otgen run - apply config, start protocols, run traffic Source: https://otg.dev/clients/otgen Runs an OTG test by applying a configuration, starting protocols if devices are defined, and running traffic flows. Supports many options to control API endpoint, input format, BGP route detection, metrics collection, timing, and protocol handling. ```bash otgen run [--api https://otg-api-endpoint] # URL of OTG API endpoint. Overrides ENV:OTG_API (default "https://localhost:8443") [--insecure] # Ignore X.509 certificate validation [--file otg.yml | --file otg.json] # OTG configuration file. If not provided, will use stdin [--yaml | --json] # Format of OTG input [--rxbgp 10|2x] # How many BGP routes shall we receive to consider the protocol is up. In number routes or multiples of routes advertised (default 1x) [--metrics port,flow,bgp4] # Metrics types to report as a comma-separated list: "port" for PortMetrics, "flow" for FlowMetrics, "bgp4" for Bgpv4Metrics [--interval 0.5s] # Interval to pull OTG metrics. Valid time units are 'ms', 's', 'm', 'h'. Example: 1s (default 0.5s) [--xeta 2] # How long to wait before forcing traffic to stop. In multiples of ETA. Example: 1.5 (default 2) [--timeout 120] # Maximum total run time, including protocols convergence and running traffic [--protocols auto|ignore|keep] # Protocols control mode: auto - detect, start and stop; ignore - do not detect, start or stop; keep - detect, start but do not stop ``` -------------------------------- ### Launch Docker Compose deployment Source: https://otg.dev/examples/otg-examples/hw/ixhw-b2b Launches the Docker Compose deployment in detached mode. This starts the KENG controller and layer23-hw-server containers. ```bash docker compose up -d ``` -------------------------------- ### Run all steps with Containerlab Source: https://otg.dev/examples/otg-examples/docker-compose/cpdp-frr Runs all steps using the Containerlab option, then cleans up. Execute these commands from the cpdp-frr directory. ```bash make all-clab make clean ``` -------------------------------- ### Set OTG_HOST environment variable Source: https://otg.dev/clients/curl Initializes the OTG_HOST environment variable with the URL of the OTG API Endpoint. Required for all subsequent curl examples. ```bash OTG_HOST="https://localhost" ``` -------------------------------- ### otgen create device: Emulated Device configuration Source: https://otg.dev/clients/otgen Creates an Emulated Device configuration for otgen. Options include device name (default otg1), port (default p1), location (default localhost:5555), MAC, IP, gateway, and network prefix. ```bash otgen create device # Create a configuration for an Emulated Device [--name string] # Device name (default otg1) [--port string] # Test port name (default p1) [--location string] # Test port location string (default localhost:5555) [--mac xx.xx.xx.xx.xx.xx] # Device MAC address [--ip x.x.x.x] # Device IP address [--gw x.x.x.x] # Device default gateway [--prefix nn] # Device network prefix ```