Submodules¶

lib.basicHostIPCLayer module¶

Default co-simulation application layer.

class lib.basicHostIPCLayer.basicHostIPCLayer(host_id, log_file, application_ids_mapping, managed_application_id, params)¶

Bases: threading.Thread

Default application layer of co-simulation processes spawned inside mininet hosts

A co-simulation process may implement a specific application layer by inheriting from this class. Co-simulation processes may interact with the power simulator through by making GRPC calls to the proxy.

cancel_thread()¶

Send a command to terminate this thread

Returns:	None

Note

Do not override

get_curr_cmd()¶

Gets the current pending command sent by the co-simulation host process

Returns:	str or None – the command sent from the process to this thread

Note

Do not override

on_rx_pkt_from_network(pkt)¶

This function gets called on reception of message from network.

It may be overriden in the specific application layer implementation for a variety of purposes

Parameters:	pkt (str) – A packet string of the CyberMessage proto format specified in srcs/proto/css.proto
Returns:	None

on_shutdown()¶

This function gets called upon shutdown of the thread.

It may be overridden in specific application layer implementations for cleanup

Returns:	None

on_start_up()¶

This function gets called on thread start up after all initilization is complete.

It may be overridden in specific application layer implementations for starting user defined services.

Returns:	None

run()¶

Main run function which starts the thread functionality

Monitors the mininet network on ip,port specified for the assigned application_id. Upon receiving a packet intended for this application, it calls on_rx_packet_from_network

Returns:	None

Note

Do not override

tx_pkt_to_powersim_entity(pkt)¶

Transmit a co-simulation packet over the mininet cyber network

Parameters:	pkt (str) – A packet string which is converted to CyberMessage proto and sent over the network
Returns:	None

Note

Do not override

lib.defines module¶

Helper functions.

lib.defines.decode_raw_ip_payload_src_dst(buf)¶

Get src,dst ip address from raw ip payload string

Parameters:	buf – A string buffer containing raw ip payload
Returns:	A typle with source and destination IP strings

lib.defines.get_ip_ethernet(buf)¶

Unpack the data within the Ethernet frame (the IP packet)

Pulling out src, dst, length, fragment info, TTL, and Protocol

Parameters:	buf (str) – A string buffer containing the entire packet
Returns:	ip of type (dpkt.IP)

lib.defines.get_ip_loopback(buf)¶

Unpack the data within the Ethernet frame (the IP packet)

Pulling out src, dst, length, fragment info, TTL, and Protocol

Parameters:	buf (str) – A string buffer containing the entire packet
Returns:	ip of type (dpkt.IP)

lib.defines.get_ip_sll(buf)¶

Unpack the data within the SLL frame (the IP packet)

Pulling out src, dst, length, fragment info, TTL, and Protocol

Parameters:	buf (str) – A string buffer containing the entire packet
Returns:	ip of type (dpkt.IP)

lib.defines.get_pkt_src_dst_IP(buf, dl_type=1)¶

Get src and dst IP from raw packet string

Parameters:	buf (str) – A string buffer containing the entire packet dl_type (int) – Link Layer type defined in dpkt.pcap. (Default ETH_TYPE_FRAME)
Returns:	A tuple with source and destination IP strings

lib.defines.get_raw_ip_pkt(buf, dl_type=1)¶

Get IP payload from raw packet string

Parameters:	buf (str) – A string buffer containing the entire packet dl_type (int) – Link Layer type defined in dpkt.pcap. (Default ETH_TYPE_FRAME)
Returns:	A string buffer with IP payload

lib.defines.getid()¶

Returns a random unique string ID

Returns:	str

lib.defines.inet_to_str(inet)¶

Convert inet object to a string

Parameters:	inet (inet struct) – inet network address
Returns:	str of printable/readable IP address

lib.defines.rpc_process()¶

Sends a batch processing GRPC request request.

Called by Melody to initiate processing of all read/write requests received in the last batch.

Returns:	None

lib.defines.rpc_read(readlist)¶

Makes a GRPC read request call to the proxy. It may be used to read some values from the power simulation.

It takes in as input a list of read requests and composes and sends a single GRPC read request to the proxy. It waits until the proxy sends a response and returns the values contained in the response or None if there was an error.

