DEBOPS.DHCP_PROBE(5)

NAME
debops.dhcp_probe - Configure DHCP Probe using Ansible

SYNOPSIS

debops service/dhcp_probe [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The dhcp_probe <https://www.net.princeton.edu/software/dhcp_probe/> tool can be used to passively detect rogue DHCP servers on IPv4 networks. Upon detection, the service can execute custom commands to, for example, block the culprit via RADIUS or notify the system administrator.

The debops.dhcp_probe role can be used to install and configure dhcp_probe on a Debian/Ubuntu host. It will utilize systemd instance templates to run DHCP Probe instances on multiple network interfaces at once. By default, an e-mail message will be sent to the system administrator with notification on newly detected rogue DHCP servers.

GETTING STARTED

  Example inventory

To install and manage DHCP Probe on a host, it needs to be included in the [debops_service_dhcp_probe] Ansible inventory group:

[debops_service_dhcp_probe]
hostname

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.dhcp_probe role:

---
- name: Manage dhcp_probe service
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_dhcp_probe' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: dhcp_probe
      tags: [ 'role::dhcp_probe', 'skip::dhcp_probe' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after host is first configured to speed up playbook execution, when you are sure that most of the configuration has not been changed.

Available role tags:

role::dhcp_probe
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

  Other resources

List of other useful resources related to the debops.dhcp_probe Ansible role:

•   Manual pages: dhcp_probe(8) <https://manpages.debian.org/dhcp_probe(8)>, dhcp_probe.cf(5) <https://manpages.debian.org/dhcp_probe.cf(5)>

DEFAULT VARIABLE DETAILS

Some of debops.dhcp_probe default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  dhcp_probe__interfaces

The dhcp_probe__*_interfaces variables contain a list of network interfaces on which instances of dhcp_probe will be listening for rogue DHCP servers. The lists are merged together, users can modify contents of the dhcp_probe__default_interfaces by the entries in the dhcp_probe__interfaces variable.

  Examples

Enable DHCP Probe on custom interfaces:

dhcp_probe__interfaces:
  - name: 'br0'
  - name: 'br1'
    state: 'present'

  Syntax

Each list contains YAML dictionaries with specific parameters:

name
    Required. Name of the network interface (actually a systemd instance) on which dhcp_probe will be listening for rogue DHCP servers. This parameter is used as an anchor to merge multiple lists of interfaces together.

state
    Optional. If not specified or present the systemd instance will be enabled. if absent, the systemd instance will be disabled.

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2022, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others