ExternalEnvironment

simple module

Executes a setup command on the host OS during initialization and another teardown command during module destruction. For example, it can be used to configure virtual network interfaces.

The commands can be executed in the context of a network namespace (Linux only). The network namespace may already exist in the host OS before the simulation starts, or it can be created as a global namespace under /var/run/netns/, or it can be created as a process-local namespace.

To run a command that requires elevated privileges without sudo, user and network namespaces need to be unshared from the host OS (unshare-namespaces = true). In this case, the state of the host OS's external processes are not accessible from the unshared namespace in the usual way (e.g. displaying routing tables with ip route). To work around this, use nsenter:

sudo nsenter -t <PID> -n <command>

PID is the ID of the process running in the unshared namespace.

To list process IDs in all network namespaces:

sudo lsns -t net

<b>See also:</b> ~ExternalApp, ~ExternalProcess

Inheritance diagram

The following diagram shows inheritance relationships for this type. Unresolved types are missing from the diagram.

Used in compound modules

Name	Type	Description
ExternalApp	compound module	Provides an external application that uses a host OS external process.
NodeBase	compound module	The fundamental infrastructure for all network nodes focusing on non-communication aspects of network nodes.

Extends

Name	Type	Description
SimpleModule	simple module	Base module for all INET simple modules.

Parameters

Name	Type	Default value	Description
displayStringTextFormat	string	""	Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
initStage	int	0	Initialization stage for the setup command
globalNamespace	bool	false	Create new network namespaces under /var/run/netns/ (Linux only)
namespace	string	""	Name of the host OS network namespace (optional) (Linux only)
setupCommand	string	""	A host OS system command
teardownCommand	string	""	A host OS system command

Properties

Name	Value	Description
class	ExternalEnvironment
display	i=block/app

Source code

//
// Executes a setup command on the host OS during initialization and another teardown
// command during module destruction. For example, it can be used to configure
// virtual network interfaces.
//
// The commands can be executed in the context of a network namespace (Linux only).
// The network namespace may already exist in the host OS before the simulation
// starts, or it can be created as a global namespace under /var/run/netns/, or
// it can be created as a process-local namespace.
//
// To run a command that requires elevated privileges without sudo, user and
// network namespaces need to be unshared from the host OS (unshare-namespaces = true).
// In this case, the state of the host OS's external processes are not accessible
// from the unshared namespace in the usual way (e.g. displaying routing tables with `ip route`).
// To work around this, use `nsenter`:
//
//    sudo nsenter -t <PID> -n <command>
//
// PID is the ID of the process running in the unshared namespace.
//
// To list process IDs in all network namespaces:
//
//    sudo lsns -t net
//
//
// @see ~ExternalApp, ~ExternalProcess
//
simple ExternalEnvironment extends SimpleModule
{
    parameters:
        @class(ExternalEnvironment);
        int initStage = default(0); // Initialization stage for the setup command
        bool globalNamespace = default(false); // Create new network namespaces under /var/run/netns/ (Linux only)
        string namespace = default(""); // Name of the host OS network namespace (optional) (Linux only)
        string setupCommand = default(""); // A host OS system command
        string teardownCommand = default(""); // A host OS system command
        @display("i=block/app");
}

File: src/inet/common/ExternalEnvironment.ned