Mastering tcpdump and dig: Real-World Examples for Beginners

Improving official documentation can make complex tools like tcpdump and dig accessible even for infrequent users. This guide explains why new examples were added to their man pages, how the process worked, and what beginners can learn from them. Each question below dives into a key aspect of this documentation effort, offering practical insights for anyone wanting to use these powerful network utilities with confidence.

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

Man pages are often the most accurate source of information for command-line tools, but they can be dense and hard to follow. Many users, especially beginners or those who only use a tool occasionally, find themselves skipping the official docs and turning to blog posts or Stack Overflow instead. The goal was to bridge that gap by providing real, practical examples that answer common questions like “What are the most used tcpdump flags?” or “How do I query a specific DNS record with dig?”. By including clear, minimal examples, the man pages become more approachable and useful without sacrificing accuracy. Maintainers of both tools embraced this idea because it directly addresses user pain points and makes the documentation more effective for a wider audience.

What was the main goal of the new examples?

The objective was straightforward: provide the absolute most basic examples for people who use tcpdump or dig infrequently — or have never used them before. Often, beginners just need a few lines of correct syntax to get started. For dig, that might be dig example.com or dig -x 8.8.8.8; for tcpdump, a simple packet capture like tcpdump -i eth0 or tcpdump host 192.168.1.1. Keeping examples minimal and focused on everyday tasks helps users quickly achieve their objectives without getting lost in advanced options. The feedback from maintainers and users confirmed that this approach works well: it’s easy to explain, makes sense from a user’s perspective, and provides immediate value.

Why focus on improving man pages instead of other documentation?

Man pages have a unique advantage: they live with the tool itself and can be updated as the software changes. Unlike a third-party blog post, the information in a man page is kept current by maintainers. Moreover, the review process ensures that every flag, behavior, and example is checked for correctness. This is especially valuable for tools like tcpdump, where incorrect flag usage can lead to missed packets or system errors. By investing effort in man pages, we make the official documentation as readable and useful as a high-quality blog post, but with the added benefit of being precisely accurate. The experience of contributing also revealed hidden features — for instance, the tcpdump maintainers pointed out the -v flag combined with -w provides a live capture count, a tip many users would miss otherwise.

What did you learn while writing the examples?

Working on the examples taught me that even basic questions like “What are the most common tcpdump flags?” can uncover surprising best practices. For example, when saving packets to a file with tcpdump -w out.pcap, adding -v prints a live summary of how many packets have been captured so far. This is extremely useful for long captures, and I never would have discovered it on my own. Similarly, for dig, the maintainers helped craft queries that handle various DNS record types efficiently. The collaboration with experienced developers (Denis Ovsienko, Guy Harris, Ondřej Surý, and others) was a positive experience and left me motivated to continue refining man pages. It also reinforced that official documentation doesn’t have to be dry; with the right examples, it can be as engaging as a tutorial.

How did you handle the roff language used in tcpdump’s man page?

The tcpdump project uses the roff language, which has a steep learning curve. Instead of writing roff directly, I created a simple Markdown-to-roff script that converted Markdown into the required formatting, following the conventions already present in the man page. This allowed me to focus on content without wrestling with arcane syntax. While tools like pandoc exist, its output differed significantly from the man page’s style, so a custom script seemed more reliable. The result was a smooth workflow: write examples in Markdown, convert to roff, and submit for review. This approach made the documentation process approachable and could be reused for other man pages in the future.

What feedback did you receive from maintainers?

The maintainers of both tcpdump and dig were supportive and collaborative. They reviewed every change carefully, ensuring technical accuracy and adherence to the project’s style. Their experience brought invaluable insights; for example, they suggested edge cases or alternative flag combinations that make the examples more robust. The review process was thorough but constructive, leaving me feeling that the final examples truly reflect best practices from real-world use. Hearing from users who later found the examples helpful was also rewarding — it confirmed that this kind of documentation effort fills a real need. Overall, the positive reception encouraged me to continue investing in man page improvements.

How can beginners benefit from these new examples?

Beginners can get started immediately without wading through lengthy theory. For dig, the examples show how to perform a basic DNS lookup, reverse lookup, and query specific record types (A, AAAA, MX). For tcpdump, common scenarios are covered: capturing packets on an interface, filtering by host or port, saving to a file, and printing packet summaries with -v. Each example includes the full command and a brief explanation of what it does. This reduces the time spent reading documentation and increases hands-on learning. Additionally, by seeing the simplest cases first, beginners build confidence and are more likely to explore advanced options later. The examples serve as a quick reference for everyday tasks, making both tools much more accessible.