byteblowerll package

Submodules

byteblowerll.byteblower module

class byteblowerll.byteblower.AbstractModifier(*args, **kwargs)

Bases: AbstractObject

Base class for most ByteBlower Modifiers

property thisown: The membership flag

class byteblowerll.byteblower.AbstractObject(*args, **kwargs)

Bases: object

Base class for most of the ByteBlower Objects

DescriptionGet(*args)

Gets a textual description for the current object

Example

from byteblowerll.byteblower import ByteBlower
server = ByteBlower.ServerAdd('byteblower-1.lab.byteblower.com')
print(server.DescriptionGet())

Gets a textual description for the current object

Example

from byteblowerll.byteblower import ByteBlower
server = ByteBlower.ServerAdd('byteblower-1.lab.byteblower.com')
print(server.DescriptionGet())

Refresh()

Retrieves the latest data from the server.

When the method is called on a History object, the method will transfer the samples from the server-side buffer to this API instance. The last sample will always be the running sample. When a sample is closed, the oldest sample in the buffer will be removed.

property thisown: The membership flag

class byteblowerll.byteblower.AbstractObjectList(*args)

Bases: object

This is a List of multiple AbstractObject objects.

It can be iterated just like a normal Python list.

append(x)

iterator()

property thisown: The membership flag

class byteblowerll.byteblower.AbstractRefreshableResult(*args, **kwargs)

Bases: AbstractObject

Base class for Results which are refreshable.

property thisown: The membership flag

class byteblowerll.byteblower.AbstractRefreshableResultList(*args)

Bases: object

This is a List of multiple AbstractRefreshableResult objects.

It can be iterated just like a normal Python list.

append(x)

iterator()

property thisown: The membership flag

exception byteblowerll.byteblower.AddressResolutionFailed(*args)

Bases: InitializationError

property thisown: The membership flag

byteblowerll.byteblower.BB()

class byteblowerll.byteblower.Buffer(*args)

Bases: object

This is a List of multiple string objects.

It can be iterated just like a normal Python list.

iterator()

property thisown: The membership flag

class byteblowerll.byteblower.ByteBlower(*args, **kwargs)

Bases: AbstractObject

Singleton class that is the entry point to start using the ByteBlower API.

Typically, this is the first class you will use when writing a ByteBlower test script. Use this class to connect to ByteBlower servers, to start or stop all configured ByteBlower ports across those servers, and to control the logging behavior.

Retrieve the singleton ByteBlower object using the static method InstanceGet().

This class contains some static convenience methods. They are wrappers around the corresponding non-static methods of the singleton object.

APIVersionGet()

Returns the version of the API.

New in version 2.6.0.

Return type:: str

Example

from byteblowerll import byteblower as api
print(api.ByteBlower.APIVersionGet())
# returns 2.10.0

DefaultTimeout = 10000000000

static DestroyInstance(): Destroy the ByteBlower API Instance

Warning

This will destroy all created API objects.

This will cause all handles to created ByteBlower objects to render invalid.

Bug: accessing invalid handles will most likely crash your pplication

static InstanceGet()

Creates or returns the ByteBlower API singleton instance.

Returns:: ByteBlower singleton instance.
Return type:: ByteBlower

This object is the entry point to start working with the ByteBlower Python API.

If no ByteBlower instance is created yet, this method creates one and returns the object. If the instance exists already, it is simply returned. Any other static call will implicitly instantiate this singleton object.

Example

from byteblowerll import byteblower as api
instance = api.ByteBlower.InstanceGet()

MeetingPointAdd(*args)

Opens a connection to a MeetingPoint and adds it to the current API instance.

New in version 2.6.0.

Parameters:

server – IP address or hostname of the MeetingPoint server to connect.
port – Remote TCP port on which to connect the MeetingPoint server. Should normally never be overridden. Default: 9101

Returns:

A MeetingPoint object that represents the server connection.

Return type:

MeetingPoint

Raises:

MeetingPointUnreachable – When the MeetingPoint server daemon could not be reached. Typical causes are an incorrect or unreachable DNS name or IP address or a MeetingPoint server daemon that is not running (on purpose or due to a software issue).
ValueError|TypeError – When the <port> parameter is provided and is no integer.

A single client instance may be connected to multiple MeetingPoint servers. This allows to use a set of Meeting point servers as a single system. On the other hand, multiple client instances may be connected to a single (shared) MeetingPoint server and will share its resources. See MeetingPoint for more information.

Example

from byteblowerll import byteblower as api
bb = api.ByteBlower.InstanceGet()
meetingpoint = bb.MeetingPointAdd('byteblower-1.lab.byteblower.com')

Opens a connection to a MeetingPoint and adds it to the current API instance.

New in version 2.6.0.

Parameters:

server – IP address or hostname of the MeetingPoint server to connect.
port – Remote TCP port on which to connect the MeetingPoint server. Should normally never be overridden. Default: 9101

Returns:

A MeetingPoint object that represents the server connection.

Return type:

MeetingPoint

Raises:

MeetingPointUnreachable – When the MeetingPoint server daemon could not be reached. Typical causes are an incorrect or unreachable DNS name or IP address or a MeetingPoint server daemon that is not running (on purpose or due to a software issue).
ValueError|TypeError – When the <port> parameter is provided and is no integer.

A single client instance may be connected to multiple MeetingPoint servers. This allows to use a set of Meeting point servers as a single system. On the other hand, multiple client instances may be connected to a single (shared) MeetingPoint server and will share its resources. See MeetingPoint for more information.

Example

from byteblowerll import byteblower as api
bb = api.ByteBlower.InstanceGet()
meetingpoint = bb.MeetingPointAdd('byteblower-1.lab.byteblower.com')

Opens a connection to a MeetingPoint and adds it to the current API instance.

New in version 2.6.0.

Parameters:

server – IP address or hostname of the MeetingPoint server to connect.
port – Remote TCP port on which to connect the MeetingPoint server. Should normally never be overridden. Default: 9101

Returns:

A MeetingPoint object that represents the server connection.

Return type:

MeetingPoint

Raises:

MeetingPointUnreachable – When the MeetingPoint server daemon could not be reached. Typical causes are an incorrect or unreachable DNS name or IP address or a MeetingPoint server daemon that is not running (on purpose or due to a software issue).
ValueError|TypeError – When the <port> parameter is provided and is no integer.

A single client instance may be connected to multiple MeetingPoint servers. This allows to use a set of Meeting point servers as a single system. On the other hand, multiple client instances may be connected to a single (shared) MeetingPoint server and will share its resources. See MeetingPoint for more information.

Example

from byteblowerll import byteblower as api
bb = api.ByteBlower.InstanceGet()
meetingpoint = bb.MeetingPointAdd('byteblower-1.lab.byteblower.com')

MeetingPointGet()

Returns all Meeting Point connections within this API instance.

New in version 2.6.0.

Returns:: a list with objects created within this API instance. Can be empty
Return type:: MeetingPointList

See MeetingPointAdd() for more information

Example

from byteblowerll import byteblower as api
bb = api.ByteBlower.InstanceGet()
meetingPoints = bb.MeetingPointGet()

MeetingPointRemove(inMeetingPoint)

Disconnects from the ByteBlower MeetingPoint.

Parameters:: meetingpoint (MeetingPoint) – The MeetingPoint to disconnect from

See MeetingPointAdd() for more information.

Note

This will invalidate all created objects on this ByteBlower

MeetingPoint!

Example

from byteblowerll import byteblower as api
bb = api.ByteBlower.InstanceGet()
meetingpoint = bb.MeetingPointAdd('byteblower-1.lab.byteblower.com')
bb.MeetingPointRemove(meetingpoint)

MeetingPointRemoveAll()

Disconnects from all ByteBlower MeetingPoints.

See MeetingPointRemove() for more information.

Note

This will invalidate all created objects on this ByteBlower MeetingPoint!

Example

from byteblowerll import byteblower as api
bb = api.ByteBlower.InstanceGet()
meetingpoint = bb.MeetingPointAdd('byteblower-1.lab.byteblower.com')
# ..
bb.MeetingPointRemoveAll()

PortsStart(inPorts)

Starts all traffic streams and application schedules on the specified ByteBlower ports.

Parameters:: ports (ByteBlowerPortList) – a list of ByteBlowerPort objects to start.

More specifically, for each traffic stream and schedulable object on the specified ports, the configured time to wait kicks off and when this time has passed the corresponding action is performed.

Typical actions include starting a traffic stream or sending out a multicast join message or HTTP request. See Stream and SchedulesStart() for more information.

Streams or schedulable objects that are already scheduled and streams that are already active are ignored. Schedulable objects that are already stopped are scheduled again. See SchedulesStart() for more information.

If a port does not contain any streams or schedules, nothing happens for that port.

Example

bb.PortsStart()

PortsStartAll()

Starts all traffic streams and application schedules on all created ByteBlower Ports.

See PortsStart() for more information.

PortsStop(inPorts)

Stops all traffic streams and application schedules on the specified ByteBlower ports.

Parameters:: args (ByteBlowerPortList) – Zero, one or more ByteBlowerPort objects on which to abort traffic streams and application schedules.

More specifically, all traffic streams and schedulable objects that are currently scheduled are cancelled and all active traffic streams are stopped. Since schedulable objects are only active for an instant, aborting these is not possible.

For more information about schedulable objects, see SchedulesStart().

Streams and schedules that are not running are ignored. This may be because they have not yet started or because they are already finished or stopped.

If a port does not contain any streams or schedules, nothing happens for that port.

Example

bb.PortsStop()

PortsStopAll()

Stops all traffic streams and application schedules on all created ByteBlower Ports.

See PortsStop() for more information.

ResultsRefresh(inResults)

Refreshes multiple result objects.

New in version 2.2.

Parameters:: results (AbstractRefreshableResultList) – A list of refreshable results

Sometimes you want to refresh a lot of results-objects at the same time. You can refresh all those objects in one API call. The results will be batched per server and then refreshed.

Example

bb.ResultsRefresh()

ScheduleGroupCreate()

Create a ScheduleGroup.

Return type:: ScheduleGroup

Example

bb.ScheduleGroupCreate()

ScheduleGroupGet()

Returns all existing ScheduleGroups.

Return type:: ScheduleGroupList

Example

scheduleGroup = bb.ScheduleGroupGet('byteblower-1.lab.byteblower.com')

SchedulesStart(inSchedules)

Starts the specified schedulable objects.

Parameters:: schedules (ScheduleList) – Zero, one or more schedulable objects to start.

More specifically, all specified schedulable objects have their time to wait period kick off simultaneously and when this time has passed the corresponding action is performed.

Typical actions include sending out a multicast join message or an HTTP request. All schedulable objects are listed below.

Schedulable objects that are already scheduled are ignored. Schedulable objects that are already finished or cancelled are scheduled again.

While re-scheduling them will always succeed (and this method will return without error), executing them multiple times may result in error states in other places. For example, a HTTPClient can only manage one HTTP session and will refuse to send out a second HTTP request.

Different kinds of schedulable objects exist throughout the API. They are returned by methods such as Igmpv1MemberSession.ScheduleAdd().

After creating and configuring such schedules, they can be scheduled by either passing them to this method or by passing the port(s) on which they were created to PortsStart().

The following schedulable object types are available in the API:

IGMPIPMulticastListen
IGMPJoin
IGMPLeave

Note

Bug: HTTP requests are not yet available as a schedulable object and cannot be used with this method.

Example

bb.SchedulesStart()

SchedulesStop(inSchedules)

Stops the specified schedulable objects.

Parameters:: inSchedules (ScheduleList) – Zero, one or more schedulable objects to abort.

More specifically, all specified schedulable objects that are currently scheduled are cancelled. Schedulable objects are only active for an instant, so actually aborting them is not possible.

For more information about schedulable objects, see SchedulesStart().

Schedules that are not running are ignored. This may be because they have not yet started or because they are already finished or cancelled.

Example

bb.SchedulesStop()

ServerAdd(*args)

Opens a connection to a ByteBlower server and adds it to the current API instance.

Returns:

An object that represents the server connection.

Return type:

ByteBlowerServer