Parameters:	readlist (list of tuples) – A list of tuples (objtype (str), objid (str), fieldtype (str)). Refer srcs/proto/pss.proto
Returns:	list of str or None

lib.defines.rpc_write(writelist)¶

Makes a GRPC write request call to the proxy. It may be used to write some values to the power simulation

It takes in as input a list of write requests and composes and sends a single GRPC write request to the proxy. It waits until the proxy sends a response and returns the status response or None if there was an error.

Parameters:	writelist (list of tuples) – A list of tuples (objtype (str), objid (str), fieldtype (str), value(str)). Refer srcs/proto/pss.proto
Returns:	list of int (Refer srcs/proto/pss.proto: WriteStatus) or None

lib.defines.str_to_inet(str)¶

Convert string object to an inet

Parameters:	str (str) – printable/readable IP address
Returns:	inet (inet struct) - an inet network address

lib.disturbance_gen module¶

Disturbance generator

lib.disturbance_gen.init_shared_buffers(shared_buf_array)¶

Initialize shared buffers used for communication with the main Melody process

Parameters:	shared_buf_array – A shared buffer array object (defined in srcs/core/shared_buffer.py)
Returns:	None

lib.disturbance_gen.main(path_to_disturbance_file)¶

Starts the disturbance generator and sends disturbances to the power simulation at specified relative timestamps

Disturbances and their relative timestamps are specified in a file according to the Disturbance message format defined in srcs/proto/configuration.proto

Parameters:	path_to_disturbance_file (str) – Absolute path to file containing disturbances specified in Disturbance proto format. (Refer srcs/proto/configuration.proto : Disturbances)
Returns:	None

lib.emulation_driver module¶

Emulation Driver

class lib.emulation_driver.EmulationDriver(input_params)¶

Bases: object

An emulation driver is responsible for emulating background flow traffic in the mininet network.

It is assigned a command to execute and spawned inside a mininet host. It forks a child process and executes the assigned command.

init_shared_buffers(driver_id, run_time)¶

Initialize shared buffers used for communication with the main Melody process

If the shared buffers cannot be opened successfully, the driver just sleeps for the specified amount of run time.

Parameters:	driver_id (str) – A unique id string assigned to this driver. The shared buffer is opened with this ID. run_time (int) – Running time of driver in seconds
Returns:	None

trigger()¶

Start executing the assigned command.

Forks a new process and starts the command.

Returns:	None

lib.emulation_driver.main()¶

Main entry point of the emulation_driver

Creates an emulation driver, initializes it and triggers executing the command at the right time. It also handles shutting down the driver.

Returns:	None

lib.host module¶

Co-simulation host.

lib.host.extract_mappings(net_cfg_file)¶

lib.host.init_shared_buffers(run_time, shared_buf_array, managed_application_id)¶

Initialize shared buffers used for communication with the main Melody process

If the shared buffers cannot be opened successfully, the co-simulation host just sleeps for the specified amount of run time.

Parameters:	run_time (int) – Running time of co-simulation host in seconds shared_buf_array – A shared buffer array object (defined in srcs/lib/shared_buffer.py) managed_application_id (str) – The application_id assigned to this co-simulation host
Returns:	None

lib.host.main(host_id, net_cfg_file, log_file, run_time, project_name, app_layer_file, managed_application_id)¶

Main entry point of the co-simulation host

Starts the co-simulation host and its application layer thread.

Parameters:

host_id (int) – Mininet host number on which this process is run. (e.g 1 implies h1) net_cfg_file (str) – Absolute path of file containing a mapping of application ids to ip,port values log_file (str) – Absolute path of file where stdout will be logged. run_time (int) – Running time of co-simulated host in seconds project_name (str) – Name of the project app_layer_file (str) – Name of the file containing application layer code for this host. If not specified, a default basicHostIPC layer thread will be started for the co-simulation host. The app_layer_file must be located inside srcs/projects/project_name managed_application_id (str) – Name of the application assigned to this co-simulaiton host

Returns:

None

lib.host.parseOpts()¶

lib.host.usage()¶

lib.kronos_helper_functions module¶

lib.logger module¶

Melody Logger

class lib.logger.Logger(log_file, tag)¶

Bases: object

Simple Logger class for logging messages to stdout/log files

error(msg)¶

Logs a ERROR message

Parameters:	msg (str) – actual message string
Returns:	None

info(msg)¶

Logs a INFO message

Parameters:	msg (str) – actual message string
Returns:	None

log_msg(loglevel, tag, msg)¶

Appends message to file or prints to stdout

Parameters:	loglevel (str) – can be INFO or WARN or ERROR tag (str) – a tag added to the message msg (str) – actual message string
Returns:	None

warn(msg)¶

Logs a WARN message

Parameters:	msg (str) – actual message string
Returns:	None

lib.net_power module¶

Melody main orchestrator logic

class lib.net_power.NetPower(run_time, network_configuration, project_dir, base_dir, log_dir, emulated_background_traffic_flows, replay_traffic_flows, cyber_host_apps, enable_kronos, rel_cpu_speed, power_sim_spec)¶

Bases: object

Class which starts mininet, proxy, disturbance generator and manages their operation.

It initializes the project and brings it under the control of Kronos. It provides API to drive the co-simulation of mininet and a power simulator.

allow_icmp_requests()¶

Enables ICMP requests on all hosts

Returns:	None

allow_icmp_responses()¶

Allows ICMP responses on all hosts

Returns:	None

check_kronos_loaded()¶

Check if kronos is loaded

Returns:	Fails if Kronos is enabled but not loaded

cleanup()¶

Cleanup the emulation

Returns:	None

close_project()¶

To be called on finish

Returns:	None

cmd_to_start_process_under_tracer(cmd_to_run)¶

Gets a command string which can be started under kronos

Parameters:	cmd_to_run (str) – Command to run under kronos control
Returns:	str command to run

disable_TCP_RST()¶

Disables TCP_RST on all hosts

Returns:	None

enable_TCP_RST()¶

Enables TCP_RST on all hosts

Returns:	None

generate_node_mappings(roles)¶

Generate a dictionary which maps application_id to a hostname, ip and port. Stores this in /tmp

Parameters:	roles – list of tuples (host_name, [application_id, listen_port])
Returns:	None

get_application_id_attributes(application_id, project_config_file)¶

get_emulation_driver_params()¶

Construct list of emulated traffic flow objects

Returns:	None

get_number_of_tracers()¶

initialize_kronos_exp()¶

Initialize Kronos exp

Returns:	None

initialize_project()¶

Initialize the project

Starts all co-simulation hosts, switches, control network, proxy, packet captures, emulation & replay drivers and disturbance generator processes.

Returns:	None

open_main_cmd_channel_buffers()¶

Open shared buffer channels to all hosts

Shared buffer channels are used to control co-simulation hosts, replay drivers and emulation drivers.

Returns:	None or exits on Failure to open shared buffer channels

print_topo_info()¶

Prints topology information

run_for(run_time_ns, sync=True)¶

Runs the cyber emulation for the specified time in nano seconds.

The cyber emulation gets frozen after running for the specified duration iff it is under kronos control.

Parameters:	run_time_ns (int) – Batch run time in nano seconds sync (bool) – If True, it syncs with power simulator after running for the required time
Returns:	None

send_cmd_to_node(node_name, cmd)¶

Sends a command to execute on a mininet host

Parameters:	node_name (str) – mininet host name cmd (str) – command string to execute
Returns:	None

set_netdevice_owners()¶

Associates interfaces with Kronos so that packets are delayed in virtual time.

Returns:	None

start_all_host_captures()¶

Start packet captures in all hosts

Returns:	None

start_control_network()¶

Starts a separate control network which allows all mininet hosts to communicate outside the mininet network

The control network allows each host to send GRPC requests to the proxy.

Returns:	None

start_disturbance_generator()¶

Starts the disturbance generator process and brings it under the control of Kronos

The disturbance generator will send disturbances to the power simulator.

Returns:	None

start_emulation_drivers()¶

Starts all emulation drivers

Emulation drivers would control background traffic generation.

Returns:	None

start_host_capture(host_obj)¶

Start packet capture in each host

Parameters:	host_obj – mininet_host object
Returns:	None

start_host_processes()¶

