PluginDhcp

Authors: Jorge Somavilla (somavilla at dit.upm.es) Miguel Ferrer (mferrer at dit.upm.es) Francisco Jose Martin (fjmarin at dit.upm.es) Ferm&iacute;n Gal&aacute;n (galan at dit.upm.es) David Fern&aacute;ndez (david at dit.upm.es) version 1.0, January 29th, 2009

Introduction
The DHCP plugin is available since VNUML version 1.9 to configure and run scenarios with the facilities provided by the Dynamic Host Configuration Protocol (DHCP).

DHCP is a protocol like BOOTP (actually dhcpd includes much of the functionality of bootpd). It gives client machines "leases" for IP addresses and can automatically set their network configuration.

In current version 1.0, the virtual machines make use of the version 3 of the Internet Software Consortium's implementation of DHCP, dhcp3. For more information visit Internet Systems Consortium.

The binary packages currently used are dhcp3-server, dhcp3-relay and dhclient.

In order to configure the DHCP protocol, the user must specify the role(s) of the virtual machines that will act in the DHCP scenario. These can be either server, relay or client, or any combination of them.


 * For the DHCP servers, the plugin creates the configuration file /etc/dhcp3/dhcpd.conf
 * For the DHCP relays, the plugin creates the configuration file /etc/default/dhcp3-relay
 * For the DHCP clients, the plugin creates the configuration file /etc/dhcp3/dhclient.conf

In order to properly run the DHCP protocol, it is needed to start the server, relay and client daemons in those virtual machines were these roles have been configured. The task of generating the configuration files and starting/stoping daemons in the virtual machines is performed by the DHCP plugin.

The plugin is based on a configuration file. In order to be used in a VNUML scenario a line as the following one has to be included in the tag of the scenario specification files:



where dhcp_conf.xml is a file compliant with the Dhcp plugin language reference. Using this configuration file, several operations can be performed.

Operations
In order to configure and run the dhcp server, relay and client daemons, the Dhcp plugin will execute several taks at building mode (-t) of vnumlparser.pl and at execution mode (-x) of vnumlparser.pl

Building mode
At the moment of building the scenario,the Dhcp plugin executes two tasks:
 * Writing configuration files for server, relay and client daemons for each virtual machine where the DHCP functions are configured. In order to fill these files, the dhcp plugin will gather the information from the configuration file that is specified at tag at the virtual scenario's XML file.
 * Copying these files in the appropriate paths mentioned before in each virtual machine.

Execution mode
Since version 1.0, the Dhcp plugin recognizes 17 commands. According to the level of definition of the service and virtual machine affected by the command, we can classify the commands into three categories:

Generic commands
When executed, they have effect in all the plugins included with the tag in the tag of the scenario specification files. Inside the Dhcp plugin, they have the following functions. Starts every dhcp daemon (servers, relays and clients) in every virtual machine configured in the dhcp scenario. vnumlparser.pl -x start@dhcp_scenario.xml -v -u root Stops every dhcp daemon (servers, relays and clients) in every virtual machine configured in the dhcp scenario. vnumlparser.pl -x stop@dhcp_scenario.xml -v -u root
 * start
 * stop

Restarts every dhcp daemon (servers, relays and clients) in every virtual machine configured in the dhcp scenario. vnumlparser.pl -x restart@dhcp_scenario.xml -v -u root
 * restart

Plugin speciffic commands
When executed, they have effect in the Dhcp plugin without affecting the other possible plugins configured for the scenario. Inside the Dhcp plugin, they have the following functions. Starts every dhcp daemon (servers, relays and clients) in every virtual machine configured in the dhcp scenario. vnumlparser.pl -x dhcp-start@dhcp_scenario.xml -v -u root Stops every dhcp daemon (servers, relays and clients) in every virtual machine configured in the dhcp scenario. vnumlparser.pl -x dhcp-stop@dhcp_scenario.xml -v -u root Restarts every dhcp daemon (servers, relays and clients) in every virtual machine configured in the dhcp scenario. vnumlparser.pl -x dhcp-restart@dhcp_scenario.xml -v -u root
 * dhcp-start
 * dhcp-stop
 * dhcp-restart

Role speciffic commands
When executed, they have effect only in the machines where the specified role is present. Starts, stops, restarts, or forces the stop and start processes of all the server daemons in the scenario. vnumlparser.pl -x dhcp-server-start@dhcp_scenario.xml -v -u root vnumlparser.pl -x dhcp-server-stop@dhcp_scenario.xml -v -u root vnumlparser.pl -x dhcp-server-restart@dhcp_scenario.xml -v -u root vnumlparser.pl -x dhcp-server-force-reload@dhcp_scenario.xml -v -u root Starts, stops, restarts, or forces the stop and start processes of all the relay daemons in the scenario. vnumlparser.pl -x dhcp-relay-start@dhcp_scenario.xml -v -u root vnumlparser.pl -x dhcp-relay-stop@dhcp_scenario.xml -v -u root vnumlparser.pl -x dhcp-relay-restart@dhcp_scenario.xml -v -u root vnumlparser.pl -x dhcp-relay-force-reload@dhcp_scenario.xml -v -u root Starts, stops or restarts all the client daemons in the scenario. vnumlparser.pl -x dhcp-client-start@dhcp_scenario.xml -v -u root vnumlparser.pl -x dhcp-client-stop@dhcp_scenario.xml -v -u root vnumlparser.pl -x dhcp-client-restart@dhcp_scenario.xml -v -u root
 * dhcp-server-start; dhcp-server-stop; dhcp-server-restart; dhcp-server-force-reload
 * dhcp-relay-start; dhcp-relay-stop; dhcp-relay-restart; dhcp-relay-force-reload
 * dhcp-client-start; dhcp-client-stop; dhcp-client-restart

Explicit definition of virtual machine with flag -M
Any of the commands defined in the previous point can be executed in a user specified virtual machine and not in the rest, by means of adding the flag -M name_of_machine in the -x sequence. vnumlparser.pl -x dhcp-client-stop@dhcp_scenario.xml -v -u root -M uml5 In this case the command dhcp-client-stop will only be executed in the machine named uml5 in the XML configuration files. Before using -x mode with -M flag, the user should be certain that the machine specified has been configured with the appropriate role (in our example, uml5 must have a dhcp client role in the dhcp_conf.xml file). If there is no correspondence between the command executed and the roles configured in the specified machine, no action will be taken.

VM Definitions: 
This tag groups all virtual machine definitions for the dhcp configuration.

Attributes
The following attributes may appear in a  tag:

name
Required. Unique.

Specifies the name of the virtual machine, as it appears in XML scenario file.

type
Required. Unique. Specifies the type of the DHCP source package. In version 1.0, the only implemented type is "dhcp3". 

Tags
The following tags may appear in a  tag:

Optional. Unique.

When included, it indicates that the parent virtual machine will play (at least) the role of dhcp server in the deployed scenario.


Optional. Unique.

When included, it indicates the the period of time (in seconds) during which the IP leases from this server are valid. After this time, the DHCP clients will have to ask for renewal of the lease.

300

If this field is not included, the server will be configured with a default lease time of 120 seconds.

Required. Multiple.

Within the Tag we find configuration packages inside Tags. One group has the following components: 10.0.10.0 10.0.10.10    10.0.10.20  10.0.10.9  10.0.10.21  mydomain.org 
 *  Required. Unique. It must contain the attribute "mask" in decimal format and the base address of the subnet as unique child.
 * Optional. Multiple. Contains the definition of a range of ip addresses to be leased by the server, including Tags and for the first and last available addresses in that range.
 * : Optional. Multiple. One for each router available for the current subnet.
 * : Optional. Multiple. One for each domain name server available for the current subnet.
 * : Optional. Unique. The domain of the current subnet.
 * : Optional. Multiple. One for each host to be configured with permanent static ip address. Requires attributes name (name of the host), mac (hardware address of the host's network interface), and ip (static ip assigned to the host).

Optional. Unique.

When included, it indicates that the parent virtual machine will play (at least) the role of dhcp relay in the deployed scenario.

Inside the Tag we find one kind of component:
 * : Required. Multiple. One Tag for each DHCP server where the virtual machine relays DHCP messages.

10.0.0.1

Optional. Unique.

When included, it indicates that the parent virtual machine will play (at least) the role of dhcp client in the deployed scenario.

Inside the Tag we find one kind of component:
 * : Required. Multiple. One Tag for each one of the client's interfaces that will be configured using DHCP protocol.

2

Example


 10.0.0.0</ip> 10.0.0.10          10.0.0.20         10.0.0.9         10.0.0.21         dominio.org 10.0.10.0</ip> 10.0.10.10          10.0.10.20         10.0.10.9         <host name="Unicum" mac="AA:BB:CC:DD:EE:FF" ip="10.0.10.28"/> </vm>

<vm name="uml2" type="dhcp3"> 1</if> </vm>

<vm name="uml3" type="dhcp3"> 10.0.0.1  </vm>

<vm name="uml4" type="dhcp3"> 1</if> </vm>

</dhcp_conf>