dhcp.rst 7.27 KB
Newer Older
eallovon's avatar
eallovon committed
1 2
.. _dhcp_configuration:

Xav Encall's avatar
Xav Encall committed
3 4 5 6
*******************
DHCP Server
*******************

7 8 9 10
XiVO includes a DHCP server used for assisting in the provisioning of phones and other devices. (See
:ref:`Basic Configuration <dhcpd-config>` for the basic setup). This section contains additional
notes on how to configure more advanced options that may be helpful when integrating the server with
different VOIP subnets.
Xav Encall's avatar
Xav Encall committed
11 12


13 14
Activating DHCP on another interface
====================================
Xav Encall's avatar
Xav Encall committed
15

Sebastien Duthil's avatar
Sebastien Duthil committed
16 17
DHCP Server can be activated through the XiVO Web Interface :menuselection:`Configuration -->
Network --> DHCP` :
Xav Encall's avatar
Xav Encall committed
18 19 20 21 22 23

.. figure:: img/dhcp.png
   :scale: 85%

   :menuselection:`Configuration --> Network --> DHCP`

Sebastien Duthil's avatar
Sebastien Duthil committed
24
By default, it will only answer to DHCP requests coming from the VoIP subnet (defined in the
25 26 27
:menuselection:`Configuration --> Network --> Interfaces` section). If you need to activate DHCP on
an other interface, you have to fill in the *Extra network interfaces* field with the interface name
, for example : ``eth0``
Xav Encall's avatar
Xav Encall committed
28

29 30
After saving your modifications, click on *Apply system configuration* so that the new settings can
take effect.
Xav Encall's avatar
Xav Encall committed
31

32

33 34
Changing default DHCP gateway 
=============================
35

36 37
By default, the XiVO DHCP server uses the XiVO's IP address as the routing address.  To change this
you must create a custom-template:
38 39 40

#. Create a custom template for the :file:`dhcpd_subnet.conf.head` file::

41 42 43
    mkdir -p /etc/xivo/custom-templates/dhcp/etc/dhcp/
    cd /etc/xivo/custom-templates/dhcp/etc/dhcp/
    cp /usr/share/xivo-config/templates/dhcp/etc/dhcp/dhcpd_subnet.conf.head .
44 45 46

#. Edit the custom template::

47
    vim dhcpd_subnet.conf.head
48

49 50
#. In the file, replace the string ``#XIVO_NET4_IP#`` by the routing address of your VoIP network,
   for example::
51

52
    option routers 192.168.2.254;
53 54 55

#. Re-generate the dhcp configuration::

56
    xivo-update-config
57

58
DHCP server should have been restarted and should now use the new routing address.
59 60


61 62
Configuring DHCP server to serve unknown hosts
==============================================
63 64 65

By default, the XiVO DHCP server serves only known hosts. That is:

Sebastien Duthil's avatar
Sebastien Duthil committed
66 67
* either hosts which MAC address prefix (the `OUI
  <http://en.wikipedia.org/wiki/Organizationally_unique_identifier>`_) is known
68 69
* or hosts which Vendor Identifier is known

Etienne Allovon's avatar
Etienne Allovon committed
70
Known OUIs and Vendor Class Identifiers are declared in :file:`/etc/dhcp/dhcpd_update/*` files.
71 72 73

If you want your XiVO DHCP server to serve also unknown hosts (like PCs) follow these instructions:

74
#. Create a custom template for the :file:`dhcpd_subnet.conf.tail` file::
Sebastien Duthil's avatar
Sebastien Duthil committed
75

76 77 78
    mkdir -p /etc/xivo/custom-templates/dhcp/etc/dhcp/
    cd /etc/xivo/custom-templates/dhcp/etc/dhcp/
    cp /usr/share/xivo-config/templates/dhcp/etc/dhcp/dhcpd_subnet.conf.tail .
79

80
#. Edit the custom template::
81

82
    vim dhcpd_subnet.conf.tail
83

84
#. And add the following line at the head of the file::
Sebastien Duthil's avatar
Sebastien Duthil committed
85

86
    allow unknown-clients;
87 88 89

#. Re-generate the dhcp configuration::

90
    xivo-update-config
91 92 93 94

DHCP server should have been restarted and should now serve all network equipments.


Sebastien Duthil's avatar
Sebastien Duthil committed
95
DHCP-Relay
Xav Encall's avatar
Xav Encall committed
96 97
==========

Sebastien Duthil's avatar
Sebastien Duthil committed
98 99
If your telephony devices aren't located on the same site and the same broadcast domain as the XiVO
DHCP server, you will have to add the option *DHCP Relay* to the site's router.  This parameter will
100 101
allow the DHCP requests from distant devices to be transmitted to the IP address you specify as DHCP
Relay.
Xav Encall's avatar
Xav Encall committed
102

103
.. warning:: Please make sure that the IP address used as DHCP Relay is the same as one of XiVO's
104 105 106
   interfaces, and that this interface is configured to listen to DHCP requests (as decribed in
   previous part). Also verify that routing is configured between the distant router and the choosen
   interface, otherwise DHCP requests will never reach the XiVO server.
Xav Encall's avatar
Xav Encall committed
107 108 109 110 111


Configuring DHCP server for other subnets
=========================================