Starts all co-simulation host processes

This starts all specified applications inside mininet hosts.

Returns:	None

start_pkt_captures()¶

Start packet captures in all host and switch interfaces

Returns:	None

start_proxy_process()¶

Starts the proxy process

Returns:	None

start_replay_drivers()¶

Starts all replay drivers

Replay drivers would control replaying all pcaps.

Returns:	None

start_replay_orchestrator()¶

Starts the replay orchestrator process

The replay orchestrator process will drive replaying pcaps.

Returns:	None

start_switch_processes()¶

Starts all mininet switch processes

Returns:	None

start_synchronized_experiment()¶

Start a synchronized kronos experiment if kronos is enabled

Returns:	None

stop_control_network()¶

Stops the control network which enables GRPC connectivity

Returns:	None

stop_synchronized_experiment()¶

Stop a synchronized kronos experiment if kronos is disabled

Returns:	None

sync_with_power_simulator()¶

Sends an RPC process request to the proxy.

This triggers batch processing which processes all read/write rpc requests sent in the previous batch.

Returns:	None

trigger_all_processes(trigger_cmd)¶

Sends a message over shared buffer channels to all co-simulated hosts, replay and emulation drivers

Parameters:	trigger_cmd (str) – command to send
Returns:	None

trigger_nxt_k_replays(k)¶

trigger_nxt_replay()¶

Sends a command to replay orchestrater

This queues a replay command on the replay orchestrator. The replay orchestrator will initate the next replay as soon as possible.

Returns:	None

wait_for_loaded_pcap_msg()¶

Waits for required pcaps to be loaded by all replay-drivers

Returns:	None

lib.net_power.stderr_redirected()¶

Lifted from: https://stackoverflow.com/questions/4675728/redirect-stdout-to-a-file-in-python

This is the only way I’ve found to redirect stdout with curses. This way the output from questionnaire can be piped to another program, without piping what’s written to the terminal by the prompters.

lib.parse_project_configuration module¶

lib.pss_driver module¶

Drivers for interacting with power system simulator.

class lib.pss_driver.PSSDriverAbstract¶

Bases: object

Abstract class for implementing power system simulation-specific driver.

close()¶

open()¶

read(case)¶

run_pf(method=None)¶

save(newcase)¶

write(objtype, objid, fieldtype, value)¶

write_multiple(writelist)¶

lib.pss_server module¶

The proxy is implemented as a GRPC server.

class lib.pss_server.Job(request, request_type, reply)¶

Bases: object

A data structure to store the GRPC read/write request, the reply, and an Event() object to signal when the reply is ready to be returned to the requester.

to_string()¶

class lib.pss_server.PSSServicer(pssDriver, caseFile)¶

Bases: srcs.proto.pss_pb2_grpc.pssServicer

process(request, context)¶

Function to handle GRPC process requests from simulation main loop. Requests, including both read and write requests, are processed in the timing order as given by their timestamps, not by the order in which they were enlisted to the job list. Process time may vary depending on the size of the job list and the type of requests.

Parameters:	request (pss_pb2.ProcessRequest) – a GRPC process request object.
Returns:	a pss_pb2.Status object.

read(readRequest, context)¶

Function to handle GRPC read requests from the simulated cyber network. Each GRPC read request is appended to the proxy’s job list, where each job contains the request and its related information. The proxy processes all items in the job list once it receives the GRPC process request. The GRPC process request is invoked by the simulation main loop.

Parameters:	readRequest (pss_pb2.ReadRequest) – a GRPC read request object, which is a list of requests sharing the same timestamp.
Returns:	a pss_pb2.ReadResponse object.

write(writeRequest, context)¶

Function to handle GRPC write requests from the simulated cyber network. Similar to GRPC read requests, each GRPC write request is also appended to the proxy’s job list, where each job contains the request and its related information. The proxy processes all items in the job list once it receives the GRPC process request. The GRPC process request is invoked by the simulation main loop.

Parameters:	writeRequest (pss_pb2.WriteRequest) – a GRPC write request object, which is a list of requests sharing the same timestamp.
Returns:	a pss_pb2.WriteStatus object

lib.pss_server.exit_gracefully(signum, frame)¶

lib.replay_driver module¶

