PluginDhcp

Dhcp Plugin

Authors:
Jorge Somavilla (somavilla at dit.upm.es)
Miguel Ferrer (mferrer at dit.upm.es)
Francisco Jose Martin (fjmarin at dit.upm.es)
Fermín Galán (galan at dit.upm.es)
David Ferná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 <global> tag of the scenario specification files:

<extension plugin="dhcp" conf="dhcp_conf.xml" />

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 <extension plugin> 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 <extension> in the <global> tag of the scenario specification files. Inside the Dhcp plugin, they have the following functions.

• start

Starts every dhcp daemon (servers, relays and clients) in every virtual machine configured in the dhcp scenario.

vnumlparser.pl -x start@dhcp_lab.xml -v -u root

• stop

Stops every dhcp daemon (servers, relays and clients) in every virtual machine configured in the dhcp scenario.

vnumlparser.pl -x stop@dhcp_lab.xml -v -u root

• restart

Restarts every dhcp daemon (servers, relays and clients) in every virtual machine configured in the dhcp scenario.

vnumlparser.pl -x restart@dhcp_lab.xml -v -u root

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.

• dhcp-start

Starts every dhcp daemon (servers, relays and clients) in every virtual machine configured in the dhcp scenario.

vnumlparser.pl -x dhcp-start@dhcp_lab.xml -v -u root

• dhcp-stop

Stops every dhcp daemon (servers, relays and clients) in every virtual machine configured in the dhcp scenario.

vnumlparser.pl -x dhcp-stop@dhcp_lab.xml -v -u root

• dhcp-restart

Restarts every dhcp daemon (servers, relays and clients) in every virtual machine configured in the dhcp scenario.

vnumlparser.pl -x dhcp-restart@dhcp_lab.xml -v -u root

Role speciffic commands

When executed, they have effect only in the machines where the specified role is present.

• dhcp-server-start; dhcp-server-stop; dhcp-server-restart; dhcp-server-force-reload

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_lab.xml -v -u root
vnumlparser.pl -x dhcp-server-stop@dhcp_lab.xml -v -u root
vnumlparser.pl -x dhcp-server-restart@dhcp_lab.xml -v -u root
vnumlparser.pl -x dhcp-server-force-reload@dhcp_lab.xml -v -u root

• dhcp-relay-start; dhcp-relay-stop; dhcp-relay-restart; dhcp-relay-force-reload

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_lab.xml -v -u root
vnumlparser.pl -x dhcp-relay-stop@dhcp_lab.xml -v -u root
vnumlparser.pl -x dhcp-relay-restart@dhcp_lab.xml -v -u root
vnumlparser.pl -x dhcp-relay-force-reload@dhcp_lab.xml -v -u root

• dhcp-client-start; dhcp-client-stop; dhcp-client-restart

Starts, stops or restarts all the client daemons in the scenario.

vnumlparser.pl -x dhcp-client-start@dhcp_lab.xml -v -u root
vnumlparser.pl -x dhcp-client-stop@dhcp_lab.xml -v -u root
vnumlparser.pl -x dhcp-client-restart@dhcp_lab.xml -v -u root

Explicit definition of virtual machine with flag -M

Any of the commands defined in the previous point can be executed in a user defined 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_lab.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.

Language reference

VM Definitions: <vm>

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

Attributes

The following attributes may appear in a <vm> 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".

<vm name="vm1" type="dhcp3">

Tags

The following tags may appear in a <vm> tag:

<server>

Optional. Unique.

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

<subnet>

Required. Multiple.

Within the <server> Tag we find configuration packages inside <subnet> Tags. One <subnet> group has the following components:

• <ip> Required. Unique. It must contain the attribute "mask" in decimal format and the base address of the subnet as unique child.

<ip mask="24">10.0.10.0</ip>

• <range> Optional. Multiple. Contains the definition of a range of ip addresses to be leased by the server, including Tags <first> and <last> for the first and last available addresses in that range.

<range>
   <first>10.0.10.10</first>
   <last>10.0.10.20</last>
</range>

• <router>: Optional. Multiple. One for each router available for the current subnet.

<router>10.0.10.9</router>

• <dns>: Optional. Multiple. One for each domain name server available for the current subnet.

<dns>10.0.10.21</dns>

• <domain>: Optional. Unique. The domain of the current subnet.

<domain>mydomain.org</domain>

• <host>: 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).

<host name="Unicum" mac="AA:BB:CC:DD:EE:FF" ip="10.0.10.21"/>

<relay>

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 <relay> Tag we find one kind of component:

• <toserver>: Required. Multiple. One Tag for each DHCP server where the virtual machine relays DHCP messages.

<toserver>10.0.0.1</toserver>

<client>

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 <client> Tag we find one kind of component:

• <if>: Required. Multiple. One Tag for each one of the client's interfaces that will be configured using DHCP protocol.

<if>2</if>

Example

<dhcp_conf>

  <vm name="uml1" type="dhcp3">
    <server>
      <subnet>
        <ip mask="24">10.0.0.0</ip>
        <range>
          <first>10.0.0.10</first>
          <last>10.0.0.20</last>
        </range>
        <router>10.0.0.9</router>
        <dns>10.0.0.21</dns>
        <domain>dominio.org</domain>
      </subnet>
      <subnet>
        <ip mask="24">10.0.10.0</ip>
        <range>
          <first>10.0.10.10</first>
          <last>10.0.10.20</last>
        </range>
        <router>10.0.10.9</router>
        <host name="Unicum" mac="AA:BB:CC:DD:EE:FF" ip="10.0.10.28"/>
      </subnet>
    </server>
  </vm>

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

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

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

</dhcp_conf>