SatelliteLab: Configuration files

Overview | Download | Publications | Documentation | Contact

SatelliteLab: Configuration files

This document explains the various settings that can be added to planet and sun configuration files.

Planet configuration

The planet configuration file has a single section called [general], which can contain the following settings:

	`logFile=<filename>`		Creates a log file with the specified name.
	`logLevel={0..4}`		Controls the amount of information that is written to the log file. 0 means warnings only; the highest level is 4.
	`logFlush={yes\|no}`		If set to `yes`, causes the planet to call fflush() after each line that is written to the log. Increases latency, but useful for debugging.
	`eventFile=<filename>`		Causes the planet to record all packet exchanges in a special kind of log file. Useful for benchmarking.
	`writeStatistics={yes,no}`		Causes the planet to periodically log some statistics for each local satellite.
	`planetlab={yes\|no}`		When set to `yes`, causes the planet to open the TUN/TAP device in a way that is compatible with PlanetLab OS.
	`virtualIP=<ip>`		Sets the IP address of the TUN/TAP device. Cannot be used on PlanetLab.
	`virtualNetmask=<mask>`		Sets the netmask of the TUN/TAP device. Cannot be used on PlanetLab.
	`enableSun={yes\|no}`		When this is enabled, the planet periodically sends status reports to the sun. This is required for any experiment that uses the global testbed. In a local experiment, it allows the sun to display the testbed status.
	`sun=<ip:port>`		Specifies the IP address and port number of the sun. The default is `galaxy.octarine.de:30000`.
	`allocation={static,dynamic}`		Controls how the planet obtains the satellite-to-planet mapping. When the `static` setting is used, the mapping is loaded from `allocationFile`; with the `dynamic` setting, the mapping is obtained from the sun.
	`allocationFile=<filename>`		When static allocation is used, this must contain the name of the file with the satellite-to-planet mapping.
	`experiment=<name>`		Specifies a name for the current experiment. With dynamic allocation, this setting is required and must match the name that was used to register the experiment with the sun.
	`owner=<id>`		Specifies the owner of the current experiment. With dynamic allocation, this setting is required and must match your testbed user name.
	`lossProtection={yes,no}`		When loss protection is enabled, the planet tries to recover lost control packets by including some recent packet IDs in each probe packet, and by inspecting the history list in each response packet.
	`extraProbes={yes,no}`		When enabled, causes the planet to send an extra probe whenever a satellite's link is idle for more than a specified time. In combination with loss protection, this can be used to mask a loss of the `last' control packet in a flow. The idle timeout can be set with the `extraProbeDelay setting.`
	`extraProbeDelay=<ms>`		Specifies the idle timeout to be used with `extraProbes` (in milliseconds).
	`startProcessesWhenOnline={yes,no}`		When enabled, causes the planet to run a specific command (such as a shell script) whenever a new satellite associates with it. The command line is set with `satelliteCommand`.
	`killProcessesWhenOffline={yes,no}`		When this is enabled and a satellite goes offline, the planet sends a `SIGHUP signal to any processes it has started for that satellite.`
	`satelliteCommand=<cmd>`		Command line to run when a satellite comes online. The environment variable `NODEID` is automatically set to the number of the satellite in question; the first satellite has the number 1.
	`daemon={yes,no}`		When enabled, the planet runs as a daemon in the background.
	`port=<number>`		Sets the port pair to use for communicating with satellites and other planets. The port specified here (default: 30000) is used for satellites; the following port is used for planets.
	`receiveBufferSize=<bytes>`		Controls the size of the UDP receive buffer. Increasing this may reduce packet loss on machines with high scheduling delays, such as PlanetLab nodes.
	`writeTimestamps={yes,no}`		Causes the planet to record timestamps in specially formatted packets; useful for profiling and debugging.
	`enforceMSS=<bytes>`		When set, causes the planet to limit the maximum segment size (MSS) of TCP flows by adding a MSS option to TCP SYN packets. Since the planets encapsulate each IP packet in a UDP packet when tunneling it to another planet, using a MSS of 1500 bytes would cause IP fragmentation.
	`pathToLibIpAddr=<path>`		Specifies the path to `libipaddr.so`. This library is preloaded whenever the planet starts any applications for a satellite (see also `satelliteCommand`).

Sun configuration

The sun configuration file has a single section called [general], which can contain the following settings:

	`logFile=<filename>`		Creates a log file with the specified name.
	`logLevel={0..4}`		Controls the amount of information that is written to the log file. 0 means warnings only; the highest level is 4.
	`logFlush={yes\|no}`		If set to `yes`, causes the sun to call fflush() after each line that is written to the log. Increases latency, but useful for debugging.
	`append={yes\|no}`		If set to `yes` and a log file already exists, causes the sun append to it rather than overwriting it.
	`daemon={yes,no}`		When enabled, the sun runs as a daemon in the background.
	`port=<number>`		Specifies the UDP port number to use (default is 30000).
	`webInterface={yes,no}`		Enables or disables the web interface.
	`adminUsername=<user>`		Sets the administrator's username for the web interface.
	`adminPassword=<user>`		Sets the administrator's password for the web interface.
	`database={file,mysql,dynamic}`		Controls which database the sun uses; `file` should only be used for experiments with static allocation, `mysql` is for full-service testbeds, like the global testbed, and `dynamic` is for local testbeds where all satellites are allocated to the same experiment.
	`mysqlDbName=<name>`		When `database=mysql` is used, sets the name of the mySQL database.
	`mysqlUsername=<name>`		When `database=mysql` is used, sets the name of the mySQL account the sun should use.
	`mysqlPassword=<passwd>`		When `database=mysql` is used, sets the password of the mySQL account the sun should use.
	`databaseFile=<file>`		When `database=file` is used, sets the name of the file with the satellite-to-planet mapping.
	`experiment=<name>`		When `database=file` is used, sets the name of the current experiment.
	`owner=<id>`		When `database=file` is used, sets the owner of the current experiment.