Commit 0ce8ee77 authored by Maciej Delmanowski's avatar Maciej Delmanowski

Merge branch 'drybjed-filter-dhcp'

parents 306acabe 2d9f6c35
Pipeline #19450920 passed with stages
in 8 minutes and 21 seconds
......@@ -38,6 +38,10 @@ Added
:ref:`debops.etckeeper`. The new role is included in the ``common.yml``
- [debops.ifupdown] The role has new tasks that manage custom hooks in other
services. First hook is :ref:`ifupdown__ref_custom_hooks_filter_dhcp_options`
which can be used to selectively apply DHCP options per network interface.
......@@ -298,6 +298,21 @@ ifupdown__dependent_interfaces: {}
ifupdown__combined_interfaces: '{{ lookup("template", "lookup/ifupdown__combined_interfaces.j2", convert_data=False) | from_yaml }}'
# ]]]
# ]]]
# Custom ifupdown hooks [[[
# -------------------------
# .. envvar:: ifupdown__custom_hooks [[[
# List of custom hooks created by the ``debops.ifupdown`` role. See
# :ref:`ifupdown__ref_custom_hooks` for more details.
- name: 'filter-dhcp-options'
hook: 'etc/dhcp/dhclient-enter-hooks.d/filter-dhcp-options'
mode: '0644'
state: 'present'
# ]]]
# ]]]
# Custom configuration files [[[
# ------------------------------
......@@ -121,6 +121,25 @@
(item.src|d() or item.content|d()) and
item.state|d('present') != 'absent')
- name: Remove custom ifupdown hooks
path: '{{ item.dest | d("/" + item.hook) }}'
state: 'absent'
- '{{ ifupdown__custom_hooks }}'
when:|d() and item.state|d('present') == 'absent'
- name: Install custom ifupdown hooks
src: '{{ item.src | d(item.hook + ".j2") }}'
dest: '{{ item.dest | d("/" + item.hook) }}'
owner: 'root'
group: 'root'
mode: '{{ item.mode | d("0755") }}'
- '{{ ifupdown__custom_hooks }}'
when:|d() and item.state|d('present') != 'absent'
- name: Install reconfiguration script if needed
src: 'script/ifupdown-reconfigure-interfaces'
# {{ ansible_managed }}
# vim:ft=sh
# Hook installed by the 'debops.ifupdown' Ansible role
# This hook is sourced directly into the dhclient-script(8) environment, be
# careful about messing around in it. Bourne shell (/bin/sh) features are used
# here.
# This hook can be used to filter incoming DHCP options per the network
# interface and ignore unwanted ones. See the dhclient-script(8) for
# information about how this script is used by 'dhclient', and dhcp-options(5)
# for information about possible DHCP options which can be ignored.
case "$reason" in
case "$interface" in
{% for interface, options in ifupdown__combined_interfaces.items() %}
{% if (options.state|d('present') != 'absent' and
options.dhcp_ignore is defined and options.dhcp_ignore) %}
{% set dhcp_ignore = ([ options.dhcp_ignore ] if (options.dhcp_ignore is string) else options.dhcp_ignore) %}
{{ interface }})
echo "Ignoring DHCP options received via '${interface}' interface: {{ dhcp_ignore | join(',') }}"
unset {{ dhcp_ignore | join(' ') }}
{% endif %}
{% endfor %}
.. _ifupdown__ref_custom_hooks:
Custom :program:`ifupdown` hooks
The ``debops.ifupdown`` Ansible role can configure custom :program:`ifupdown`
hooks in other software to configure services related to network interfaces.
The list of hooks can be found in the :envvar:`ifupdown__custom_hooks`
variable, which is a list of YAML dictionaries with specific parameters:
Required. Name of the hook, used as an identifier.
Optional. Path of a Jinja2 template included with the :ref:`debops.ifupdown`
role relative to the :file:`templates/` directory, which will be used to
generate the hook script. The hook script will be placed at the same path on
the target host.
Optional. Override the path of the Jinja2 template (the ``.j2`` extension
needs to be specified).
Optional. Override the path of the generated hook on the remote host (path
needs to start with ``/``).
Optional. Set the file mode to use, by default ``0755``.
Optional. If not specified or ``present``, the hook will be generated. If
``absent``, the hook will be removed.
.. _ifupdown__ref_custom_hooks_filter_dhcp_options:
The :program:`filter-dhcp-options` hook
This hook is a Bourne shell (:command:`/bin/sh`) script that is sourced by the
:man:`dhclient-script(8)` command executed by the :program:`dhclient` program
during interface configuration via DHCP. The hook allows to filter and ignore
recevied DHCP options per the network interface, which can be useful on systems
connected to multiple networks with each one providing DHCP services. List of
DHCP options that can be filtered can be found in the :man:`dhcp-options(5)`
manual page.
By default the hook does not filter any DHCP options. To configure it, add the
``dhcp_ignore`` parameter in the :ref:`ifupdown__ref_interfaces` interface
configuration. The parameter is a string or list of variables used by the
:program:`dhclient-script` command to represent DHCP options.
Consider configuration of a host connected to two networks, ``br0`` (internal
network) and ``br1`` (external network via a VLAN). By default the Debian
Installer sets up only the internal network connection which is used for host
configuration and management. The external connection is configured later, via
a VLAN which cannot be automatically configued by Debian Installer. Both
networks are maintained using DHCP servers, each providing a default route
through its network.
After the host is configured, you want to switch the default route from the
internal network to the external network to allow public access to the services
provided by this host. To do that, the default route from the internal DHCP
server needs to be ignored, in which case the external network will take
Additionally, the external DHCP server provides information about nameservers
that don't know about the internal network. You want to ignore the external
nameservers and use the ones provided by the internal network to resolve
queries, which lets you access other internal hosts via their hostnames.
.. code-block:: yaml
- iface: 'br0'
comment: 'Internal network'
type: 'bridge'
inet: 'dhcp'
inet6: 'auto'
bridge_ports: 'eth0'
dhcp_ignore: 'new_routers'
- iface: 'br1'
comment: 'External network'
type: 'bridge'
inet: 'dhcp'
inet6: 'auto'
bridge_ports: 'eth1'
dhcp_ignore: 'new_domain_name_servers'
Just after installation the host will have only the internal network connection
set up, used for configuration. When Ansible applies the :ref:`debops.ifupdown`
configuration on the host, the default route to the external network will
replace the default route to to the internal network, however existing internal
connections will work as usual. Any existing connections to the external
network via internal router might be interrupted before the new route takes
The network configuration should be preserved across reboots - even though both
of the DHCP servers send relevant configuration for default routes and
nameservers, the DHCP options are filtered on the client side.
......@@ -295,6 +295,19 @@ Mapping parameters
configuration for a mapping dynamically. See :man:`interfaces(5)` manual for
more details.
DHCP parameters
Optional. String or list of variable names used by the
:man:`dhclient-script(8)` script to configure the interface. The specified
variables representing DHCP options will be unset by the configuration
script; this can be used to selectively ignore DHCP options on a given
network interface.
See :ref:`ifupdown__ref_custom_hooks_filter_dhcp_options` documentation for
more details.
Custom interface options
......@@ -11,6 +11,7 @@ debops.ifupdown
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment