Merge branch 'drybjed-filter-dhcp'

CHANGELOG.rst

@@ -38,6 +38,10 @@ Added
     :ref:`debops.etckeeper`. The new role is included in the ``common.yml``
     playbook.
 
+- [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.
+
 Changed
 ~~~~~~~
 

ansible/roles/debops.ifupdown/defaults/main.yml

@@ -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.
+ifupdown__custom_hooks:
+
+  - name: 'filter-dhcp-options'
+    hook: 'etc/dhcp/dhclient-enter-hooks.d/filter-dhcp-options'
+    mode: '0644'
+    state: 'present'
+                                                                   # ]]]
+                                                                   # ]]]
 # Custom configuration files [[[
 # ------------------------------
 

ansible/roles/debops.ifupdown/tasks/main.yml

@@ -121,6 +121,25 @@
          (item.src|d() or item.content|d()) and
          item.state|d('present') != 'absent')
 
+- name: Remove custom ifupdown hooks
+  file:
+    path: '{{ item.dest | d("/" + item.hook) }}'
+    state: 'absent'
+  with_flattened:
+    - '{{ ifupdown__custom_hooks }}'
+  when: item.name|d() and item.state|d('present') == 'absent'
+
+- name: Install custom ifupdown hooks
+  template:
+    src:  '{{ item.src  | d(item.hook + ".j2") }}'
+    dest: '{{ item.dest | d("/" + item.hook) }}'
+    owner: 'root'
+    group: 'root'
+    mode: '{{ item.mode | d("0755") }}'
+  with_flattened:
+    - '{{ ifupdown__custom_hooks }}'
+  when: item.name|d() and item.state|d('present') != 'absent'
+
 - name: Install reconfiguration script if needed
   copy:
     src: 'script/ifupdown-reconfigure-interfaces'

ansible/roles/debops.ifupdown/templates/etc/dhcp/dhclient-enter-hooks.d/filter-dhcp-options.j2

+# {{ 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
+    BOUND|RENEW|REBIND|REBOOT|TIMEOUT)
+
+        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 %}
+
+            *)
+                ;;
+
+        esac
+
+        ;;
+
+esac

docs/ansible/roles/debops.ifupdown/custom-hooks.rst

+.. _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:
+
+``name``
+  Required. Name of the hook, used as an identifier.
+
+``hook``
+  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.
+
+``src``
+  Optional. Override the path of the Jinja2 template (the ``.j2`` extension
+  needs to be specified).
+
+``dest``
+  Optional. Override the path of the generated hook on the remote host (path
+  needs to start with ``/``).
+
+``mode``
+  Optional. Set the file mode to use, by default ``0755``.
+
+``state``
+  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.
+
+Examples
+~~~~~~~~
+
+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
+precedence.
+
+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
+
+   ifupdown__host_interfaces:
+
+     - 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
+over.
+
+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.

docs/ansible/roles/debops.ifupdown/defaults-detailed.rst

@@ -295,6 +295,19 @@ Mapping parameters
   configuration for a mapping dynamically. See :man:`interfaces(5)` manual for
   more details.
 
+DHCP parameters
+~~~~~~~~~~~~~~~
+
+``dhcp_ignore``
+  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
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/ansible/roles/debops.ifupdown/index.rst

@@ -11,6 +11,7 @@ debops.ifupdown
    defaults
    defaults-detailed
    ifupdown-systemd
+   custom-hooks
    copyright
    upgrade