Raises:

ByteBlowerServerUnreachable – When the ByteBlower server daemon could not be reached. Typical causes are an incorrect or unreachable DNS name or IP address or a ByteBlower server daemon that is not running (on purpose or due to a software issue).
ByteBlowerServerIncompatible – When the ByteBlower server daemon is running an incompatible version.
ValueError|TypeError – When the <port> parameter is provided and is no integer.

A single client instance may be connected to multiple ByteBlower servers. This allows to use a set of ByteBlower servers as a single system. On the other hand, multiple client instances may be connected to a single (shared) ByteBlower server and will share its resources. See ByteBlowerServer for more information.

Parameters:

server – IP address or hostname of the ByteBlower server to connect.
port – Remote TCP port on which to connect the ByteBlower server. Should normally never be overridden. Default: 9002

Example

This example connects to the server ‘byteblower-1.lab.byteblower.com

from byteblowerll import byteblower as api
bb = api.ByteBlower.InstanceGet()
server = bb.ServerAdd('byteblower-1.lab.byteblower.com')

Opens a connection to a ByteBlower server and adds it to the current API instance.

Returns:

An object that represents the server connection.

Return type:

ByteBlowerServer

Raises:

ByteBlowerServerUnreachable – When the ByteBlower server daemon could not be reached. Typical causes are an incorrect or unreachable DNS name or IP address or a ByteBlower server daemon that is not running (on purpose or due to a software issue).
ByteBlowerServerIncompatible – When the ByteBlower server daemon is running an incompatible version.
ValueError|TypeError – When the <port> parameter is provided and is no integer.

A single client instance may be connected to multiple ByteBlower servers. This allows to use a set of ByteBlower servers as a single system. On the other hand, multiple client instances may be connected to a single (shared) ByteBlower server and will share its resources. See ByteBlowerServer for more information.

Parameters:

server – IP address or hostname of the ByteBlower server to connect.
port – Remote TCP port on which to connect the ByteBlower server. Should normally never be overridden. Default: 9002

Example

This example connects to the server ‘byteblower-1.lab.byteblower.com

from byteblowerll import byteblower as api
bb = api.ByteBlower.InstanceGet()
server = bb.ServerAdd('byteblower-1.lab.byteblower.com')

Opens a connection to a ByteBlower server and adds it to the current API instance.

Returns:

An object that represents the server connection.

Return type:

ByteBlowerServer

Raises:

ByteBlowerServerUnreachable – When the ByteBlower server daemon could not be reached. Typical causes are an incorrect or unreachable DNS name or IP address or a ByteBlower server daemon that is not running (on purpose or due to a software issue).
ByteBlowerServerIncompatible – When the ByteBlower server daemon is running an incompatible version.
ValueError|TypeError – When the <port> parameter is provided and is no integer.

A single client instance may be connected to multiple ByteBlower servers. This allows to use a set of ByteBlower servers as a single system. On the other hand, multiple client instances may be connected to a single (shared) ByteBlower server and will share its resources. See ByteBlowerServer for more information.

Parameters:

server – IP address or hostname of the ByteBlower server to connect.
port – Remote TCP port on which to connect the ByteBlower server. Should normally never be overridden. Default: 9002

Example

This example connects to the server ‘byteblower-1.lab.byteblower.com

from byteblowerll import byteblower as api
bb = api.ByteBlower.InstanceGet()
server = bb.ServerAdd('byteblower-1.lab.byteblower.com')

ServerCount()

Counts the number of server objects created.

Returns:: the number of ByteBlowerServer objects
Return type:: int

See ServerAdd() for more information.

Example

server = bb.ServerCount()

ServerGet()

Returns all server connections within this API instance.

Returns:: a list of ByteBlowerServer objects
Return type:: ByteBlowerServerList

See ServerAdd() for more information.

Example

server = bb.ServerGet()

ServerRemove(inByteBlowerServer)

Disconnects from the ByteBlower server.

Parameters:: server (ByteBlowerServer) – The server to disconnect from

See ServerAdd() for more information.

Note

This will invalidate all created objects on this ByteBlower Server!

Example

bb.ServerRemove(server)

ServerRemoveAll()

Disconnects from all ByteBlower servers.

See ServerRemove() for more information.

Note

This will invalidate all created objects on this ByteBlower Server!

Example

bb.ServerRemoveAll()

WirelessEndpointsPrepare(inWirelessEndpoints)

Prepares all the specified ByteBlower Endpoints.

Parameters:: endpoints (WirelessEndpointList) – a list with zero, one or more WirelessEndpoint objects to prepare.
Raises:: TechnicalError – When the items in <wirelessEndpoints> are spread across multiple MeetingPoints.

If a ByteBlower Endpoint does not contain any streams or schedules, nothing happens for that ByteBlower Endpoint.

WirelessEndpointsPrepareAsync(inWirelessEndpoints)

Prepares all the specified ByteBlower Endpoints in an asynchronious way.

Parameters:: endpoints (WirelessEndpointList) – a list with zero, one or more WirelessEndpoint objects to prepare.
Raises:: TechnicalError – When the items in <endpoints> are spread across multiple MeetingPoints.

If a ByteBlower endpoint does not contain any streams or schedules, nothing happens for that ByteBlower Endpoint.

Example

bb.WirelessEndpointsPrepareAsync()

WirelessEndpointsStart(inWirelessEndpoints)

Starts all traffic streams and application schedules on the specified ByteBlower Endpoints.

Parameters:: endpoints (WirelessEndpointList) – list with zero, one or more WirelessEndpoint objects on which to start traffic streams and application schedules.
Raises:: TechnicalError – When the items in <wirelessEndpoints> are spread across multiple MeetingPoints.

More specifically, for each traffic stream and trigger object on the specified endpoints, the configured time to wait kicks off and when this time has passed the corresponding action is performed.

Typical actions include starting a traffic stream or HTTP request. See StreamMobile for more information. If a ByteBlower endpoint does not contain any streams or schedules, nothing happens for that ByteBlower Endpoint.

WirelessEndpointsStartAndWait(inWirelessEndpoints)

Starts all traffic streams and application schedules on the specified ByteBlower Endpoints And waits until the devices are started.

Parameters:: endpoints (WirelessEndpointList) – Zero, one or more WirelessEndpont objects on which to start traffic streams and application schedules.
Raises:: TechnicalError – When the items in <wirelessEndpoints> are spread across multiple MeetingPoints.

More specifically, for each traffic stream and trigger object on the specified endpoints, the configured time to wait kicks off and when this time has passed the corresponding action is performed.

Typical actions include starting a traffic stream or HTTP request. See StreamMobile for more information.

If a ByteBlower endpoint does not contain any streams or schedules, nothing happens for that ByteBlower Endpoint.

Example

bb.WirelessEndpointsStartAndWait()

property thisown: The membership flag

exception byteblowerll.byteblower.ByteBlowerAPIException

Bases: Exception

Base class for most of the ByteBlower Exceptions

getInfo()

Gets some additional info of the error

Return type:: str

getMessage()

Get a description of the error

Return type:: str

property thisown: The membership flag

what()

Get a description of the error

Return type:: str

class byteblowerll.byteblower.ByteBlowerInterface(*args, **kwargs)

Bases: AbstractObject

Example

interface = bbServer.InterfaceGetByName('trunk-1-14')
packetDump = interface.PacketDumpCreate()

NameGet()

Returns the name of the ByteBlower Interface

Returns:: Name of the ByteBlower Interface
Return type:: str

Example

print(interface.NameGet())

PacketDumpCreate()

Adds a Packet Dumper to this interface

Returns:: returns a PacketDump object
Return type:: PacketDump

A Packet Dumper can be used to capture all bidirectional traffic coming in on this ByteBlower Interface.

Example

packetDump = interface.PacketDumpCreate()

PacketDumpDestroy(packet_dump)

removes a PacketDump from this interface

