The AMnet HOWTO

7. Execution Environment

This chapter contains information about the Execution Environment (EE) which is component controlled by the signalling described in the next chapter. Reading this chapter is therefore especially interesting for users who want to install and test the AMnet software or looking forward develop new AMnet modules.

7.1 What is the Execution Environment?

Composable services are constructed from service modules which reside within the EE. Each service module implements a well defined part of a give service. Beside service specific functionality such as media transcoding or flexible error control also basic communication protocol tasks such as network level packet de-/fragmentation, checksumming and packet header generation are performed within service modules.

The EE is created under control of the signalling. It is responsible for the loading of service modules and for the configuration. The EE offers configuration support, memory and timer management. The design of the EE allows the coexistence of more than one EE, where each environment is realized as a seperate process.

The basic execution works as followed:

the EE is being started
the EE is requested to load specific modules
the loaded modules are configured if needed
after a start request, the EE reads data from the LTAP device, transports it through the module chain and writes the data finally back to the LTAP device.

7.2 The Execution Environment's interface

The execution environment provides an interface that allows interactive (without making use of signalling) configuration by the user. In order to setup a test environment without signalling, the execution environment on the node has to be started manually. The EE resides in the amnet/user/ee directory and can be started there with the ee command. At startup, a log file amnet/user/ee is created in the current directory, which is used to store all status messages. To monitor the status output while the EE is running, a command like tail -f ee.log may be used. Besides, the EE can be invoced with a filename as its only parameter whereas the file contains a list of commands. These commands are executed automatically on startup and are useful to work with multiple EEs.

After invocation of the execution environment a list of all possible commands and their description can be obtained by issueing the help command. Therefore, the commands are not described in detail here. Errors during invocation are indicated by negative return values being displayed. A description of these error values can be obtained with the command errstring.

Before an example configuration of the EE is described, some remarks should be pointed out:

With setownip the EE can be assigned its own IP address. This option avoids problems which may be caused by a host with multiple interfaces. This is due to the problem, that a host with multiple interfaces returns different IP addresses on the gethostname() system call.
The EE uses two ``paths'' or ``chains'': One input chain and one output chain. The differences between these chains are: One packet is always accompanied by a struct manage *. This struct contains among other things information about the interface. The structs used in the input chain only contain information about the input interface, the packet was received on. The structs for packets in the output chain only contains information about the interface, the packet is to be sent to.
Besides ``external'' modules, which are loaded by usemodulebyname, ``internal'' functions exist, e.g. in order to process UDP/IP headers. These are accessible separately, which also means, that they have to be selected explicitely in order to be used.

An example configuration for an EE that is configured with a MPEG filter looks like the following:

setownip!10.0.2.2: See above.
useudpipinput: See above.
usemodulebyname!I!pc!libpc.so: Loads the external modules packet counter to count incoming packets. External modules have to be accessible by the path described with the LD_LIBRARY_PATH environment variable. This path is setup correctly by the setup script.
configure!pc!string!filename!pc.log: Sets the output file for the packet counter. string is the parameter type, filename the parameter name and pc.log the parameter value.
usemodulebyname!I!mp!libmpeg.so: Loads the external module for the filtering of MPEG streams.
configure!mp!int!quality!3: Sets the quality for the MPEG stream to 3. The propagation of the parameter ranges is currently an unsolved problem. This means that the user has to know, which module has to be configured with which parameters. Default values for all modules are stored in the module specification on the service module repository.
configure!mp!int!color!1: Sets the color for the MPEG stream.
configure!mp!int!skip!0: Sets the skip value for the MPEG stream.
configure!mp!int!slices!0: Sets the slices value for the MPEG stream.
useinternalfunc!I!sendPacket: This and the next command are needed to transmit processed packets again.
useinternalfunc!O!setupPacket
useudpipoutput: See above.
connecttos!5000!10.0.3.2!5000: This establishes a connection to the sender. This means that all data received by this port is processed by the EE.
connecttor!6000!10.0.3.2!6000: This establishes a connection to the receiver. This means that packet are transmitted by the EE over this port.
start: Activates the EE.