Replay driver

class lib.replay_driver.ReplayDriver(input_params)¶

Bases: object

Controls replaying pcaps

init_shared_buffers(run_time)¶

Initializes shared buffers to allow communication with the main melody process

Parameters:	run_time (int) – run time in seconds. If the buffer cannot be opened, the driver would simply run for the specified amount and exit gracefully.
Returns:	None

load_pcap(pcap_file_path)¶

Loads a pcap specified by the pcap_file_path

Parameters:	pcap_file_path (str) – Absolute path to the pcap file
Returns:	None

load_pcaps()¶

Load all pcaps which involve this mininet host

Returns:	None

recv_command_message()¶

Gets command from the shared buffer

Returns:	string or None

send_command_message(msg)¶

Sends a message over the shared buffer

Parameters:	msg (str) – Message to send
Returns:	None

trigger_replay(pcap_file_path)¶

Triggers replay of the pcap_file specified by pcap_file_path

Note

The pcap file must have already been loaded before calling this.

Parameters:	pcap_file_path (str) – Absolute path to pcap file
Returns:	None

wait_for_commands()¶

Wait for a trigger replay command from the main melody process

Returns:	None

lib.replay_driver.main()¶

Creates a replay driver and calls wait_for_commands

Returns:	None

lib.replay_orchestrator module¶

Replay Orchestrator

class lib.replay_orchestrator.ReplayOrchestrator(net_power_obj, replay_plan_file)¶

Bases: threading.Thread

This thread orchestrates pcap replay by communicating with all replay drivers.

are_two_pcap_stages_conflicting(stage_1_nodes, stage_2_nodes)¶

Checks if two sets have nodes have any intersections

Parameters:	stage_1_nodes – list of host names stage_2_nodes – list of host names
Returns:	True if the intersection is not NULL, else False

cancel_thread()¶

get_curr_cmd()¶

is_pcap_stage_relevant(involved_hosts)¶

Checks if any node involved in the pcap doesn’t even exist in the emulation

Parameters:	involved_hosts – list of mininet host names
Returns:	True if all nodes involved are valid, else False

run()¶

Listens for queued commands from the main melody process and sends triggers to the appropriate replay drivers

send_command(cmd)¶

signal_pcap_replay_trigger(node_id, pcap_file_path)¶

Signals the pcap driver on “node_id” to run the pcap

Parameters:	node_id (str) – mininet host name pcap_file_path (str) – Absolute path to the pcap to be replayed
Returns:	None

trigger_replay(node_ids, pcap_file)¶

Sends a trigger command to all nodes specified in node_ids

Parameters:	node_ids – list of mininet host names pcap_file – pcap file to replay among those hosts
Returns:	None

lib.shared_buffer module¶

Shared Buffer

class lib.shared_buffer.shared_buffer(bufName, isProxy)¶

Bases: object

Uses the shared_buffer library defined in srcs/lib/libs

close()¶

Closes the shared buffer

open()¶

Opens the shared buffer

read()¶

Reads from the shared buffer :return: str or None

write(msg, dstID=0)¶

Write message to the shared buffer

Parameters:	msg (str) – message to write dstID – Not used

class lib.shared_buffer.shared_buffer_array¶

Bases: object

Can be used to create an array of shared buffers

close()¶

Closes all opened shared buffers

Returns:	None

open(bufName, isProxy)¶

Opens a new shared buffer and adds it to the array

Parameters:	bufName (str) – buffer name isProxy (int) – Specifies if the buffer is opened by the master or slave. 1-Master, 0-Slave
Returns:	None

read(bufName)¶

Reads a buffer specified by buffer name. It is Non-Blocking.

Parameters:	bufName (str) – buffer name to read
Returns:	str or None if there is nothing to read in the buffer.

read_until(bufName, cool_off_time=0.01)¶

Reads until something appears in the buffer.

Parameters:	bufName (str) – buffer name to read cool_off_time (float) – time to sleep in secs between two successive reads
Returns:	str

write(bufName, msg, dstID=0)¶

Write a message to the buffer.

Parameters:	bufName (str) – buffer name to write msg (str) – Message to write dstID – Not used
Returns:	number of bytes written (int)

Module contents¶