Sebastien Duthil's avatar
Sebastien Duthil committed
112 113 114
This section describes how to configure XiVO to serve other subnets that the VOIP subnet. As you
can't use the Web Interface to declare other subnets (for example to address DATA subnet, or a VOIP
subnet that isn't on the same site that XiVO server), you'll have to do the following configuration
115
on the Command Line Interface.
116

Xav Encall's avatar
Xav Encall committed
117 118 119 120

Creating "extra subnet" configuration files
-------------------------------------------

121
First thing to do is to create a directory and to copy into it the configuration files::
Xav Encall's avatar
Xav Encall committed
122

123 124 125
    mkdir /etc/dhcp/dhcpd_sites/
    cp /etc/dhcp/dhcpd_subnet.conf /etc/dhcp/dhcpd_sites/dhcpd_siteXXX.conf
    cp /etc/dhcp/dhcpd_subnet.conf /etc/dhcp/dhcpd_sites/dhcpd_lanDATA.conf
Xav Encall's avatar
Xav Encall committed
126 127

.. note::
128 129 130
   In this case we'll create 2 files for 2 differents subnets. You can change the name of the files,
   and create as many files as you want in the folder :file:`/etc/dhcp/dhcpd_sites/`. Just adapt
   this procedure by changing the name of the file in the different links.
Xav Encall's avatar
Xav Encall committed
131

Sebastien Duthil's avatar
Sebastien Duthil committed
132
After creating one or several files in :file:`/etc/dhcp/dhcpd_sites/`, you have to edit the file
133
:file:`/etc/dhcp/dhcpd_extra.conf` and add the according include statement like::
Xav Encall's avatar
Xav Encall committed
134

135 136
    include "/etc/dhcp/dhcpd_sites/dhcpd_siteXXX.conf";
    include "/etc/dhcp/dhcpd_sites/dhcpd_lanDATA.conf";
137

Xav Encall's avatar
Xav Encall committed
138 139 140 141

Adjusting Options of the DHCP server
------------------------------------

Sebastien Duthil's avatar
Sebastien Duthil committed
142 143 144 145
Once you have created the subnet in the DHCP server, you must edit each configuration file (the
files in :file:`/etc/dhcp/dhcpd_sites/`) and modify the different parameters.  In section
**subnet**, write the IP subnet and change the following options (underlined fields in the
example)::
Xav Encall's avatar
Xav Encall committed
146

147
    subnet 172.30.8.0 netmask 255.255.255.0 {
Xav Encall's avatar
Xav Encall committed
148

149
* subnet-mask::
Sebastien Duthil's avatar
Sebastien Duthil committed
150

151
    option subnet-mask 255.255.255.0;
Xav Encall's avatar
Xav Encall committed
152

153
* broadcast-address::
Sebastien Duthil's avatar
Sebastien Duthil committed
154

155
    option broadcast-address 172.30.8.255;
Xav Encall's avatar
Xav Encall committed
156

157
* routers (specify the IP address of the router that will be the default gateway of the site)::
Sebastien Duthil's avatar
Sebastien Duthil committed
158

159
    option routers 172.30.8.1;
Xav Encall's avatar
Xav Encall committed
160

161
In section **pool**, modify the options::
Xav Encall's avatar
Xav Encall committed
162

163
    pool {
Xav Encall's avatar
Xav Encall committed
164

165
* log (add the name of the site or of the subnet)::
Sebastien Duthil's avatar
Sebastien Duthil committed
166

167
    log(concat("[", binary-to-ascii(16, 8, ":", hardware), "] POOL VoIP Site XXX"));
Xav Encall's avatar
Xav Encall committed
168

Sebastien Duthil's avatar
Sebastien Duthil committed
169 170 171
* range (it will define the range of IP address the DHCP server can use to address the devices of
  that subnet)::

172
    range 172.30.8.10 172.30.8.200;
Xav Encall's avatar
Xav Encall committed
173

174
.. warning:: XiVO only answers to DHCP requests from `supported devices <https://documentation.xivo.solutions/projects/devices/en/latest/>`_. In case of
175 176
   you need to address other equipment, use the option *allow unknown-clients;* in the
   :file:`/etc/dhcp/dhcpd_sites/` files
177

178 179
* If you have checked the "DHCP integration" (See :ref:`Advanced Configuration <dhcp-integration>` for the basic setup) in provisionning configuration, you will also **MUST** add the parameter below: (**Otherwise provd won't be able to route the devices to the correct plugins**)

XivoBuilder's avatar
XivoBuilder committed
180 181 182
.. code-block:: none 

   on commit {
183 184 185 186 187 188 189
                execute("dxtorc",
                        "commit",
                        binary-to-ascii(10, 8, ".", leased-address),
                        binary-to-ascii(16, 8, ":", suffix(hardware, 6)),
                        pick-first-value(concat("060", binary-to-ascii(16, 8, ".", option vendor-class-identifier)), "")
                    );
            }
XivoBuilder's avatar
XivoBuilder committed
190

Xav Encall's avatar
Xav Encall committed
191

192
At this point, you can apply the changes of the DHCP server with the command::
Xav Encall's avatar
Xav Encall committed
193

194
    service isc-dhcp-server restart
Xav Encall's avatar
Xav Encall committed
195

196 197 198
After that, XiVO will start to serve the DHCP requests of the devices located on other sites or
other subnets than the VOIP subnet. You will see in :file:`/var/log/daemon.log` all the DHCP
requests received and how they are handled by XiVO.