Difference between revisions of "PluginDhcp"

From VNUML-WIKI
Jump to: navigation, search
(Created page with '{{Title|Dhcp Example}} <big> Authors: '''Miguel Ferrer (mferrer at dit.upm.es)''' '''Francisco Jose Martin (fjmarin at dit.upm.es)''' '''Jorge Somavilla (somavilla at dit.up...')
 
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Title|Dhcp Example}}
+
{{Title|Dhcp Plugin}}
  
 
<big>
 
<big>
 
  Authors:
 
  Authors:
 +
'''Jorge Somavilla (somavilla at dit.upm.es)'''
 
  '''Miguel Ferrer (mferrer at dit.upm.es)'''
 
  '''Miguel Ferrer (mferrer at dit.upm.es)'''
 
  '''Francisco Jose Martin (fjmarin at dit.upm.es)'''
 
  '''Francisco Jose Martin (fjmarin at dit.upm.es)'''
'''Jorge Somavilla (somavilla at dit.upm.es)'''
 
 
  '''Ferm&iacute;n Gal&aacute;n (galan at dit.upm.es)'''
 
  '''Ferm&iacute;n Gal&aacute;n (galan at dit.upm.es)'''
 
  '''David Fern&aacute;ndez (david at dit.upm.es)'''
 
  '''David Fern&aacute;ndez (david at dit.upm.es)'''
Line 12: Line 12:
  
 
__TOC__
 
__TOC__
 +
  
  
 
== Introduction ==
 
== Introduction ==
This is a simple usage example for the VNUMl [DHCP Plugin/DHCP Plugin].
 
== Binaries ==
 
There are two binaries currently not included in VNUML available filesystems:
 
*dhcp3-server
 
*dhcp3-relay
 
Please download the following filesystem for your DHCP simulation.
 
  
== Scenario ==
+
The DHCP plugin is available since VNUML version 1.9 to configure and
[[Imagen:Dhcp-simple.png]]
+
run scenarios with the facilities provided by the Dynamic Host Configuration Protocol (DHCP).
== VNUML Description ==
+
 
<pre>
+
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.
<?xml version="1.0" encoding="UTF-8"?>
+
 