Parameters:: dump (PacketDump) – Packet Dumper that you want to destroy from the interface`.

Example

packetDump = interface.PacketDumpCreate()
interface.PacketDumpDestroy(packetDump)

PortCountGet()

Returns the number of created ports on this interface

Returns:: number of ports on this ByteBlowerInterface
Return type:: int

Example

print(interface.PortCountGet())

PortCreate()

Creates a new ByteBlower Port on this ByteBlowerInterface.

Returns:: The created ByteBlower Port object.
Return type:: ByteBlowerPort

Example

port = interface.PortCreate()

PortDestroy(inPort)

Removes a ByteBlower Port from this interface

Parameters:: port (ByteBlowerPort) – Port that you want to destroy from the interface.

Example

interface.PortDestroy(port)

PortGet()

Returns a list of created ByteBlower ports on this ByteBlower Interface

Returns:: A list of ByteBlower ports on this interface
Return type:: ByteBlowerPortList

Example

portList = interface.PortGet()

PortIdGet()

Returns the ID of this interface on the Physical Interface

Returns:: The id of the ByteBlower Interface on the Physical Interface
Return type:: int

Example

print(interface.PortIdGet())

SpeedGet()

Returns the speed of a ByteBlower Interface

Returns:: The speed of this ByteBlower Interface
Return type:: int

Example

print(interface.SpeedGet())

SwitchIdGet()

Returns the ID of the switch where the ByteBlower Interface resides

Returns:: Id of the switch where the ByteBlower Interface is connected
Return type:: int

property thisown: The membership flag

class byteblowerll.byteblower.ByteBlowerInterfaceList(*args)

Bases: object

This is a List of multiple ByteBlowerInterface objects.

It can be iterated just like a normal Python list.

iterator()

property thisown: The membership flag

class byteblowerll.byteblower.ByteBlowerLicense(*args, **kwargs)

Bases: AbstractObject

This class represents the license information of your connected server.

New in version 2.6.0.

Deprecated since version 2.10.0.

The license is defined by the security key hardware on your ByteBlower server.

Example

license = serverServiceInfo.LicenseGet()
print(license.TimeAllowedGet())

NumberOfNonTrunksGet()

The maximum number of non-trunking interfaces allowed by the license

Returns:: number of nontrunks
Return type:: int

Example

print(license.NumberOfNonTrunksGet())

NumberOfTrunkPortsGet(index)

The maximum number of ByteBlower Interfaces that can reside at the given trunk interface.

Parameters:: index (int) – Index of the trunk interface to obtain the value for.
Returns:: Allowed number of ByteBlower Interfaces on the physical interface
Rtype int:

Example

print(license.NumberOfTrunkPortsGet())

NumberOfTrunksGet()

The maximum number of trunking interfaces allowed by the license

Returns:: number of trunking interfaces
Return type:: int

Example

print(license.NumberOfTrunksGet())

SerialGet()

Retrieves the serial number.

This serial number is the serial number of the hardware containing the license. This is handy info when contacting the ByteBlower support department.

Returns:: the serial number of the hardware containing the license
Return type:: str

Example

print(license.SerialGet())

TimeAllowedGet()

The number of minutes the ByteBlower server can run on the license.

If the value is set to 4294967295, the license is permanent and the number should be treated as infinity.

Returns:: Number of minutes the ByteBlower server can run.
Return type:: int

Example

print(license.TimeAllowedGet())

TimeConsumedGet()

The number of minutes the ByteBlower server has run on the license.

This value has only a meaning when the license is a temporary (demo) license.

Returns:: Number of minutes the ByteBlower server has used of the maximum allowed
Return type:: int

Example

print(license.TimeConsumedGet())

VersionGet()

Gets the version of the license.

Returns:: the version of the license
Return type:: int

Example

print(license.VersionGet())

property thisown: The membership flag

class byteblowerll.byteblower.ByteBlowerPort(*args, **kwargs)

Bases: AbstractObject

Logical representation of a network host docked somewhere in the NUT, which can transmit or schedule network traffic, process incoming traffic and run stateful network applications.

A ByteBlowerPort is physically connected (or ‘attached’) to the NUT through the physical ByteBlower interface on which it is created. See ByteBlowerServer.PortCreate() for more information.

Multiple ports may be created on the same physical interface. From a network view, they are just different (simulated) hosts within a shared (datalink or layer 2) subnet. This means traffic to one port created on an interface is seen by all ports on that interface.

Most test scenarios start with one or more ByteBlower ports that are configured to do the following things:

become part of the network (layer2, layer3, perform DHCP, join multicast groups, …)
schedule network traffic streams for transmission (TX objects)
configure incoming packet processors (RX objects) that look for matching packets and e.g. count them
start network applications such as HTTP servers
schedule network application actions (called ‘schedulable objects’) such an HTTP client application sending out an HTTP request

When such ports are subsequently activated, the scheduled streams and network actions are performed at the configured time.

From that moment, relevant result data may be pulled from those streams (TX statistics), incoming packet processors (RX statistics) and network applications (application and session statistics).

Destroying a port will clean up everything that is configured on that port in a clean way:

streams, incoming packet processors and network applications are teared down, their results are gone
the port leaves all multicast groups of which it is part (but doesn’t wait for confirmation)
the port releases its DHCP lease (but doesn’t wait for confirmation)

CapabilityGetByName(name)

Returns a Capability object by its name.

New in version 2.6.0.

Returns:: An object representing the requested capability
Return type:: Capability
Raises:: ConfigError – UnsupportedConfig error message when the Capability is not supported

Example

capability = port.CapabilityGetByName('IPv4')
print(capability.DescriptionGet())

CapabilityIsSupported(name)

Checks whether a capability is supported.

New in version 2.6.0.

Returns:: True if it is supported, False if not
Return type:: bool

Example

print(port.CapabilityIsSupported('IPv4')
# prints True

CapabilityListGet()

Returns a list of Capability objects.

New in version 2.6.0.

Returns:: An object representing a list of known capabilities
Return type:: CapabilityList

Example

This example shows how to query the capabilities on a ByteBlowerPort

capability_list = port.CapabilityListGet()

for capability in capability_list:
   print(capability.DescriptionGet())

InterfaceNameGet()

Returns physical ByteBlower interface code.

Returns:: String code representing the physical interface name (e.g. trunk-1-4 or nontrunk-1).
Return type:: str

Each ByteBlower port is created on a physical ByteBlower interface of a server. This interface determines where the port will be ‘attached’ to the NUT.

See ByteBlowerServer.PortCreate() for more information and to see how an interface name is structured.

Example

print(port.InterfaceNameGet())
# prints trunk-1-1

InterfaceSpeedGet()

Returns physical ByteBlower interface speed.

Returns:: The maximum speed in bits per second a ByteBlower Interface can transmit. This does not take any VLAN overhead into account!
Return type:: int

See ByteBlowerServer.PortCreate() for more information and to see how an interface name is structured.

Example

print(port.InterfaceSpeedGet())
# prints 1000000000

InterfaceSwitchIdGet()

Returns the ID of the switch where the ByteBlower Port resides

Returns:: Id of the switch where the ByteBlower Interface is connected
Return type:: int

Layer25PPPoEAdd()

Adds a layer 2.5 PPPoE Client to this port.

New in version 2.5.0.

Returns:: an object representing an PPPoE client
Return type:: PPPoEClient
Raises:: ConfigError – When an underlying layer 2 or layer 2.5 configuration is not yet fully configured.

Once a layer 2.5 configuration is added to a port, it cannot be destroyed or removed.

Example

Configure the Port’s network connection as a PPPoE-enabled virtual interface.

# set an PPPoE client
client = port.Layer25PPPoEAdd()
print(client.DescriptionGet())

Layer25PPPoEGet()

Returns the ordered list of layer 2.5 PPPoE objects of this port.

New in version 2.5.0: PPPoE objects can be added by ByteBlowerPort.Layer25PPPoEAdd()

Returns:: A list with all the PPPoE clients created
Return type:: Layer25PPPoEList

Example

layer25PPPoEGet = port.Layer25PPPoEGet()

Layer25VlanAdd()

Adds a layer 2.5 VLAN to this port.

Changed in version 2.3.0: Support for stacking multiple VLAN tags. Adding a second VLAN tag on an older server will throw a technical exception.

Changed in version 2.5.0: Multiple layer 2.5 configurations can be added. They will be stacked on top each other in the the port’s network stack from the bottom up.

Returns:: Created VLAN configuration object.
Return type:: VLANTag
Raises:: ConfigError – When an underlying layer 2 or layer 2.5 configuration is not yet fully configured.

Once a layer 2.5 configuration is added to a port, it cannot be destroyed or removed.

Example

Configure the Port’s network connection as a VLAN-enabled virtual interface.

vlan_tag = port.Layer25VlanAdd()
vlan_tag.IDSet(20)

Layer25VlanGet()

Returns the ordered list of layer 2.5 Vlan objects of this port.

New in version 2.5.0: VLAN objects can be added by Layer25VlanAdd().

Return type:: Layer25VlanList

Example

Reading the number of .VLANTag objects of port Configure the Port’s network connection as a VLAN-enabled virtual interface.

vlan_list = port.Layer25VlanGet()

Layer2EthIIGet()

Returns the layer 2 configuration object of this port.

New in version 2.5.0.

Returns:: The ethernet configuration of the ByteBlower port
Return type:: EthernetConfiguration
Raises:: ConfigError – When the layer 2 configuration is not yet set.

Example

eth_conf = port.Layer2EthIIGet()

Layer2EthIISet()

Sets the layer 2 configuration of this port.

Return type:: EthernetConfiguration
Raises:: ConfigError – When the layer 2 configuration is already set.

Once the layer 2 configuration is set, it cannot be destroyed or overwritten.

Example

Configure the Port’s network connection as an Ethernet interface and add MAC address.

port.Layer2EthIISet().MacSet('00bb1b000001')

Layer3IPv4Get()

Returns the layer 3 IPv4 configuration object of this port.

New in version 2.5.0.

Returns:: A created IPv4 configuration object
Return type:: IPv4Configuration
Raises:: ConfigError – When the layer 3 configuration is not yet set.

Example

ipv4_config = port.Layer3IPv4Get()
print(ipv4_config.DescriptionGet())

Layer3IPv4Set()

Sets the layer 3 IPv4 configuration of this port.

New in version 2.5.0.

Returns:

an object representing the IPv4 configuration for the ByteBlower port

Return type:

IPv4Configuration

Raises:

ConfigError – When an underlying layer 2 or layer 2.5 configuration is not yet fully configured.
ConfigError – When the layer 3 configuration is already set.

Once a layer 3 configuration is set, it cannot be destroyed or overwritten.

Both IPv4 and IPv6 are supported. Dual stack is not available on a single port, but can be achieved by creating 2 separate ports with identical layer 2 and (possibly) layer 2.5 configurations.

Example

Configure the Port’s network connection as an IPv4 host.

ipv4_config = port.Layer3IPv4Set()

Layer3IPv6Get()

Returns the layer 3 IPv6 configuration object of this port.

New in version 2.5.0.

Returns:: An object with the IPv6 configuration of the ByteBlower Port
Return type:: IPv6Configuration
Raises:: ConfigError – When the layer 3 configuration is not yet set.

Example

l3_config = port.Layer3IPv6Get()

Layer3IPv6Set()

Sets the layer 3 IPv6 configuration of this port.

New in version 2.5.0.

Return type:

IPv6Configuration

Raises:

ConfigError – When an underlying layer 2 or layer 2.5 configuration is not yet fully configured.
ConfigError – When the layer 3 configuration is already set.

Once a layer 3 configuration is set, it cannot be destroyed or overwritten.

Both IPv4 and IPv6 are supported. Dual stack is not available on a single port, but can be achieved by creating 2 separate ports with identical layer 2 and (possibly) layer 2.5 configurations.

Example

Configure the Port’s network connection as an IPv6 host.

bbPort1_l3 = port1.Layer3IPv6Set().IpManualAdd('3000:3128::24/64')

MDLGet()

Returns the port’s current Maximum Data Length (MDL), the maximum ethernet frame size that can be transmitted.

Returns:: Current MDL value in bytes.
Return type:: int

The MDL is the maximum size (in bytes) for any ethernet packet leaving the port. It includes the ethernet header, but excludes CRC, preamble and interframe gap. To calculate the maximum size of the layer 2 payload, substract the 14 bytes of the ethernet header.

This payload may be a layer 3 IP packet, a layer 2.5 VLAN tag followed by such a layer 3 IP packet or anything else.

The MDL value defaults to 1514, which corresponds with a layer 2 payload of 1500 bytes.

This value is used by the protocol stack. For example, the announced TCP Maximum Segment Size (MSS) is based on this MDL value. This value also limits the number of bytes that can be placed in a Frame when calling Frame.BytesSet().

Note

For ports without layer 2.5 configurations, the default MDL of 1514 will also lead to a maximum layer 3 packet size of 1500. This value is often called the Maximum Transmission Unit or MTU of an interface. When a port has a VLAN configuration however, the MTU will only be 1496 by default! Consider increasing the MDL to 1518 in such cases to simulate typical real-world behavior.

Note

On trunking interfaces the ByteBlower server adds a temporary VLAN automatically, to select an interface (e.g. trunk-1-10) on the ByteBlower switch. This is hidden from the user and has no influence on the MDL value. See ByteBlowerPort::MDLMaximumGet for more information.

Example

Typical values for a trunking and non-trunking port.

print(port1.MDLGet())

MDLMaximumGet()

Returns the port’s highest allowed Maximum Data Length (MDL) value, which is limited by the physical interface.

Returns:: Physical upper bound for the MDL in bytes.
Return type:: int

The MDL of a ByteBlower port places a limit on the size of ethernet frames that may be sent on that port. It can be modified by the user through MDLSet(). The MDL value (in bytes) covers the whole ethernet packet, but excluding CRC, preamble and interframe gap.

The physical ByteBlower interface (e.g. nontrunk-1) on which a port is created places an upper bound on the allowed MDL values. Through this method, this property can be retrieved at runtime.

The typical value of the maximum MDL is 9014 on non-trunking interfaces and 9010 on trunking interfaces.

Note

On trunking interfaces the ByteBlower server adds a temporary VLAN automatically, to select an interface (e.g. trunk-1-10) on the ByteBlower switch. This is hidden from the user. However, it also means that from a user perspective, the maximum MDL value of the same physical interface is 4 bytes less when it’s configured as a trunking interface.

Example

Typical values for a trunking and a non-trunking port.

print(port1.MDLMaximumGet())

MDLSet(mdl)

Sets the port’s Maximum Data Length (MDL), the maximum ethernet frame size that can be transmitted.

Parameters:

mdl (int) – New MDL value in bytes. Should be less then the value returned by MDLMaximumGet().

Raises:

TypeError – When the value is is not an integer.
ConfigError – When the provided value was larger than the maximum supported MDL.

See MDLGet() for more information.

Example

port.MDLSet(1350)
print(port.MDLGet())
# prints 1350

ProtocolHttpClientAdd()

Creates a HTTP client application to run on this port.

Return type:: HTTPClient

A :HTTPClient application can initiate customized HTTP sessions that are typically used to emulate a TCP connection.

It allows configuring the special HTTP requests to which a running HTTPServer application responds. For example, an HTTP client can ask (GET) for a response of a specified size or time or may send (PUT) a payload of a specified size or time itself.

Besides constructing such special HTTP requests, the HTTP client can interact with any normal webserver by configuring its URL.

Example

httpClient = port.ProtocolHttpClientAdd()

ProtocolHttpClientGet()

Returns the list of all HTTP client applications created on this port.

Returns:: returns a list of created HTTPClient objects
Return type:: HTTPClientList

See ProtocolHttpClientAdd() for more information.

Example

all_clients = port.ProtocolHttpClientGet()
print(all_clients.size())

ProtocolHttpClientRemove(arg2)

Removes the HTTP Client application from this port

Parameters:: client (HTTPClient) – The client to remove

ProtocolHttpMultiClientAdd()

Creates a Multi Client application on this port.

Return type:: HTTPMultiClient

Example

httpClient = port.ProtocolHttpMultiClientAdd()

ProtocolHttpMultiClientGet()

Returns the list of a HTTPMultiClient objects on this port.

Return type:: HTTPMultiClientList

Example

print(port.ProtocolHttpMultiClientGet())

ProtocolHttpMultiClientRemove(arg2)

Removes a HTTP Multiclient application from this port

Parameters:: client (HTTPMultiClient) – The HTTP MultiClient to remove

ProtocolHttpMultiServerAdd()

Creates a HTTP MultiServer application on this port.

Return type:: HTTPMultiServer

Example

# create the HTTP client
httpServer = port.ProtocolHttpMultiServerAdd()

ProtocolHttpMultiServerGet()

Returns the list of HTTPMultiServer objects on this port.

Return type:: HTTPMultiServerList

Example

print(port.ProtocolHttpMultiServerGet())

ProtocolHttpMultiServerRemove(arg2)

Removes a HTTP MultiServer application from this port

Parameters:: server (HTTPMultiServer) – The HTTP MultiServer object to remove

ProtocolHttpServerAdd()

Creates a HTTP server application to run on this port.

Returns:: an object representing an HTTP Server object.
Return type:: HTTPServer

An HTTP Server application is a customized HTTP server that is typically used to emulate a TCP connection.

It listens for special HTTP requests (sent by HTTPClient applications) and responds in the desired way. For example, an HTTP request may ask (GET) for a response of a specified size and the HTTP server will emulate sending such a file back.

Example

http_server = port.ProtocolHttpServerAdd()

ProtocolHttpServerGet()

Returns the list of all HTTP server applications created on this port.

See ProtocolHttpServerAdd() for more information.

Returns:: A list of HTTP Server objects.
Return type:: HTTPServerList

Example

print(port.ProtocolHttpServerGet())

ProtocolHttpServerRemove(arg2)

Removes a HTTP server application to from this port.

Parameters:: server (HTTPServer) – HTTP Server object to remove

ProtocolTelnetClientAdd()

Creates a Telnet client application to run on this port.

New in version API: 2.2.0

Return type:: TelnetClient

A Telnet Client application can contact and interact with an external Telnet server.

Apart from simulating such scenarios for its own sake, this application can be used to contact important nodes within the NUT (e.g. a router) and retrieve relevant statistics from it.

Example

protocolTelnetClient = port.ProtocolTelnetClientAdd()

ProtocolTelnetClientGet()

Returns the list of all Telnet client applications created on this port.

New in version API: 2.2.0

Return type:: TelnetClientList

See ProtocolTelnetClientAdd() for more information.

Example

protocolTelnetClient = port.ProtocolTelnetClientGet()

ProtocolTelnetClientRemove(arg2)

Removes a Telnet client application from this port

Parameters:: client (TelnetClient) – Telnet client to remove

ResultClear()

Clears the counters for the ByteBlower port and empties the ByteBlowerPortResultHistory.

Example

port.ResultClear()

ResultGet()

Returns the result object.

Returns:: A result object which contains the packet count, byte count etc for this ByteBlower port.
Return type:: ByteBlowerPortResultSnapshot

Example

result = port.ResultGet()
print(result.DescriptionGet())

ResultHistoryGet()

Returns the history for the counters for the ByteBlower port.

Returns:: An object representing the history of the counters of the ByteBlower Port
Return type:: ByteBlowerPortResultHistory

Example

historyResult = port.ResultHistoryGet()
print(historyResult.DescriptionGet())

RxCaptureBasicAdd()

Creates a capture tool, which captures the data and metadata of incoming frames (possibly restricted by a filter).

New in version 2.5.0.

Returns:: An object representing the servers implementation of the capture functionality
Return type:: CaptureRawPacket

Like all incoming packet processors (or ‘Rx’ objects), this object listens to incoming traffic matching a configurable BPF filter and performs some action when it arrives.

Typically, the filter should limit the matching packets to the interesting traffic, especially since capturing all incoming bytes at high rates may place a heavy load on the server.

Note

Unlike other Rx objects, the capture tool is not activated as soon as it is created. See the class documentation of the returned types for more information.

Warning

Using this tool requires a lot of system resources. Try to avoid capturing at high rates or for a long time. Set the capture filter as strict as possible to avoid unwanted traffic. When too much incoming traffic must be processed, the ByteBlower server may become unstable.

Note

It is also possible to log in to the server and capture there. Note that when capturing a trunking interface (i.e. connected to a switch) you will see an extra VLAN tag that shows to or from which interface the traffic goes. This is currently only possible on the 1x00 series, where the Linux tcpdump tool can sniff the server’s (native) data interfaces.

Note

This functionality is also available with a stand-alone command-line tool. It can be found and downloaded on our support portal.

The returned capture tool is a basic capture tool stores both the frame data and some metadata.

Example

captureTool = port.RxCaptureBasicAdd()
captureTool.Start()

RxCaptureBasicGet()

Returns the list of capture tools created on this port.

Return type:: CaptureRawPacketList

See RxCaptureBasicAdd() for more information.

Example

tools = port.RxCaptureBasicGet()

RxCaptureBasicRemove(inCapture)

Removes a capture

Parameters:: capture (CaptureRawPacket) – The object returned by RxCaptureBasicAdd() or RxCaptureBasicGet()

RxLatencyBasicAdd()

Creates a latency calculator, which computes latency measurements based on timestamps in received frames (possibly restricted by a filter).

New in version 2.5.0.

Return type:: LatencyBasic

Like all incoming packet processors (or ‘Rx’ objects), this object listens to incoming traffic matching a configurable BPF filter and performs some action when it arrives.

Typically, the filter should limit the matching traffic to the Tx.Stream whose transmitted frames actually contain the required timestamps!

The latency calculator is activated as soon as it is created, so don’t forget to reset its counters after setting the filter and initializing your test.

See Frame for information on timestamping.

Example

latency = port.RxLatencyBasicAdd()

RxLatencyBasicGet()

Returns the list of latency calculators created on this port.

New in version 2.5.0.

Return type:: LatencyBasicList

See RxLatencyBasicAdd() for more information.

Example

all_latency = port.RxLatencyBasicGet()
print(all_latency.size())
# prints 1

RxLatencyBasicRemove(inLatency)

Removes a Basic Latency Trigger from this port

Parameters:: trigger (LatencyBasic) – Trigger object to remove

RxLatencyDistributionAdd()

Creates a latency calculator, which computes latency measurements based on timestamps in received frames (possibly restricted by a filter).

New in version 2.5.0.

Return type:: LatencyDistribution

Like all incoming packet processors (or ‘Rx’ objects), this object listens to incoming traffic matching a configurable BPF filter and performs some action when it arrives.

Typically, the filter should limit the matching traffic to the Tx.Stream whose transmitted frames actually contain the required timestamps!

The latency calculator is activated as soon as it is created, so don’t forget to reset its counters after setting the filter and initializing your test.

See Frame for information on timestamping.

Example

distribution = port.RxLatencyDistributionAdd()

RxLatencyDistributionGet()

Returns the list of latency calculators created on this port.

New in version 2.5.0.

Return type:: LatencyDistributionList

See RxLatencyDistributionAdd() for more information.

Example

all_latency = port.RxLatencyDistributionGet()

RxLatencyDistributionRemove(inLatency)

Removes a Latency Distribution trigger from this port

Parameters:: trigger (LatencyDistribution) – Trigger to remove

RxOutOfSequenceBasicAdd()

Creates an out-of-sequence detector, which counts such cases based on sequence numbers in received frames (possibly restricted by a filter).

New in version 2.5.0.

Returns:: Created out-of-sequence detector object.
Return type:: OutOfSequence

Like all incoming packet processors (or ‘Rx’ objects), this object listens to incoming traffic matching a configurable BPF filter and performs some action when it arrives.

Typically, the filter should limit the matching traffic to the Stream whose transmitted frames actually contain the required sequence numbers!

The out-of-sequence detector is activated as soon as it is created, so don’t forget to reset its counters after setting the filter and initializing your test.

Example

out_of_sequence = port.RxOutOfsequenceBasicAdd()
# lets assume traffic is sent to UDP port 9000
out_of_sequence.FilterSet('ip && dst port 9000')
print(out_of_sequence.DescriptionGet())

RxOutOfSequenceBasicGet()

Returns the list of out-of-sequence detectors created on this port.

New in version 2.5.0.

Returns:: A list of created objects
Return type:: OutOfSequenceList

See RxOutOfSequenceBasicAdd() for more information.

Example

all_oos = port.RxOutOfSequenceBasicGet()
print(all_oos.size())
# prints 1

RxOutOfSequenceBasicRemove(inOutOfSequence)

Removes an Out-of-Sequence trigger from the port

Parameters:: trigger (OutOfSequence) – Trigger to remove

RxTriggerBasicAdd()

Creates a basic receive trigger, whose counters are updated for each received frame (possibly restricted by a filter).

New in version 2.5.0.

Returns:: A basic trigger object, which allows to configure the trigger and getting the results
Return type:: TriggerBasic

Like all incoming packet processors (or ‘Rx’ objects), this object listens to incoming traffic matching a configurable BPF filter and performs some action when it arrives.

The receive trigger is activated as soon as it is created, so don’t forget to reset its counters after setting the filter and initializing your test.

See the class documentation of the returned types for more information.

Example

trigger = port.RxTriggerBasciAdd()

RxTriggerBasicGet()

Returns the list of receive triggers created on this port.

New in version 2.5.0.

Returns:: an object representing a list of create basic triggers
Return type:: TriggerBasicList

See RxTriggerBasicAdd() for more information.

Example

all_triggers = port.RxTriggerBasicGet()
print(all_triggers.size())
# prints 1  

RxTriggerBasicRemove(arg2)

Removes a created basic trigger

Parameters:: trigger (TriggerBasic) – Trigger to remove

RxTriggerSizeDistributionAdd()

Creates a size distribution receive trigger, whose counters are updated for each received frame (possibly restricted by a filter).

New in version 2.5.0.

Return type:: TriggerSizeDistribution

Like all incoming packet processors (or ‘Rx’ objects), this object listens to incoming traffic matching a configurable BPF filter and performs some action when it arrives.

The receive trigger is activated as soon as it is created, so don’t forget to reset its counters after setting the filter and initializing your test.

See the class documentation of the returned types for more information.

Example

trigger = port.RxTriggerSizeDistributionAdd()

RxTriggerSizeDistributionGet()

Returns the list of receive triggers created on this port.

New in version 2.5.0.

Returns:: A list with all the sizedistribution triggers created
Return type:: TriggerSizeDistributionList

See RxTriggerSizeDistributionAdd() for more information.

Example

all_size_dists = port.RxTriggerSizeDistributionGet()
print(all_size_dists.size())
# prints 1

RxTriggerSizeDistributionRemove(arg2)

Removes a created size distribution trigger

Parameters:: trigger (TriggerSizeDistribution) – Trigger to remove

Start()

Starts all transmit streams and schedulable objects configured on this port.

See ByteBlower.PortsStart, which does the same for a set of ports, for more information.

Example

port.Start()

Stop()

Stops all transmit streams and schedulable objects configured on this port.

Example

port.Stop()

TunnelTcpAdd()

Creates a TCP tunnel object.

Returns:: The created tunnel. This object can be used to configure the tunnel
Return type:: TCPTunnel

A TCP Tunnel can be used to configure TCP port forwarding between the user’s office network and the lab network.

Through the protocol, a client can requesting dynamic changes to the firewall or NAT port forwarding settings of a (PCP-enabled) gateway.

Example

tunnel = port.TunnelTcpAdd()
print(tunnel.DescriptionGet())

TunnelTcpGet()

Returns a list of all TCP Tunnel objects created on this port.

Return type:: TCPTunnelList

See TunnelTcpAdd() for more information.

Example

tunnelTcp = port.TunnelTcpGet()

TunnelTcpRemove(arg2)

Removes the given TCP Tunnel application from this port

Parameters:: tunnel (TCPTunnel) – TCP Tunnel to remove

TxStreamAdd()

Creates a transmit stream, which can be configured to blast layer 2 frames traffic from this port in a stateless way.

Returns:: an object representing a pure frame blasting stream.
Return type:: Stream

Initially, a stream does not contain any traffic. It must still be configured by adding content (in the form of Frame objects) and timing information (especially the interframe gap).

A Stream can be compared to the transmitting part of a frame blasting flow in the GUI.

Example

stream = port.TxStreamAdd()

TxStreamGet()

Returns a list of transmit streams created on this port.

Returns:: A list with all created Stream objects
Return type:: StreamList

Example

streams = port.TxStreamGet()
print(streams.size())
# prints 1

TxStreamRemove(inStream)

Removes a created ByteBlower Stream from a port

Parameters:: stream (Stream) – Stream object to remove

property thisown: The membership flag

class byteblowerll.byteblower.ByteBlowerPortCounterType

Bases: object

RxAll = 2: TODO

RxBroadcast = 0: TODO

RxUnicast = 1: TODO

class byteblowerll.byteblower.ByteBlowerPortList(*args)

Bases: object

A list of ByteBlowerPort objects

This object represents a list of ByteBlowerPort objects.

The list can be accessed using the standard python list syntax

from __future__ import print_function
from byteblowerll.byteblower import ByteBlower
bb = ByteBlower.InstanceGet()
server = bb.ServerAdd('byteblower-1.lab.byteblower.excentis.com')

# create 2 ports
p1 = server.PortCreate('trunk-1-1')
p2 = server.PortCreate('trunk-1-2')

ports = server.PortGet()

print('Number of created ports', str(len(ports)))
# prints 'Number of created ports 2'

for port in ports:
    print(port.InterfaceNameGet())

# prints the following output :
# trunk-1-1
# trunk-1-2

append(x)

clear()

empty()

erase(*args)

iterator()

push_back(x): Deprecated since version 2.22.0.

This is a leaked implementation detail, please use append().

property thisown: The membership flag

class byteblowerll.byteblower.ByteBlowerPortResultData(*args, **kwargs)

Bases: AbstractObject

ByteBlower port counter result set.

The result set contains three different counters:

a Unicast counter, which counts all received unicast Ethernet frames.
a Broadcast counter, which counts all received broadcast Ethernet frames.
an All counter, which counts all received Ethernet frames.

Note

The ‘all’ counter can be seen as the combination of the unicast and the broadcast counter.

Note

See What’s new in API v2 for more information.

A ByteBlower port result data snapshot object can be created via a ByteBlowerPortResultData or ByteBlowerPort.ResultSnapshot

Example

Receive all frames on “trunk-1-2” of some server, matching UDP source or destination port 67.

result = port.ResultHistoryGet()
resultData = result.CumulativeLatestGet()

IntervalDurationGet()

Gets the configured duration of this results snapshot.

New in version 2.3.0.

Returns:: The interval duration for this sample in nanoseconds
Return type:: int

Example

This example gets interval duration of this result snapshot

print(resultData.IntervalDurationGet())

RxAllGet()

Gets the received counters for the port.

Returns:: a statistics object which contains all counters from a port
Return type:: ByteBlowerPortResultRxData

Example

print(resultData.RxAllGet().DescriptionGet())

RxBroadcastGet()

Gets the received broadcast counters for the port.

Returns:: A statistics object which contain all counters from a port. This will only contain the broadcast packets received on the port.
Return type:: ByteBlowerPortResultRxData

Example

print(resultData.RxBroadcastGet().DescriptionGet())

RxUnicastGet()

Gets the received unicast counters for the port.

Returns:: a statistics object which contain all unicast counters from a port. This will only contain the broadcast unicast received on the port.
Return type:: ByteBlowerPortResultRxData

Example

print(resultData.RxUnicastGet().DescriptionGet())

TimestampGet()

Gets the snapshot timestamp.

Returns:: the snapshot timestamp in nanoseconds from epoch when this snapshot was created.
Return type:: int

Example

This example gets the snapshot timestamp.

print(resultData.TimestampGet())

property thisown: The membership flag

class byteblowerll.byteblower.ByteBlowerPortResultDataList(*args)

Bases: object

This is a List of multiple ByteBlowerPortResultData objects.

It can be iterated just like a normal Python list.

iterator()

property thisown: The membership flag

class byteblowerll.byteblower.ByteBlowerPortResultHistory(*args, **kwargs)

Bases: AbstractRefreshableResult

Port counter result history.

The port counter history is - as always - available in two flavors: the cumulative and the interval results

Note

The information is not updated until Refresh is called on this object.

Note

See History result for more information.

A result history object can be created via a ByteBlowerPort, using ByteBlowerPort.ResultHistoryGet()

Example

Receive all frames on “trunk-1-2” of some server, matching UDP source or destination port 67.

port_resultHistory = port.ResultHistoryGet()

Clear()

Removes the locally stored history snapshots.

This can be used to save memory in long tests where the results are requested at regular intervals.

Warning

Any interval or cumulative result object returned from this history object before calling Clear() will be destroyed and thus become unusable.

CumulativeGet()

Returns a list of available cumulative counters.

Returns:: a list containing the Interval counters
Return type:: ByteBlowerPortResultDataList

Example

This example gets the available cumulative counters

for results in port_resultHistory.CumulativeGet():
     print(results.DescriptionGet())

CumulativeGetByIndex(index)

Returns a single item of the cumulative list.

Parameters:: index (int) – Index of the cumulative snapshot to query
Returns:: cumulative counter object at the specified index
Return type:: ByteBlowerPortResultData

Example

This example gets the available cumulative counters

print(resultHistory.CumulativeGetByIndex(0).DescriptionGet())

CumulativeGetByTime(timestamp)

Returns a single item of the cumulative list using a timestamp nanoseconds.

New in version 2.2.

Parameters:: timestamp (int) – timestamp in nanoseconds since epoch identifying the snapshot
Returns:: The queried snapshot
Return type:: ByteBlowerPortResultData

Example

This example gets the available cumulative counters

print(port_resultHistory.CumulativeGetByTime(timestamp).DescriptionGet())

CumulativeLatestGet()

Returns latest closed item of the cumulative list.

New in version 2.2.

Returns:: The last closed cumulative counter object.
Return type:: ByteBlowerPortResultData

Example

This example gets the available cumulative counters

print(port_resultHistory.CumulativeLatestGet.DescriptionGet())

CumulativeLengthGet()

Returns the size of the cumulative list.

Returns:: The length of the cumulative list
Return type:: int

Example

print(port_resultHistory.CumulativeLengthGet())

IntervalGet()

Returns a list of available interval counters.

Returns:: a list containing the Interval counters
Return type:: ByteBlowerPortResultDataList

Example

This example gets the available interval counters

for i in resultHistory.IntervalGet():
     print(i.DescriptionGet())

IntervalGetByIndex(index)

Returns a single item of the interval list.

Parameters:: index (int) – Index of the interval to query
Returns:: interval counter object at the specified index
Return type:: ByteBlowerPortResultData

Example

This example gets the available interval counters

print(port_resultHistory.IntervalGetByIndex(0).DescriptionGet())

IntervalGetByTime(timestamp)

Returns a single item of the interval list using a timestamp in nanoseconds.

New in version 2.2.

Return type:: ByteBlowerPortResultRxData

Example

This example gets the available interval counters

interval = port_resultHistory.IntervalGetByTime(timestamp)

IntervalLatestGet()

Returns the latest closed item of the interval list.

New in version 2.2.

Returns:: The last closed interval counter object.
Return type:: ByteBlowerPortResultData

Example

This example gets the available interval counters

print(port_resultHistory.IntervalLatestGet.DescriptionGet())

IntervalLengthGet()

Returns the size of the interval list.

Returns:: The length of the interval list
Return type:: int

Example

print(port_resultHistory.IntervalLengthGet())

RefreshTimestampGet()

Returns the timestamp on the server when the current history is requested.

Returns:: Timestamp on the server when the current history is requested in nanoseconds since epoch
Return type:: int

Example

print(port_resultHistory.RefreshTimestampGet())

SamplingBufferLengthGet()

Number of samples to keep in the buffer.

The ByteBlower server has a buffer to keep some samples before they are transferred to the client. This method gets the maximum number of samples the server can hold. The last sample will always be the running sample. When a sample is closed, the oldest sample in the buffer will be removed.

Returns:: The length of the sample buffer
Return type:: int

Example

print(port_resultHistory.SamplingBufferLengthGet())

SamplingBufferLengthSet(inCount)

Sets the number of samples to keep in the buffer.

New in version 2.3.0.

The ByteBlower server has a buffer to keep some samples before they are transferred to the client. This method sets the maximum number of samples the server can hold. The last sample will always be the running sample. When a sample is closed, the oldest sample in the buffer will be removed.

Parameters:: length (int) – New number of samples to store.

Example

port_resultHistory.SamplingBufferLengthSet(10)

SamplingIntervalDurationGet()

Duration of one sampling interval in nanoseconds.

Returns:: Duration in nanoseconds
Return type:: int

Example

print(port_resultHistory.SamplingIntervalDurationGet())

SamplingIntervalDurationSet(inDuration)

Sets the duration of one sampling interval.

New in version 2.3.0.

Parameters:: duration (int) – New duration for a new snapshot interval expressed in nanoseconds

Warning

This affects all users on the same ByteBlower interface.

Warning

The previously collected history will be invalidated.

Example

print(port1_resultHistory.SamplingIntervalDurationGet())

property thisown: The membership flag

class byteblowerll.byteblower.ByteBlowerPortResultRxData(*args, **kwargs)

Bases: AbstractObject

ByteBlower port counter result set.

A ByteBlower port result data snapshot object can be created via a ByteBlowerPortResultData or ByteBlowerPortResultSnapshot

Note

See What’s new in API v2 for more information.

Example

Receive all frames on “trunk-1-2” of some server, matching UDP source or destination port 67.

rx_result=port_result.RxAllGet()

ByteCountGet()

Gets the current received bytes counter.

Return type:: int

Example

This example gets the received bytes counter

print(rx_result.ByteCountGet())

ByteCountWithCRCGet()

Gets the current received bytes counter with the CRC.

Return type:: int

Example

This example gets the received bytes counter

print(rx_result.ByteCountWithCRCGet())

CounterType_RxAll = 2

CounterType_RxBroadcast = 0

CounterType_RxUnicast = 1

FramesizeMaximumGet()

Gets the largest frame size received in this snapshot.

Return type:: int
Raises:: DomainError – When no frames are received, this counter is unavailable

Example

This example gets the largest frame size received in this snapshot.

print(rx_result.FramesizeMaximumGet())

FramesizeMinimumGet()

Gets the smallest frame size received in this snapshot.

Return type:: int
Raises:: DomainError – When no frames are received, this counter is unavailable

Example

This example gets the smallest frame size received in this snapshot.

print(rx_result.FramesizeMinimumGet())

IntervalDurationGet()

Returns the duration of this sample

Returns:: The duration in nanoseconds
Return type:: int

PacketCountGet()

Gets the received packet count.

Return type:: int

Example

This example gets the received packet counter

print(rx_result.PacketCountGet())

TimestampFirstGet()

Gets the timestamp of the first packet in this snapshot.

Returns:: The timestamp in nanoseconds since epoch when the first packet in this was counted
Return type:: int
Raises:: DomainError – When no frames are received, this counter is unavailable

Example

This example gets the timestamp of the first received packet in this snapshot

print(rx_result.TimestampFirstGet())

TimestampGet()

Gets the snapshot timestamp.

Returns:: The timestamp in nanoseconds since epoch when this sample was created
Return type:: int

Example

This example gets the snapshot timestamp.

print(rx_result.TimestampGet()) 

TimestampLastGet()

Gets the current timestamp of the last packet in this snapshot.

Returns:: The timestamp in nanoseconds of the last packet in this sample
Return type:: int
Raises:: DomainError – When no frames are received, this counter is unavailable

Example

This example gets the timestamp of the last received packet in this snapshot.

print(rx_result.TimestampLastGet())

property thisown: The membership flag

class byteblowerll.byteblower.ByteBlowerPortResultSnapshot(*args, **kwargs)

Bases: AbstractRefreshableResult

ByteBlower port counter result set.

The result set contains three different counters:

a Unicast counter, which counts all received unicast Ethernet frames.
a Broadcast counter, which counts all received broadcast Ethernet frames.
an All counter, which counts all received Ethernet frames.

Note

The “all” counter can be seen as the combination of the unicast and the broadcast counter.

Note

See What’s new in API v2 for more information.

A ByteBlower port result data snapshot object can be created via a ByteBlowerPortResultData or ByteBlowerPortResultSnapshot

Example

Receive all frames on “trunk-1-2” of some server, matching UDP source or destination port 67.

port_result = port.ResultGet()

Clear(): Resets all counters back to 0

IntervalDurationGet()

Gets the configured duration of this results snapshot.

New in version 2.3.0.

Returns:: The duration of this sample in nanoseconds
Return type:: int

Example

This example gets interval duration of this result snapshot

print(port_result.IntervalDurationGet())

RefreshTimestampGet()

Returns the timestamp on the server when the current snapshot is requested.

Returns:: Timestamp on the server when the current snapshot is requested in nanoseconds since epoch
Return type:: int

When the snapshot is part of a history, the refresh timestamp will be the same as refresh timestamp of the History object.

Note

This is not the same as TimestampGet()

Example

print(port_result.RefreshTimestampGet())

RxAllGet()

Gets the received counters for the port.

Returns:: a statistics object which contain all counters from a port.
Return type:: ByteBlowerPortResultRxData

Example

print(port_result.RxAllGet.DescriptionGet())

RxBroadcastGet()

Gets the received broadcast counters for the port.

Returns:: A statistics object which contain all counters from a port. This will only contain the broadcast packets received on the port.
Return type:: ByteBlowerPortResultRxData

Example

print(port_result.RxBroadcastGet.DescriptionGet())

RxUnicastGet()

Gets the received unicast counters for the port.

Returns:: a statistics object which contain all unicast counters from a port. This will only contain the broadcast unicast received on the port.
Return type:: ByteBlowerPortResultRxData

Example

print(port_result.RxUnicastGet.DescriptionGet())

TimestampGet()

Gets the snapshot timestamp.

Returns:: Timestamp on the server when the current snapshot is created in nanoseconds since epoch
Return type:: int

Example

This example gets the snapshot timestamp.

print(port_result.TimestampGet())

property thisown: The membership flag

class byteblowerll.byteblower.ByteBlowerServer(*args, **kwargs)

Bases: AbstractObject

Representation of a client connection to a shared, physical ByteBlower server, which can send and receive network traffic through its interfaces.

Using this class, ByteBlower ports (logical network hosts) can be docked to a NUT at a specific place.

Furthermore, information about a shared ByteBlower Server, such as the available interfaces and the current connections can be retrieved.

InterfaceGetByName(name)

Gets a specific ByteBlower Interface

Parameters:: name (str) – Name of the interface to fetch
Return type:: ByteBlowerInterface

Example

interface = server.InterfaceGetByName('trunk-1-1')

InterfaceNamesGet()

Shows the available physical ByteBlower interfaces on the ByteBlower server.

Returns:: A list of all available physical interfaces on this server.
Return type:: StringList

The available interfaces on a server depend on the static server configuration. Only the presence of USB interfaces can change dynamically (using ::Update).

ByteBlower interfaces are represented by a string code formatted as follows:

Trunking interfaces, which are interfaces located on a ByteBlower switch, have a format trunk-X-Y, where X is the server interface on which the switch is connected and Y is the interface number on the switch itself.
Non-trunking interface, which are located directly on the server (without switch), have a format nontrunk-X, where X is the (server) interface.

This format is used as keys in the key-value pair list returned by UsersGet(). It is also the format that should be passed to PortCreate() method as argument.

Example

Assume server has a single 48-port trunking interface and a single non-trunking interface.

server.InterfaceNamesGet()
# Returns ['trunk-1-1', 'trunk-1-2', 'trunk-1-3', ... , 'trunk-1-48', 'nontrunk-1']

PacketDumpCreate(*args)

Creates a PacketDump object on the specified ByteBlower interface.

New in version 2.9.0.

Parameters:: interface (str) – Interface name of the ByteBlower interface
Return type:: PacketDump
Raises:: ConfigError – UnknownByteBlowerInterface When the specified interface name does not exist on the connected server.

The PacketDump API allows to capture all incoming and outgoing network traffic on a ByteBlower interface.

Example

Create a PacketDump object on trunk-1-1

dump = server.PacketDumpCreate('trunk-1-1')

Creates a PacketDump object on the specified ByteBlower interface.

New in version 2.9.0.

Parameters:: interface (ByteBlowerInterface) – ByteBlower Interface to create a dump on
Return type:: PacketDump
Raises:: ConfigError – UnknownByteBlowerInterface When the specified interface name does not exist on the connected server.

The PacketDump API allows to capture all incoming and outgoing network traffic on a ByteBlower interface.

Example

Create a PacketDump object on trunk-1-1

interface = server.InterfaceGetByName('trunk-1-1')
dump = server.PacketDumpCreate(interface)

PacketDumpDestroy(packet_dump)

Removes a created packetdump

PhysicalInterfacesGet()

Gets a list of Physical Interfaces

Return type:: PhysicalInterfaceList

PhysicalInterfacesGetByType(inPhysicalInterfaceType)

Gets a list of Physical Interfaces for a given type

Parameters:: type (PhysicalInterfaceType) – Type to filter on
Return type:: PhysicalInterfaceList

PortCreate(*args)

Creates a new ByteBlower port on the specified ByteBlower interface.

Parameters:: interface (str) – String code for the ByteBlower interface on which to create the port.
Return type:: ByteBlowerPort
Raises:: ConfigError – UnknownByteBlowerInterface When the specified interface name does not exist on the connected server.

By specifying a physical ByteBlower interface, we can ‘attach’ a ByteBlower port (which represents a network host) to the NUT somewhere. This depends of the physical set-up.

Available ByteBlower interfaces depend on the server type and configuration. Available interfaces on the connected server can be shown using InterfaceNamesGet().

ByteBlower interfaces are represented by a string code formatted as follows:

Trunking interfaces, which are interfaces located on a ByteBlower switch, have a format trunk-X-Y, where X is the server interface on which the switch is connected and Y is the interface number on the switch itself.
Non-trunking interface, which are located directly on the server (without switch), have a format nontrunk-X, where X is the (server) interface.

Example

Create a simulated host and attach it to the NUT. More specifically, locate it within the ethernet subnet connected to the first interface of the first ByteBlower switch.

port = server.PortCreate('trunk-1-1')

Creates a new ByteBlower port on the specified ByteBlower interface.

Parameters:: interface (ByteBlowerInterface) – The ByteBlower interface to create the port on.
Return type:: ByteBlowerPort

By specifying a physical ByteBlower interface, we can ‘attach’ a ByteBlower port (which represents a network host) to the NUT somewhere. This depends of the physical set-up.

Available ByteBlower interfaces depend on the server type and configuration. Available interfaces on the connected server can be shown using InterfaceNamesGet().

ByteBlower interfaces are represented by a string code formatted as follows:

Trunking interfaces, which are interfaces located on a ByteBlower switch, have a format trunk-X-Y, where X is the server interface on which the switch is connected and Y is the interface number on the switch itself.
Non-trunking interface, which are located directly on the server (without switch), have a format nontrunk-X, where X is the (server) interface.

Example

Create a simulated host and attach it to the NUT. More specifically, locate it within the ethernet subnet connected to the first interface of the first ByteBlower switch.

interface = server.InterfaceGetByName('trunk-1-1')
port = server.PortCreate(interface)

Creates a new ByteBlower port on the specified ByteBlower interface.

Parameters:

interface (PhysicalInterface) – The ByteBlower Physical interface to create the port on.
portId (int) – Number of the interface on which to create the port on

Return type:

ByteBlowerPort

By specifying a physical ByteBlower interface, we can ‘attach’ a ByteBlower port (which represents a network host) to the NUT somewhere. This depends of the physical set-up.

Available ByteBlower interfaces depend on the server type and configuration. Available interfaces on the connected server can be shown using InterfaceNamesGet().

ByteBlower interfaces are represented by a string code formatted as follows:

Trunking interfaces, which are interfaces located on a ByteBlower switch, have a format trunk-X-Y, where X is the server interface on which the switch is connected and Y is the interface number on the switch itself.
Non-trunking interface, which are located directly on the server (without switch), have a format nontrunk-X, where X is the (server) interface.

Example

Create a simulated host and attach it to the NUT. More specifically, locate it within the ethernet subnet connected to the first interface of the first ByteBlower switch.

port = server.PortCreate(physical, 1)

PortDestroy(inPort)

Remmoves a ByteBlower Port from the server.

Parameters:: port (ByteBlowerPort) – ByteBlower Port to remove

This will stop the ByteBlower Port and remove all configured items on this ByteBlower Port

PortGet()

Returns a list of all ByteBlower ports created through this server connection.

Returns:: A list of ByteBlowerPort objects
Return type:: ByteBlowerPortList

Only ports created through the connection represented by this object are returned, not those created by other client instances (either GUI or API) or those created by other server connections within this API instance! See UsersGet() to see the interfaces on which other users have created ports.

port = server.PortGet()

PortsStart(inPorts)

Starts all ByteBlower Port objects on this server.

Parameters:: ports (ByteBlowerPortList) – List of ByteBlowerPort objects to start

See ByteBlowerPort.Start for more information

PortsStartAll()

Starts all ByteBlower Port objects on this server.

See ByteBlowerPort.Start for more information

PortsStop(inPorts)

Stops all ByteBlower Port objects on this server.

Parameters:: ports (ByteBlowerPortList) – List of ByteBlowerPort objects to stop

See ByteBlowerPort.Stop for more information

PortsStopAll()

Stops all ByteBlower Port objects on this server.

See ByteBlowerPort.Stop for more information

ResultsRefreshAll(): Refreshes all result objects created on this ByteBlower Server

ServiceInfoGet()

Returns the service information of the ByteBlower server daemon.

New in version 2.6.0.

Return type:: ByteBlowerServerServiceInfo

server.ServiceInfoGet()

TimestampGet()

Returns the current timestamp on the server.

New in version 2.3.0.

Retrieves the current timestamp of the server in nanoseconds. This can be used to calculate the offset between two servers to compare results.

Returns:: Timestamp in nanoseconds since epoch
Return type:: int

Example

Assume the client is connected (through this object) to a server:

server.TimestampGet()
# :return: 1432805398000000000 

Update()

Updates dynamic interfaces (e.g. USB) on the connected server.

Deprecated since version 2.0: Since 2.0 are USB interfaces not supported anymore

Raises:: TechnicalError – This method is not implemented anymore at the ByteBlower Server

This methods looks for attached USB interfaces and updates its available interfaces. If USB interfaces are attached, they will be returned by PhysicalInterfacesGet() after this running this method.

UsersGet()

Shows which physical interfaces of the (shared) physical ByteBlower server are currently used by which clients.

Returns:: A list of User objects, one for each physical ByteBlower interface with one or more ports configured on it. The name is the string representation of the interface, the value is a list of the server connections (represented by their client’s hostname) which have created ports on that interface.
Return type:: UserList

This method gives an overview of how a ByteBlower server is currently used. It displays which client connections (whether from GUI scenario runs or API sessions) have created ByteBlowerPort objects on which of the server’s physical ByteBlower interfaces.

Such a client connection to a server is represented by this very ByteBlowerServer type! As soon as some client instance (e.g. a TCL shell, python interpreter or a GUI) on some client computer creates such server object, a connection is established to that shared server.

Multiple client instances can be active on the same host. For example, a single host may be running a GUI scenario, two python scripts and an interactive Tcl session at the same time. Similarly, a single client instance may have multiple parallel connections to the same server, by calling ByteBlower.ServerAdd() multiple times for the same server URL or IP.

The server’s physical interfaces are statically configured on the server machine and can be retrieved using PhysicalInterfacesGet(). They are shared among all connected clients.

Client connections are identified by the client’s hostname. This means that all server connections from all client instances on a single host will all be different ‘users’, but will have the same string representation. If they use the same interfaces, that hostname will simply appear multiple times.

As soon as a specific ByteBlowerServer (representing a client connection) creates a first ByteBlowerPort on some interface, it is ‘using’ that interface. The interface is no longer used when all all ports created by that server on it are destroyed. Ports can be destroyed in the following ways:

Explicitly, by calling PortDestroy() on the ByteBlowerServer
By destroying the ByteBlowerServer for that port. This is also what happens when a GUI finishes or cancels a scenario.
By destroying that client instances root ByteBlower object. This is also what happens when a client process (GUI or API) is killed.

Example

Assume three client instances are currently connected to this server. The first runs on John’s PC, the second runs on Jane’s PC and the last one is a second client instance connecting John’s PC. Note the non-trunking interface is used by multiple client instances!

userList = server.UsersGet()

property thisown: The membership flag

exception byteblowerll.byteblower.ByteBlowerServerIncompatible(*args)

Bases: DomainError

property thisown: The membership flag

class byteblowerll.byteblower.ByteBlowerServerList(*args)

Bases: object

This is a List of multiple ByteBlowerServer objects.

It can be iterated just like a normal Python list.

append(x)

iterator()

property thisown: The membership flag

class byteblowerll.byteblower.ByteBlowerServerServiceInfo(*args, **kwargs)

Bases: ServiceInfo

This class contains information on the ByteBlower System.

New in version 2.6.0.

With this object you can get information concerning the Type / version / IP or hostname etc… information.

Example

from byteblowerll.byteblower import ByteBlower
server = ByteBlower.ServerAdd('byteblower-1.lab.byteblower.com')
service_info = server.ServiceInfoGet()

ConnectionHostGet()

Returns the host (either registered name or IP address) used to connect to the ByteBlower server.

Return type:: str

Example

print(service_info.ConnectionHostGet())
# prints 'bytblower-1.lab.byteblower.com'

ConnectionIPAddressGet()

Returns the IP address used to connect to the ByteBlower server.

Return type:: str

Example

from byteblowerll.byteblower import ByteBlower
server = ByteBlower.ServerAdd('byteblower-1.lab.byteblower.com')
server.PortCreate('trunk-1-1')
service_info = server.ServiceInfoGet()
print(service_info.ConnectionIPAddressGet())
# prints ip address

ConnectionPortNumberGet()

Returns the TCP port number of the connected ByteBlower server.

Return type:: int

Example

print(service_info.ConnectionPortNumberGet())

LicenseGet()

Returns the License information for this ByteBlower server.

New in version 2.6.0.

Deprecated since version 2.10.

Return type:: ByteBlowerLicense

Each physical ByteBlower server (represented by this type of object) has a specific ByteBlower License.

ManagementIPAddressGet()

Returns all management IP addresses of the connected ByteBlower server.

New in version 2.6.0.

Returns:: List of management IP addresses
Return type:: StringList

Example

print(service_info.ManagementIPAddressGet())

property thisown: The membership flag

exception byteblowerll.byteblower.ByteBlowerServerUnreachable(*args)

Bases: DomainError

property thisown: The membership flag

class byteblowerll.byteblower.CHAPProtocol(*args, **kwargs)

Bases: PPPAuthProtocol

Represents the Challenge-Handshake Authentication Protocol

PPP defines an extensible Link Control Protocol, which allows negotiation of an Authentication Protocol for authenticating its peer before allowing Network Layer protocols to transmit over the link.

This class provides the Password Authentication protocol as described per :rfc:1334, section 3

The Challenge-Handshake Authentication Protocol (CHAP) is used to periodically verify the identity of the peer using a 3-way handshake. This is done upon initial link establishment, and MAY be repeated anytime after the link has been established.

After the Link Establishment phase is complete, the authenticator sends a “challenge” message to the peer. The peer responds with a value calculated using a “one-way hash” function. The authenticator checks the response against its own calculation of the expected hash value. If the values match, the authentication is acknowledged, otherwise the connection SHOULD be terminated.

CHAP provides protection against playback attack through the use of an incrementally changing identifier and a variable challenge value. The use of repeated challenges is intended to limit the time of exposure to any single attack. The authenticator is in control of the frequency and timing of the challenges.

This authentication method depends upon a “secret” known only to the authenticator and that peer. The secret is not sent over the link. This method is most likely used where the same secret is easily accessed from both ends of the link.

By default, authentication is not mandatory. If authentication of the link is desired, an implementation MUST specify the Authentication-Protocol Configuration Option during Link Establishment phase.

New in version 2.5.0.

GetPPPProtocol(*args)

SecretGet()

Returns the configured Secret.

Returns:: Secret value

Todo

Real Example

SecretSet(secret)

Configures the Secret on the Challenge Handshake Authentication Protocol (CHAP)

Parameters:: secret – The secret for authenticating to the PPP server.

Todo

Real Example

property thisown: The membership flag

class byteblowerll.byteblower.CHAPProtocolList(*args)

Bases: object

This is a List of multiple CHAPProtocol objects.

It can be iterated just like a normal Python list.

iterator()

property thisown: The membership flag

class byteblowerll.byteblower.Capability(*args, **kwargs)

Bases: AbstractObject

Represents a capability, A feature it supports or not.

Using this class, you can check if e.g. a ByteBlower Endpoint supports latency measurements or not

Available Capabilities: - TODO

Example

from byteblowerll.byteblower import ByteBlower
server = ByteBlower.ServerAdd('byteblower-1.lab.byteblower.com')
port = server.PortCreate('trunk-1-1')
capability_list = port.CapabilityListGet()
capability = capability_list[0]
# print version
print(capability.VersionAddedGet())

CapabilityDescriptionGet()

Returns a human-readable description of the capability.

Returns:: A human readable description
Return type:: str

Example

print(capability.CapabilityDescriptionGet())

NameGet()

Returns a human-readable name of the capability.

Returns:: The human readable name of the capability.
Rtype str:

Example

print(capability.NameGet())

ValueGet()

Returns a CapabilityValue object.

Returns:: the value of the capability
Return type:: CapabilityValue

Example

capabilityValue = capability.ValueGet()

VersionAddedGet()

Returns the ByteBlower Server/ByteBlower MeetingPoint version since when this capability is added.

Returns:: The server/meetingpoint version the capability was added
Return type:: str

Example

print(capability.VersionAddedGet())

property thisown: The membership flag

class byteblowerll.byteblower.CapabilityList(*args)

Bases: object

This is a List of multiple Capability objects.

It can be iterated just like a normal Python list.

iterator()

property thisown: The membership flag

class byteblowerll.byteblower.CapabilityValue(*args, **kwargs)

Bases: AbstractObject

The Capability Value class.

A capability ( Capability ) can have a different type of value (INTEGER, BOOLEAN, STRING). Using TypeGet() you can discover the value-type and then use the corresponding getter to get the real value

BooleanGet()

Returns the value as a boolean.

Returns:: The value of the capability as a boolean (if possible)
Return type:: bool

Example

capabilityType = capabilityValue.TypeGet()
if capabilityType==0:
    print(capabilityValue.BooleanGet())
elif capabilityType==1:
    print(capabilityValue.IntegerGet())
else:
    print(capabilityValue.StringGet())

IntegerGet()

Returns the value as an integer.

Returns:: The value of the capability as an integer
Return type:: int

Example

capabilityType = capabilityValue.TypeGet()
if capabilityType==0:
    print(capabilityValue.BooleanGet())
elif capabilityType==1:
    print(capabilityValue.IntegerGet())
else:
    print(capabilityValue.StringGet())

StringGet()

Returns the value as a string.

Returns:: The capability value as a string
Return type:: str

Example

capabilityType = capabilityValue.TypeGet()
if capabilityType==0:
    print(capabilityValue.BooleanGet())
elif capabilityType==1:
    print(capabilityValue.IntegerGet())
else:
    print(capabilityValue.StringGet())

TypeGet()

Returns the type of value.

Returns:: The type of the value
Return type:: CapabilityValueType

Example

capabilityType = capabilityValue.TypeGet()
if capabilityType==0:
    print(capabilityValue.BooleanGet())
elif capabilityType==1:
    print(capabilityValue.IntegerGet())
else:
    print(capabilityValue.StringGet())

Type_BOOLEAN = 0

Type_INTEGER = 1

Type_STRING = 2

property thisown: The membership flag

class byteblowerll.byteblower.CapabilityValueType

Bases: object

BOOLEAN = 0: The given capability is a Boolean value, containing True or False

INTEGER = 1: The given capability is an integer value

STRING = 2: The given capability is a string value

class byteblowerll.byteblower.Capture(*args, **kwargs)

Bases: Rx

Abstract base class for a capture

FileNameRemoteGet()

ResultGet()

Start()

Stop()

property thisown: The membership flag

class byteblowerll.byteblower.CaptureRawPacket(*args, **kwargs)

Bases: Capture

This class is used to capture the raw packet data that is received on the Physical interface that is associated with a ByteBlowerPort.

With this class, one can capture the data that is received by the ByteBlower Port and save this to a pcap file on your pc. You can also apply a filter (BPF-style) to only capture the packets of your interest.

Example

captureRaw = bbPort2.RxCaptureBasicAdd()
captureRaw.FilterSet('ip dst 1.1.1.2')
captureRaw.Start()
#...
captureRaw.Stop()
result = captureRaw.ResultGet()
print(result.DescriptionGet())

FileNameRemoteGet()

Returns the name for the capture as stored on the ByteBlower server

Return type:: str

FilterGet()

Returns the current installed BPF filter string.

The filter string can be configured using FilterSet()

Returns:: The current BPF filter string
Return type:: str

Example

Suppose we configured the trigger with filter string: where ipv4_1 and ipv4_2 are IPv4Configuration objects and frameSize is the (layer2) size of the frames (without CRC!). The BPF filter string would then become for example:

print(captureRaw.FilterGet())

FilterSet(inFilter)

Sets a BPF filter on a RX object.

Note

Configuring a new filter string does reset the counter values which were triggered by a previous filter string. Also the earlier collected history is invalidated.

Parameters:: bpf (str) – Valid BPF filter string. For creating valid BPF filter strings, please have a look at http://www.tcpdump.org/#documentation for more information.
Raises:: ConfigError – When an invalid BPF filter string is given.

Example

This will filter only UDP traffic. Set the filter on packets that match:

source and destination IPv4 address
UDP traffic with given destination and source UDP port
(layer2) frame length (without CRC!)

captureRaw.FilterSet('ip dst 1.1.1.2')

ResultGet()

Returns the capture result.

Return type:: CaptureResultSnapshot

Example

result = captureRaw.ResultGet()

Start()

Start capturing.

Note

Calling Start while already running does not throw an exception.

Example

captureRaw.Start()

Stop()

Stop capturing.

Note

Calling Stop while not running does not throw an exception.

Example

captureRaw.Stop()

property thisown: The membership flag

class byteblowerll.byteblower.CaptureRawPacketList(*args)

Bases: object

This is a List of multiple CaptureRawPacket objects.

It can be iterated just like a normal Python list.

iterator()

property thisown: The membership flag

class byteblowerll.byteblower.CaptureResultSnapshot(*args, **kwargs)

Bases: AbstractRefreshableResult

This class represents the result of a CaptureRawPacket.

It contains the metrics and the frames that are captured. To get an update of the values use ::Refresh.

Example

captureRaw = bbPort2.RxCaptureBasicAdd()
captureRaw.FilterSet('ip dst 1.1.1.2')
captureRaw.Start()
# ...
captureRaw.Stop()
resultSnapshot = captureRaw.ResultGet()

ByteCountGet()

Returns the number of bytes captured.

Returns:: The number of bytes captured
Return type:: int

Example

This example returns the number of bytes captured

print(resultSnapshot.ByteCountGet())

CaptureDurationGet()

Returns the duration of the capture.

Returns:: The duration of the capture in nanoseconds
Return type:: int

Example

This example returns the duration of the capture

print(resultSnapshot.CaptureDurationGet())

Clear()

Clears the counters and deletes the captured packets from the capture.

Example

This example returns the captured frames

resultSnapshot.Clear()

ErrorCountGet()

Returns Error count.

Returns:: Returns the number of packets with incorrect CRC
Return type:: int

Example

This example returns the number of corrupt frames

print(resultSnapshot.ErrorCountGet())

FramesGet()

Returns a list of captured frames.

Returns:: a list of CapturedFrame objects.
Return type:: CapturedFrameList

Example

This example returns the captured frames

framesResult = resultSnapshot.FramesGet()
for frame in framesResult:
print(frame.DescriptionGet())

FramesGetByIndex(index)

Returns a Rx.Capture.Frame at the provided index.

Return type:: CapturedFrame

Example

This example returns the captured frame given by the index

frame = resultSnapshot.FramesGetByIndex(0)

PacketCountGet()

Returns the number of packets captured.

Returns:: The number of packets this capture captured
Return type:: int

Example

This example returns the number of packets captured

print(resultSnapshot.PacketCountGet())

PcapLastFileNameGet()

The fileName where the last pcap was saved to.

Return type:: str

Example

print(resultSnapshot.PcapLastFileNameGet())
# prints: pcapResult.pcap

PcapNanoSave(filename)

Stores the captured frames into a pcap file.

Parameters:: filename (str) – Destination filename for the capture file.
Raises:: <python_error> - No pcap support found: When the pcap library is not installed on the ByteBlower client PC.
Raises:: ByteBlower.Rx.Capture.GetFailed - When no results are available or when an exception occurred while obtaining the results.
Raises:: ByteBlower.Rx.Capture.GetFramesFailed - Invalid captured packet offset.

The stored capture file can be opened by e.g. wireshark.

Example

Stores all packets captured by filter to c:pcap which is in PcapNano format

from byteblowerll.byteblower import ByteBlower
server = ByteBlower.ServerAdd('byteblower-1.lab.byteblower.com')
server.PortCreate('trunk-1-1')
# TODO??

PcapSave(filename)

Stores the captured frames into a pcap file.

Parameters:: fileName (str) – Destination filename for the capture file.
Raises:: ByteBlower.Rx.Capture.GetFailed - When no results are available or when an exception occurred while obtaining the results.
Raises:: ByteBlower.Rx.Capture.GetFramesFailed - Invalid captured packet offset.

The stored capture file can be opened by e.g. wireshark.

Example

Stores all packets captured by filter to c:pcap

resultSnapshot.PcapSave('resultPcap.pcap')

RefreshTimestampGet()

Returns the timestamp when the counters of this object where last refreshed.

Return type:: int

Example

print(resultSnapshot.RefreshTimestampGet())

StateNameGet()

Returns the status of the current capture.

Returns:

Returns current state of this capture.

Possible values are:

unknown
unavailable
inactive
active
invalid

Return type:

str

Example

print(resultSnapshot.StateNameGet())

property thisown: The membership flag

class byteblowerll.byteblower.CapturedFrame(inAbstractObject, inTimestamp, bytes)

Bases: AbstractObject

A representation of a Captured Frame captured using a CaptureRawPacket.

Example

result = captureRaw.ResultGet()
frame = result.FramesGetByIndex(0)
print(frame.LengthGet())

BufferGet()

Gets access to the binary buffer in which the frame is stored.

Returns:: hex representation of the content of the captured frame
Return type:: Buffer

Example

This example gets the bytes in HEX

print(frame.BufferGet())

BytesGet()

Gets the bytes in HEX format of this CapturedFrame.

Returns:: hex representation of the content of the captured frame
Return type:: str

Example

This example gets the bytes in HEX

print(frame.BytesGet())

LengthGet()

Gets the packet length of this CapturedFrame. This is the length without CRC.

Returns:: Length of the packet without CRC
Return type:: int

Example

print(frame.LengthGet())

TimestampGet()

Gets timestamp [NS] of this CapturedFrame.

Returns:: Timestamp in nanoseconds
Return type:: int

Example

This example gets the timestamp of the captured frame

print(frame.TimestampGet())

property thisown: The membership flag

class byteblowerll.byteblower.CapturedFrameList(*args)

Bases: object

This is a List of multiple CapturedFrame objects.

It can be iterated just like a normal Python list.

iterator()

property thisown: The membership flag

class byteblowerll.byteblower.CapturedHTTPData(*args, **kwargs)

Bases: AbstractObject

This class represents captured HTTP data.

The HTTP data is a local snapshot of the HTTP data received in a HTTP session at the ByteBlower Server.

HTTP data capture is currently supported on HTTP Client objects.

captureData = httpClient.CaptureGet()
print(captureData.HttpSizeGet())

HttpBytesGet()

Returns the captured HTTP data.

Returns:: Captured HTTP data as string.
Return type:: str
Raises:: UnsupportedFeature – When the ByteBlower Server does not support HTTP Client captures

The data includes both HTTP header and payload.

Note

This only outputs the local cached HTTP data. The local cached HTTP data is a snapshot of the HTTP data received at the ByteBlower server. If no local snapshot was available yet, an initial one will be obtained from the server. You may want to synchronize the local cached data using the Refresh method on this object.

Example

Suppose we sent a HTTP GET request for an ‘index.html’ test page

print(captureData.HttpBytesGet())

HTTP/1.1 200 OK
Date: Wed, 12 Feb 2014 13:23:32 GMT
Server: Apache/2.2.22 (Debian)
Last-Modified: Thu, 10 Feb 2011 11:32:16 GMT
ETag: "27c083-b1-49bebeefcb000"
Accept-Ranges: bytes
Content-Length: 177
Vary: Accept-Encoding
Content-Type: text/html
X-Pad: avoid browser bug
<html><body><h1>It works!</h1>
<p>This is the default web page for this server.</p>
<p>The web server software is running but no content has been added,
yet.</p>
</body></html>

HttpBytesSave(inFileName)

Saves the captured HTTP data to file.

Parameters:: fileName (str) – Destination filename for the captured HTTP data.
Raises:: UnsupportedFeature – When the ByteBlower Server does not support HTTP Client captures

Note

This only outputs the local cached HTTP data. The local cached HTTP data is a snapshot of the HTTP data received at the ByteBlower server. If no local snapshot was available yet, an initial one will be obtained from the server. You may want to synchronize the local cached data using the Refresh method on this object.

Example

Stores all HTTP data captured to c:.txt

captureData.HttpBytesSave('httpResults.txt')

HttpSizeGet()

Returns the number of captured bytes of HTTP data.

Returns:: Size of captured HTTP data in Bytes.
Return type:: int

The value includes the size of both HTTP header and payload.

Note

This only outputs the local cached HTTP data. The local cached HTTP data is a snapshot of the HTTP data received at the ByteBlower server. If no local snapshot was available yet, an initial one will be obtained from the server. You may want to synchronize the local cached data using the Refresh method on this object.

Raises:: UnsupportedFeature – When the ByteBlower Server does not support HTTP Client captures

Example

a HTTP GET request for an index.html test page

print(captureData.HttpSizeGet())

property thisown: The membership flag

exception byteblowerll.byteblower.ConfigError(*args)

Bases: DomainError

Raised when the API is called with a configuration mistake

This can happen in a few cases:

The API is called with a wrong argument. E.g. The API expects a positive integer, but e.g. -1 is passed
A method is called on an object which is not fully configured yet. E.g. Start is called on an HTTP client, but the remote address was not configured.

property thisown: The membership flag

byteblowerll.byteblower.ConvertCounterType(inType)

byteblowerll.byteblower.ConvertEthernetEncodingToString(inEthernetEncoding)

byteblowerll.byteblower.ConvertHTTPMultiClientStatusToString(inHTTPRequestStatus)

byteblowerll.byteblower.ConvertHTTPRequestMethodToString(inHTTPRequestMethod)

byteblowerll.byteblower.ConvertHTTPRequestStatusToString(inHTTPRequestStatus)

byteblowerll.byteblower.ConvertHTTPRequestTypeToString(inHTTPRequestType)

byteblowerll.byteblower.ConvertLinkStatusToString(inLinkStatus)

byteblowerll.byteblower.ConvertLinkTypeToString(inLinkType)

byteblowerll.byteblower.ConvertLogLevelFromString(inLevel)

byteblowerll.byteblower.ConvertPPPoEStatusToString(inPPPoEStatus)

byteblowerll.byteblower.ConvertPhysicalInterfaceTypeToString(inType)

byteblowerll.byteblower.ConvertRequestStartTypeToString(inRequestStartType)

byteblowerll.byteblower.ConvertRuntimeTransmitErrorSource(inSource)

byteblowerll.byteblower.ConvertRuntimeTransmitErrorStatus(inStatus)

byteblowerll.byteblower.ConvertRuntimeTransmitStatus(inStatus)

byteblowerll.byteblower.ConvertScheduleGroupStatusToString(inStatus)

byteblowerll.byteblower.ConvertTCPCongestionAvoidanceAlgorithmToString(inTCAA)

byteblowerll.byteblower.ConvertTCPConnectionStateToString(inState)

byteblowerll.byteblower.ConvertTimeUnitToString(inTimeUnit)

byteblowerll.byteblower.ConvertToString(inLevel)

exception byteblowerll.byteblower.DHCPFailed(*args)

Bases: InitializationError

Raised when the DHCP process failed.

This is usually due to a DISCOVER/SOLICIT/REQUEST message did not get a (valid) reply before the DHCP Timeout passed.

property thisown: The membership flag

class byteblowerll.byteblower.DHCPv4Protocol(*args, **kwargs)

Bases: AbstractObject

This is the entry point to configure the DHCP client behavior of a ByteBlowerPort.

A ByteBlowerPort can perform DHCP the get an IP address, gateway and netmask. Currently, no other options are supported but this will change in the future.

Users can configure the timing parameters used in the different stages of the DHCP protocol: - Discover

During the discover stage the ByteBlower port will broadcast discover messages.

Request

Once one or more offers are received the ByteBlower port will broadcast its request message. If acknowledge the ByteBlower port will start using this address.
Renew

When half of the lease time received in the acknowledge message of the request has passed, a ByteBlowerPort will sent a renew message to the server to extend its lease.

Although DHCP allows clients to use unicast messages in the Request stage, ByteBlower currently only supports broadcast messages in this stage.

A DHCPv4 Protocol also supports different retransmission strategies:

Fixed: This policy will use the same timeout value for each timeout.
RFCSuggested: This policy implements the policy described in :rfc:2131.

BroadcastFlagEnable(inValue)

Enables the DHCP broadcast flag

New in version 2.11.2.

Parameters:: enable (bool) – Whether or not to enable the Broadcast flag

When a ByteBlower port performs DHCP, the port will use the unicast DHCP method as described in the DHCP RFC. Pre-2.11.2 ByteBlower servers used the legacy broadcast technique, which is sometimes detected by devices as a broadcast storm.

Example

This example will enable the Broadcast flag and thus the legacy behavour of the ByteBlower server

dhcp_protocol = port_layer3_config.ProtocolDhcpGet()
dhcp_protocol.BroadcastFlagEnable(True)
print(dhcp_protocol.BroadcastFlagIsEnabled())

BroadcastFlagIsEnabled()

Returns whether or not the broadcast flag is enabled.

New in version 2.11.2.

Returns:: Whether or not the flag is enabled
Return type:: bool

When a ByteBlower port performs DHCP, the port will use the unicast DHCP method as described in the DHCP RFC. Pre-2.11.2 ByteBlower servers used the legacy broadcast technique, which is sometimes detected by devices as a broadcast storm.

Example

This example will enable the Broadcast flag and thus the legacy behavour of the ByteBlower server

dhcp_protocol = port_layer3_config.ProtocolDhcpGet()
dhcp_protocol.BroadcastFlagEnable(True)
print(dhcp_protocol.BroadcastFlagIsEnabled())

DHCPv4SessionInfoGet()

Returns the sessionInfo object for this DHCP Session.

Return type:: DHCPv4SessionInfo

This object contains all the DHCP sessionInfo like Tx,Rx, current leaseTime, giaddr etc…

Example

This example will return the DHCPv4SessionInfo object for this DHCP session.

print(dhcpProtocol.DHCPv4SessionInfoGet().DescriptionGet())

DiscoverInitialTimeoutGet(): Returns the current <InitialTimeout> for the DHCP