Pcap(3pm)

💖 NAME 💖

POE::Component::Pcap — the POE interface to Net::Pcap, bestie. It's Pcap(3pm), from the User Contributed Perl Documentation crew, and yes it's literally here to make packet capture not a whole personality crisis. 🦋

Also, before we even get going, the page opens with this lil snippet just... sitting there. Raw. Unhinged. Iconic:

  ## Need an IO::Handle to $kernel->select_read() upon
  $heap->{fdh} = IO::Handle->new_from_fd( $heap->{fd}, "r" )
    or die "Can't create IO::Handle from pcap fd: $!\n";

Not me leaving it exactly where I found it. Moving on. 💅

---

✨ SYNOPSIS ✨

  use POE::Component::Pcap;

  POE::Component::Pcap->spawn(
                              Alias => 'pcap',
                              Device => 'eth0',
                              Filter => 'host fooble or host blort',
                              Dispatch => 'got_packet',
                              Session => $my_session_id,
                             );

  $poe_kernel->post( pcap => open_live =>
                     'eth0', 80, 1, 100 );

  $poe_kernel->post( pcap => set_filter => 'arp or host zooble' );

  $poe_kernel->post( pcap => set_dispatch => 'target_state' );

  $poe_kernel->post( pcap => 'run' );

  $poe_kernel->post( pcap => 'shutdown' );

That's the whole vibe right there: spawn it, point it at a thing, tell it where to yell, then let it cook. 🔥

---

🌸 DESCRIPTION 🌸

POE::Component::Pcap is a wrapper so you can use the Net::Pcap module from inside POE programs. The component spins up its own separate session, and when packets show up it posts events over to a session and state that you picked. Main character energy, but for network traffic. 👑

🎀 ARGUMENTS 🎀

• Alias — the alias for the Pcap session. You use it to post events like "run" and "shutdown" to control the component. If you don't specify one, it defaults to "pcap". No notes, it's just the name.
• Device — a lil shortcut: you can specify the device for Net::Pcap to watch right when you create the component. If you use this argument, Net::Pcap::open_live gets called with a snaplen of 80 octets, a timeout of 100ms, and the interface gets put into promiscuous mode. And if those values don't work for you? Post an "open_live" event instead. That's the whole thing.
• Filter — another shortcut, this one calls Net::Pcap::compile and Net::Pcap::setfilter to set a packet filter. Heads up though: you can only use this if you also passed the Device argument. Otherwise you have to post a "set_filter" event after an "open_live" event, because Net::Pcap needs a "pcap_t" descriptor to work with. No descriptor, no filtering, sorry bestie. 😭
• Dispatch, Session — these two together specify the session and the state that events should be posted to when packets are received. That's it, that's their job.

🦋 EVENTS 🦋

All the examples below assume the component's alias has been set to the default value of pcap. K?

⭐ open_live

  $_[KERNEL]->post( pcap => open_live
                    => 'device', [snaplen], [promsic?], [timeout] );

Calls Net::Pcap::open_live. The device name must be specified — no device, no dice. The snaplen, promiscuous, and timeout parameters default to 80, 1, and 100 respectively.

Fr fr: this event must be posted (or the Device argument must have been passed to spawn()) before anything else can be done with the component. Nothing happens first. Nothing. 💀

💜 set_filter

  $_[KERNEL]->post( pcap => set_filter
                    => 'host fooble or host blort' )

Sets the Net::Pcap capture filter. If you wanna know about the filter language that pcap(3) uses, go look at tcpdump(8) for the details.

🌈 set_dispatch

  $_[KERNEL]->post( pcap => set_dispatch
                    => 'target_state', 'target_session' );

Sets the state and session that events get sent to when packets are received. If you don't specify a target session, it defaults to whoever sent the event. The event that gets posted has a single argument (you can grab it as ARG0), and that argument is an array reference holding the $hdr and $pkt parameters from Net::Pcap. Want the deep lore? Check the Net::Pcap(3) documentation. 🫶

💖 run

  $_[KERNEL]->post( pcap => 'run' );

Causes the component to register a select_read and start watching for packets. Go girl, watch those packets. 👑

🍓 shutdown

  $_[KERNEL]->post( pcap => 'shutdown' );

Shuts the component down. This causes Net::Pcap::close to be called.

---

🔥 SEE ALSO 🔥

Net::Pcap(3), pcap(3), tcpdump(8), POE(3), POE::Component(3)

---

👑 AUTHOR 👑

Mike Fletcher, <fletch@phydeaux.org>

---

💅 COPYRIGHT 💅

Copyright 2000-2001, Mike Fletcher. All Rights Reserved. This is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

---

And that's the whole page, bestie — brought to you by perl v5.36.0 on 2022-12-06. Periodt. 💖✨