<!DOCTYPE vnuml SYSTEM "/usr/share/xml/vnuml/vnuml.dtd">
+
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 [http://www.isc.org/ 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
  
VNUML DHCP Test Scenario (1)
+
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:
  
<vnuml>
+
<extension plugin="dhcp" conf="dhcp_conf.xml" />
  <global>
 
    <version>1.9</version>
 
    <simulation_name>dhcp_ejemplo</simulation_name>
 
    <automac/>
 
    <vm_mgmt type="none" />
 
    <vm_defaults exec_mode="mconsole">
 
      <filesystem type="cow">/usr/share/vnuml/filesystems/root_fs_tutorial</filesystem>
 
      <kernel>/usr/share/vnuml/kernels/linux</kernel>
 
      <console id="0">xterm</console>
 
    </vm_defaults>
 
    <extension plugin="dhcp" conf="dhcp_ejemplo.xml" />
 
  </global>
 
  
  <net name="Net0" mode="uml_switch" />
+
where dhcp_conf.xml is a file compliant with the [[#Language_reference|Dhcp plugin language reference]]. Using this configuration file, several [[#Operations|operations]] can be performed.
  <net name="Net1" mode="uml_switch" />
 
  <net name="Net2" mode="uml_switch" />
 
  
  <vm name="s1">
+
== Operations ==
    <if id="1" net="Net0">
 
      <ipv4>10.0.0.1</ipv4>
 
    </if>
 
    <route type="ipv4" gw="10.0.0.2">default</route>
 
  </vm>
 
  
  <vm name="c1">
+
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
    <if id="1" net="Net0"/>
 
  </vm>
 
  
  <vm name="r1">
+
=== Building mode ===
    <if id="1" net="Net0">
 
      <ipv4>10.0.0.2</ipv4>
 
    </if>
 
    <if id="2" net="Net1">
 
      <ipv4>10.0.10.1</ipv4>
 
    </if>
 
    <route type="ipv4" gw="10.0.10.2">10.1.10.0/24</route>
 
    <forwarding type="ip"/>
 
  </vm>
 
  
  <vm name="c2">
+
At the moment of building the scenario,the Dhcp plugin executes two tasks:
    <if id="1" net="Net1">
+
*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.
    </if>
+
*Copying these files in the appropriate paths mentioned before in each virtual machine.
  </vm>
 
  
  <vm name="c3">
+
=== Execution mode ===
    <if id="1" net="Net1">
 
    </if>
 
  </vm>
 
 
  <vm name="r2">
 
    <if id="1" net="Net1">
 
      <ipv4>10.0.10.2</ipv4>
 
    </if>
 
    <if id="2" net="Net2">
 
      <ipv4>10.1.10.1</ipv4>
 
    </if>
 
    <route type="ipv4" gw="10.0.10.1">10.0.0.0/24</route>
 
    <forwarding type="ip"/>
 
  </vm>
 
  
  <vm name="c4">
+
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:
    <if id="1" net="Net2"/>
 
  </vm>
 
  
  <vm name="c5">
+
==== Generic commands ====
    <if id="1" net="Net2"/>
+
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.
  </vm>
+
*''start''
 +
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
 +
*''stop''
 +
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
  
</vnuml>
+
*''restart''
</pre>
+
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
  
== DHCP Description ==
+
==== Plugin speciffic commands ====
<pre>
+
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.
<?xml version='1.0' encoding='UTF-8'?>
+
*''dhcp-start''
<!DOCTYPE dhcp_conf SYSTEM '/usr/share/xml/vnuml/dhcp.dtd'>
+
Starts every dhcp daemon (servers, relays and clients) in every virtual machine configured in the dhcp scenario.
<dhcp_conf>
+
vnumlparser.pl -x dhcp-start@dhcp_scenario.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_scenario.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_scenario.xml -v -u root
  
  <vm name="s1" type="dhcp3">
+
==== Role speciffic commands ====
    <server>
+
When executed, they have effect only in the machines where the specified role is present.
      <subnet>
+
*''dhcp-server-start''; ''dhcp-server-stop''; ''dhcp-server-restart''; ''dhcp-server-force-reload''
        <ip mask="24">10.0.0.0</ip>
+
Starts, stops, restarts, or forces the stop and start processes of all the server daemons in the scenario.
<range>
+
vnumlparser.pl -x dhcp-server-start@dhcp_scenario.xml -v -u root
  <first>10.0.0.10</first>
+
vnumlparser.pl -x dhcp-server-stop@dhcp_scenario.xml -v -u root
  <last>10.0.0.20</last>
+
vnumlparser.pl -x dhcp-server-restart@dhcp_scenario.xml -v -u root
        </range>
+
vnumlparser.pl -x dhcp-server-force-reload@dhcp_scenario.xml -v -u root
        <router>10.0.0.2</router>
+
*''dhcp-relay-start''; ''dhcp-relay-stop''; ''dhcp-relay-restart''; ''dhcp-relay-force-reload''
      </subnet>
+
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
 +
*''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_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
  
      <subnet>
+
==== Explicit definition of virtual machine with flag -M ====
        <ip mask="24">10.0.10.0</ip>
+
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.
<range>
+
  vnumlparser.pl -x dhcp-client-stop@dhcp_scenario.xml -v -u root -M uml5
  <first>10.0.10.10</first>
+
In this case the command dhcp-client-stop will only be executed in the machine named uml5 in the XML configuration files.
  <last>10.0.10.20</last>
+
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.
        </range>
 
        <router>10.0.10.1</router>
 
        <router>10.0.10.2</router>
 
      </subnet>
 
  
      <subnet>
+
== Language reference ==
        <ip mask="24">10.1.10.0</ip>
 
<range>
 
  <first>10.1.10.10</first>
 
  <last>10.1.10.20</last>
 
        </range>
 
        <router>10.1.10.1</router>
 
      </subnet>
 
     
 
    </server>
 
  </vm>
 
  
 +
=== VM Definitions: <vm> ===
  
  <vm name="r1" type="dhcp3">
+
This tag groups all virtual machine definitions for the dhcp configuration.
    <relay>
 
      <toserver>10.0.0.1</toserver>
 
    </relay>
 
  </vm>
 
  
  <vm name="r2" type="dhcp3">
+
====Attributes====
    <relay>
 
      <toserver>10.0.0.1</toserver>
 
    </relay>
 
  </vm>
 
  
 +
The following '''attributes''' may appear in a <vm> tag:
  
  <vm name="c1" type="dhcp3">
+
=====name=====
    <client>
+
Required. Unique.
      <if>1</if>
 
    </client>
 
  </vm>
 
  <vm name="c2" type="dhcp3">
 
    <client>
 
      <if>1</if>
 
    </client>
 
  </vm>
 
  <vm name="c3" type="dhcp3">
 
    <client>
 
      <if>1</if>
 
    </client>
 
  </vm>
 
  <vm name="c4" type="dhcp3">
 
    <client>
 
      <if>1</if>
 
    </client>
 
  </vm>
 
  <vm name="c5" type="dhcp3">
 
    <client>
 
      <if>1</if>
 
    </client>
 
  </vm>
 
  
</dhcp_conf>
+
Specifies the name of the virtual machine, as it appears in XML scenario file.
</pre>
 
  
== Testing ==
+
=====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:
  
For the whole simulation the user should acquire root privileges in the host.
+
=====<server>=====
sudo su
+
Optional. Unique.
Launch the simulation with flag -t
 
vnumlparser.pl -t scenario_example.xml -v -u root
 
Once VNUML has deployed the scenario, the user can start executing commands in the host. The following sequence is proposed:
 
  
 +
When included, it indicates that the parent virtual machine will play (at least) the role of dhcp server in the deployed scenario.
  
*'''''global start'''''
+
======<lease_time>======
In the host, execute
+
Optional. Unique.
vnumlparser.pl -x dhcp-start@scenario_example.xml -v -u root
 
which will start all dhcp servers, relays and clients in the scenario. Depending on the complexity of the scenario, the time needed for convergence is variable.
 
  
 +
When included, it indicates 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.
  
*'''''dhcp testing'''''
+
  <lease_time>300</lease_time>
In order to check that dhcp started and works correctly, the user can login in the virtual machines (login:root password:xxxx), and check their status.
 
In the server, the user can consult the status of the dhcp server service
 
  /etc/init.d/dhcp3-server status
 
which should return the line
 
Status of DHCP server: dhcpd3 is running.
 
and also check that the server daemon is running
 
ps aux | grep dhcpd | grep -v grep
 
which will return the information about the process if it is launched.
 
In the relays, the user can check if the relay daemons are running
 
  ps aux | grep dhcrelay | grep -v grep
 
In the clients, the user can log in and check that they acquired a valid IP in the corresponding interface (in current example eth1)
 
ifconfig eth1
 
which for example executed in the client c5, will return a piece of information where the user can find something similar to
 
inet addr:10.1.10.11
 
The user can as well check for the running dhcp client daemon
 
ps aux | grep dhclient | grep -v grep
 
For testing purposes, the dhcp server is configured with lease time of 120 seconds, which means that clients must renew their IP leases every 120 seconds. This periodic requests can be observed running the following command in any client:
 
tcpdump -i eth1
 
  
 +
If this field is not included, the server will be configured with a default lease time of 120 seconds.
  
*'''''relays stop'''''
+
======<subnet>======
Back in the host, the user can execute the following command
+
Required. Multiple.
  vnumlparser.pl -x dhcp-relay-stop@scenario_example.xml -v -u root
 
which will stop all the relay services in the scenario.
 
Even if the relay services are stopped, the dhcp clients will already have the information about the dhcp server of the current lease, stored in the file /var/lib/dhcp/dhclient.leases.
 
Therefore, the clients will be able to renew the IP leases with no need of the relays, including the information about the servers in the dhcp request. the user can check this invoking the following command, for example in the client c5
 
tcpdump -i eth1
 
Every 120 seconds, the interface will register IP renewal petitions like the following one, with the ip of the server (10.0.0.1):
 
12:00:46.015412 IP 10.1.10.11.bootpc > 10.0.0.1.bootps: BOOTP/DHCP, Request from fe:fd:00:00:09:01 (oui Unknown), length 300
 
and the replies from the server
 
12:00:46.016610 IP 10.0.0.1.bootps > 10.1.10.11.bootpc: BOOTP/DHCP, Reply, length 300
 
  
 +
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"/>
  
*'''''clients restart'''''
+
=====<relay>=====
With the relays stopped, the user can now restart the clients, killing the client processes in every virtual machine and starting new daemons,
+
Optional. Unique.
vnumlparser.pl -x dhcp-client-restart@scenario_example.xml -v -u root
 
However, the new client daemons won't have the information of the server anymore, hence none of them will be able to reach the server with their petitions ('ifconfig eth1' will show no ip address acquired in the clients), except for the client c1, that does not need a working relay as it's in the same subnet as the dhcp server.
 
  
 +
When included, it indicates that the parent virtual machine will play (at least) the role of dhcp relay in the deployed scenario.
  
*'''''start relay 1'''''
+
Inside the <relay> Tag we find one kind of component:
If the user starts the relay 1
+
*<toserver>: Required. Multiple. One Tag for each DHCP server where the virtual machine relays DHCP messages.
vnumlparser.pl -x dhcp-relay-start@scenario_example.xml -v -u root -M r1
 
The clients (which are configured by the plugin to retry address acquisition every 10 seconds untill success) will keep sending their dhcp requests, except for c1 that was already configured. The requests from c2 and c3, sent to the broadcast address of the network 10.0.10/24 will reach both r2 (relay down) and r1 (relay running), and will be correctly redirected to the server s1 by r1. However the requests from the clients c4 and c5 will only reach r2 (relay down), and won't be relayed forward.
 
As a result, after the convergence time, clients c2 and c3 will acquire IP address, unlike c4 and c5. This can be tested in each client with the command
 
ifconfig eth1
 
  
 +
<toserver>10.0.0.1</toserver>
 +
  
*'''''stop relay 1'''''; '''''clients restart'''''
+
=====<client>=====
This will bring the scenario back to the status prior to relay 1 restart, where only c1 had acquired IP.
+
Optional. Unique.
vnumlparser.pl -x dhcp-relay-stop@scenario_example.xml -v -u root -M r1
 
vnumlparser.pl -x dhcp-client-restart@scenario_example.xml -v -u root
 
  
 +
When included, it indicates that the parent virtual machine will play (at least) the role of dhcp client in the deployed scenario.
  
*'''''start relay 2'''''
+
Inside the <client> Tag we find one kind of component:
The user can now test what is the effect of starting the relay 2 instead
+
*<if>: Required. Multiple. One Tag for each one of the client's interfaces that will be configured using DHCP protocol.
vnumlparser.pl -x dhcp-relay-start@scenario_example.xml -v -u root -M r2
 
The clients c2, c3, c4 and c5 will keep sending their dhcp requests, which will now find a working relay that will redirect them to the right server. Even if the relay r1 is not active, the dhcp requests sent by the clients will find a working relay in r2, which will redirect them to the server s1 and, provided that ip forwarding is allowed in r1 (even if the relay in r1 is not running), the requests will reach the server s1. As a result, after the convergence time all the clients will have acquired an IP address. This can be tested in each client with the command
 
ifconfig eth1
 
Which states that for the deployed scenario, a single dhcp relay in r2 would be sufficient.
 
  
 +
<if>2</if>
  
*'''''stop server'''''
+
== Example ==
When all the clients have acquired IP, the user can test what happens if the dhcp server is stopped.
+
<pre>
vnumlparser.pl -x dhcp-server-stop@scenario_example.xml -v -u root
+
<dhcp_conf>
As mentioned before, the clients are configured with a lease time of 120 seconds, which means they have to renew the IP lease with this frecuency.
 
Right after stopping the server, and before their leases expire, the clients will keep their addresses, as can be checked in each client with
 
ifconfig eth1
 
But when the client tries to renew the lease, the request will not find any answer from the server, and the IP will be released. After a while, all the clients will have lost their IP, and the command
 
ifconfig eth1
 
will not show any "inet addr" field.
 
  
 +
  <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>
  
*'''''start server'''''
+
  <vm name="uml2" type="dhcp3">
However the requests from the clients go on, and if the user starts the server once more
+
    <client>
vnumlparser.pl -x dhcp-server-start@scenario_example.xml -v -u root
+
      <if>1</if>
The clients will eventually be provided with a new IP lease.
+
    </client>
 +
  </vm>
  
 +
  <vm name="uml3" type="dhcp3">
 +
    <relay>
 +
      <toserver>10.0.0.1</toserver>
 +
    </relay>
 +
  </vm>
  
*'''''Stopping the simulation'''''
+
  <vm name="uml4" type="dhcp3">
Stopping the dhcp scenario
+
    <client>
vnumlparser.pl -x dhcp-stop@scenario_example.xml -v -u root
+
      <if>1</if>
Stopping the simulation with flag -P
+
    </client>
vnumlparser.pl -P scenario_example.xml -v -u root
+
  </vm>
  
== Download ==
+
</dhcp_conf>
 +
</pre>

Latest revision as of 21:56, 13 May 2009

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_scenario.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_scenario.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_scenario.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_scenario.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_scenario.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_scenario.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_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
  • 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_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
  • 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_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

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.

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.

<lease_time>

Optional. Unique.

When included, it indicates 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.

<lease_time>300</lease_time>

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

<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>