Mastering tcpdump and dig: Practical Examples for Beginners

In this article, we explore the recent improvements to the man pages for two powerful network troubleshooting tools: tcpdump and dig. The focus was on adding clear, practical examples for users who don't use these tools every day. Below are common questions about these updates, the motivation behind them, and what the author learned along the way.

Why were examples added to the man pages of tcpdump and dig?

The original man pages for tcpdump and dig lacked practical examples, making them less accessible to occasional users. The author noticed that examples in man pages can greatly improve usability, especially for those who need to quickly recall how to use a tool without reading through complex documentation. By adding (or improving) examples, the man pages now serve as a quick reference for beginners and infrequent users. This effort was driven by feedback from the community and a desire to make official documentation as helpful as a well-written blog post—but with the added benefit of being factually accurate.

Mastering tcpdump and dig: Practical Examples for Beginners

What was the goal of adding these examples?

The primary goal was to provide the absolute most basic examples of how to use tcpdump and dig. These examples target users who may have used the tools only a few times or never at all. The aim was to reduce the learning curve and make the man pages a friendly starting point. The author found that focusing on beginners and infrequent users resonated well with maintainers and reviewers, as it clearly addressed a common pain point. The section covers essential commands and flags, such as capturing packets with tcpdump -i eth0 or querying DNS with dig example.com.

Who contributed to the improvements and what was the experience like?

The documentation updates were reviewed by several key contributors: Denis Ovsienko, Guy Harris, Ondřej Surý, and others. Their feedback helped ensure the examples were accurate and useful. The author described the review process as a positive experience that left them motivated to continue improving man pages. Collaboration with experienced maintainers also uncovered hidden features, such as the usefulness of the -v flag with tcpdump -w—a detail the author would not have discovered alone. The process demonstrated how community review can enhance even simple documentation.

Why is improving man pages valuable?

Man pages can achieve nearly 100% accuracy when properly maintained, far surpassing many online tutorials or forum posts. The rigorous review process ensures that every command, flag, and description is correct. This is especially important for tools like tcpdump and dig, where incorrect usage can lead to missed data or security issues. Additionally, maintainers often know about lesser-used features that can greatly improve workflow. For example, the author learned that combining -v with -w prints a live packet count—a simple but powerful trick. Improving man pages makes them a reliable, go-to resource for both new and experienced users.

What hidden feature did the author discover while working on tcpdump examples?

While updating the tcpdump examples, the author discovered that when saving packets to a file with tcpdump -w out.pcap, adding the -v flag provides a live summary of the number of packets captured so far. This was a valuable insight because it gives real-time feedback during a capture, which is especially useful for long-running captures or when monitoring network traffic. The author noted that they never would have noticed this on their own, highlighting the benefit of collaborating with experienced maintainers during the documentation process.

How did the author handle the challenge of writing in the roff language?

The tcpdump man page is written in the roff language, which the author found difficult and did not want to learn. Instead, they created a simple Markdown-to-roff script that converted Markdown into the required roff format, using conventions already present in the existing man page. While alternatives like Pandoc existed, the author felt that Pandoc’s output differed too much from the current style. Writing a custom script allowed for greater control and consistency. This approach made the documentation process more efficient and less error-prone, proving that you don’t always need to master a complex markup language to contribute.

Tags: