DEBOPS.LLDPD(5)

NAME
debops.lldpd - Install and configure LLDP service using Ansible

SYNOPSIS

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

DESCRIPTION

Link-Layer Discovery Protocol is an industry standard protocol which enables network devices to exchange information about themselves with their neighbors connected over network links. This in turn can be used to locate other devices connected to a particular device and port.

The lldpd <https://packages.debian.org/stable/lldpd> Debian package provides a lightweight lldpd daemon which implements this protocol and can be installed on Debian/Ubuntu based hosts to advertise the LLDP notifications to other devices. This might be useful in more complex environments with multiple layers of infrastructure comprised of physical hosts, virtual machines and containers.

The debops.lldpd role can be used to install and manage the lldpd service and by default will try to distinguish virtualized hosts (VMs, containers) from physical ones to make their management easier by changing their "ChassisID" attribute to reflect their virtualized status.

GETTING STARTED

  Example inventory

The debops.lldpd role is included by default in the common.yml DebOps playbook; you don't need to do anything to have it executed.

If you don’t want to let debops.lldpd role install and configure the service, you can disable it with the following setting in your inventory:

lldpd__enabled: False

  Example playbook

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

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

  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 a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::lldpd
    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.lldpd Ansible role:

•   Manual pages: lldpd(8) <https://manpages.debian.org/lldpd(8)>, lldpcli(8) <https://manpages.debian.org/lldpcli(8)>

•   The lldpd homepage <https://lldpd.github.io/>

•   Link-Layer Discovery Protocol <https://en.wikipedia.org/wiki/Link_Layer_Discovery_Protocol> page on Wikipedia

•   The community.general.lldp <https://docs.ansible.com/ansible/latest/collections/community/general/lldp_module.html> Ansible module which can gather LLDP information from hosts.

DEFAULT VARIABLE DETAILS

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

  lldpd__configuration

These variables define the contents of the /etc/lldpd.d/ configuration directory. Each configuration entry is a file with contents defined either directly, or via the options parameter. You can read the lldpcli(8) <https://manpages.debian.org/lldpcli(8)> manual page to see the available commands.

  Examples

The default role configuration includes creation of the ChassisID attribute override for virtual machines and containers. To disable this functionality within the lldpd daemon itself, you can add an "unconfigure" command:

lldpd__configuration:
  - name: 'unchassis'
    options:
      - 'unconfigure system chassisid'

Alternatively, using the raw version:

lldpd__configuration:
  - name: 'unchassis'
    raw: |
      unconfigure system chassisid

Specify the device description attribute:

lldpd__configuration:
  - name: 'description'
    options:
      - 'configure system description': 'Custom device located in rack a1'

  Syntax

The variables are defined as lists of YAML dictionaries. Each dictionary defines a separate configuration file in the /etc/lldpd.d/ directory. Each configuration entry is defined using specific parameters:

name
    Required. Name of the generated configuration file, the role will include the .conf suffix automatically. Configuration files are read by the daemon in alphabetical order so naming is important. Entries with the same name parameter can be overridden by subsequent entries.

comment
    Optional. String or YAML text block with additional comments included in a given configuration file.

state
    Optional. If not specified or present, a given configuration file will be generated. If absent, the configuration file will be removed from the host. If comment, the configuration file will be generated but commands inside will be commented out. If ignore, a given configuration entry will not be considered during template generation. This can be used to conditionally enable or disable configuration options.

raw String or YAML text block with lldpcli(8) <https://manpages.debian.org/lldpcli(8)> commands which will be included in the generated configuration file "as is".

options
    List of lldpcli(8) <https://manpages.debian.org/lldpcli(8)> commands which will be included in the generated configuration file. The options lists from multiple entries with the same name parameter are merged together. You can specify them either as a string which denotes the whole command, or as a YAML dictionary with key and value being the command and its argument quoted in double-quotes (""). Alternatively, you can define each command using a YAML dictionary with specific parameters:

name
    The lldpcli(8) <https://manpages.debian.org/lldpcli(8)> command. Multiple entris with the same name parameter are merged together in order of appearance and can override each other.

option
    If a given command needs to be specified multiple times with different values, you can use the option parameter to specify the actual lldpcli(8) <https://manpages.debian.org/lldpcli(8)> command to be included in the generated configuration file.

value
    The value of a given lldpcli(8) <https://manpages.debian.org/lldpcli(8)> command, surrounded by double quotes.

state
    If not defined or present, a given command will be included in the generated configuration file. If absent, a given command will not be included in the generated configuration file.

AUTHOR
Maciej Delmanowski

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