Forge Home

support_packet_capture

This module makes capturing network traffic to submit to Puppet Support as part of a Puppet Support ticket easy.

7,038 downloads

6,483 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 0.2.0 (latest)
  • 0.1.1
  • 0.1.0
released Nov 11th 2017
This version is compatible with:
  • Puppet Enterprise 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >= 4.0.0 < 6.0.0
  • , , , , ,
Tasks:
  • kill_running_capture
  • run_capture
  • run_custom_capture

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'spynappels-support_packet_capture', '0.2.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add spynappels-support_packet_capture
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install spynappels-support_packet_capture --version 0.2.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

spynappels/support_packet_capture — version 0.2.0 Nov 11th 2017

support_packet_capture

Table of Contents

  1. Description
  2. Setup - The basics of getting started with support_packet_capture
  3. Usage - Configuration options and additional functionality
  4. Reference - An under-the-hood peek at what the module is doing and how
  5. Limitations - OS compatibility, etc.
  6. Development - Guide for contributing to the module

Description

This module is designed to simplify installing tcpdump and capturing network traffic on Debian and EL based Linux distros.

This module will help sysadmins to capture simple network traces as requested by Puppet Support during diagnosis of issues in Support Tickets for Puppet Enterprise. It may also be useful for anyone taking their first steps in network analysis using tcpdump and/or Wireshark.

Setup

Setup Requirements

This module has no dependencies, other than the ability to install the tcpdump utility from configured system repositories. The Tasks require Puppet Enterprise 2017.3.z or later.

Beginning with support_packet_capture

Once the module is installed, to use it simply classify any Linux node with the provided support_packet_capture class. The Tasks can be accessed in the Tasks sidebar of the PE Console.

Usage

The default instance of this module creates a Bash script (capscript.sh) in /var/tmp/ which, when run, captures 1000 packets on the primary network interface, filtered on TCP port 8140. The packets are written to a file in /var/tmp/, the name of which is defined as ${facts[hostname]}.<timestamp>.pcap. The function can be customised using the following parameters:

  • port: Providing a port value applies a capture filter on a different TCP port.
  • interface: Providing the name of an interface allows you to capture on a specific network interface.
  • packetcount: Allows you to specify the number of packets to capture before exiting.
  • savedir: Allows customisation of the directory the packet captures are saved to. The directory must exist on the target system.
  • remove: If set to true, the next Puppet run will uninstall tcpdump and remove /var/tmp/capscript.sh. Any pcap files captured using the script will NOT be removed.

This module also includes 3 Tasks:

  • A task to run the capscript.sh provided by this module.
  • A task to kill a running tcpdump.
  • A task to run a custom tcpdump, where the interface (string), number of packets (integer), the save file (string) and the capture filter (string) can all be passed in as parameters. The interface parameter is passed to the -i flag in tcpdump, and should be the interface name as found in ip link show. The number of packets is passed to the -c flag in tcpdump if it is a positive integer, and disables the default packet capture limit if it is 0. The save file is passed to tcpdump's -w flag and should be a path where any required directories exist. The capture filter should be a valid tcpdump capture filter.

The custom tcpdump capture task has a default packet limit of 50 packets, to avoid an open-ended capture filling a disk. To change the number of packets captured, simply pass the required number of packets as a parameter. Passing 0 as the packetcount parameter removes the default 50 packet limit and should be done with extreme caution.

Reference

This module provides a single class, with 2 resources which install the tcpdump package and create the Bash script which actually does the capture. It also provides the three tasks outlined above.

Limitations

This module works with all Debian or Enterprise Linux based distributions. It should be compatible with all versions of Puppet, but is designed for Puppet 4 and Puppet 5 specifically. The Tasks will only be available for PE 2017.3 and above.

Development

To contibute, please raise PRs on this module's Github page.