TCPSLICE(8)

tcpslice(8) — System Manager's Manual 💅

okay so bestie, welcome to the System Manager's Manual page for tcpslice(8) — she's a classic, she's iconic, and she's about to make so much sense to you. no cap.

---

✨ NAME ✨

tcpslice — pull pieces out of pcap files and/or merge a bunch of them together 🎀

---

🦋 SYNOPSIS 🦋

tcpslice [ -DdlhRrtv ] [ -w output-file ]
         [ -s types [ -e seconds ] [ -f format ] ]
         [ start-time [ end-time ] ] file ...

---

💖 DESCRIPTION 💖

so tcpslice is that girl for extracting portions of .pcap files — and ngl, it's giving .pcap only, not .pcapng, okay? those .pcap files come from tcpdump(1)'s -w flag, or honestly from tons of other programs too. she can also merge several of those files together, and we'll get into that below 🫶

her basic whole thing? copy to stdout every packet from her input file(s) whose timestamps land inside a given range. the starting and ending times of that range can be handed to her right on the command line. and listen — all ranges are inclusive, periodt.

the starting time defaults to the earliest time of the first packet in any of the input files — we call that the first time. the ending time defaults to ten years after the starting time. so literally:

tcpslice trace-file

just copies trace-file to stdout 😌 (as long as that file doesn't hold more than ten years' worth of data, which, bestie, it won't).

---

⏰ TIME FORMATS ⏰

there are a few ways to tell her what time you mean. let's go 🌸

option one: raw Unix timestamps in the form sssssssss.uuuuuu — that's the format tcpdump's -tt flag spits out. for example, 654321098.7654 means 38 seconds and 765,400 microseconds after 8:51PM PDT, Sept. 25, 1990 💫

every example in this manual is written in PDT times, but when she's displaying times and interpreting times symbolically (more on that in a sec), tcpslice uses the local timezone — no matter what timezone the pcap file was generated in. and the daylight-savings setting she uses is the one that's appropriate for the local timezone at the date in question. so, for example, times in summer months will usually include daylight-savings effects, and winter months won't. seasonal queen 👑

option two: relative times. you can spec a time relative to either the first time (when you're giving a starting time) or the starting time (when you're giving an ending time) by putting a + in front of a numeric value in seconds. for example, a starting time of +200 means 200 seconds after the first time, and the two args +200 +300 mean from 200 seconds after the first time through 500 seconds after the first time. math but make it cute ✨

option three: the ymdhmsu format. you can say times in terms of years (y), months (m), days (d), hours (h), minutes (m), seconds (s), and microseconds (u). for example, that Unix timestamp 654321098.7654 from earlier could also be written as 1990y9m25d20h51m38s765400u. and you can use 2 or 4 digit years — 2 digits can specify years from 1970 to 2069 👑

now here's the important bit about omitted fields, so pay attention bestie:

• if the omitted field is a unit greater than that of the first specified field, its value defaults to the corresponding value taken from either the first time (if you're specifying the starting time) or the starting time (if you're specifying the ending time).
• if the omitted field is a unit less than that of the first specified field, it defaults to zero (and 1 for days).

for example, say the input file has a first time of that Unix timestamp above — i.e. 38 seconds and 765,400 microseconds after 8:51PM PDT, Sept. 25, 1990. to specify 9:36PM PDT (exactly) on the same date we could use 21h36m. and to specify a range from 9:36PM PDT through 1:54AM PDT the next day we could use:

21h36m 26d1h54m

relative times work with the ymdhmsu format too 💫 and here the defaults flip around: omitted fields default to 0 if the unit of the field is greater than that of the first specified field, and to the corresponding value taken from either the first time or the starting time if the omitted field's unit is less than that of the first specified field.

so given a first time of that same Unix timestamp, 22h +1h10m specifies a range from 10:00PM PDT on that date through 11:10PM PDT. and +1h +1h10m specifies a range from 38.7654 seconds after 9:51PM PDT through 38.7654 seconds after 11:01PM PDT. you could grab the first hour of the file with:

+0 +1h

⚠️ heads up: with the ymdhmsu format there's an ambiguity between using m for month and m for minute. it gets resolved like this — if an m field is followed by a d field, it's interpreted as months; otherwise it specifies minutes. iykyk 💀

---

🌈 MULTIPLE INPUT FILES 🌈

if you hand her more than one input file, tcpslice merges the packets from all of them into the single output file 🫶

normally that merge is done based on the value of the time stamps in the packets in the individual files. (tcpslice assumes that within each input file, packets are in time stamp order — don't be messy, keep your files sorted.) but if you use the -l option, the value used for ordering becomes the time stamp of a given packet minus the time stamp of the first packet in the input file where that given packet lives.

when she's merging files, by default tcpslice will discard any duplicate packet she finds in more than one file. a duplicate is a packet that has an identical timestamp (either relative or absolute) and identical packet contents (for as much as was captured) as another packet previously seen in a different file.

😭 okay but here's the tea: it is possible for the network to generate true replicates of packets, and for systems that can return the same timestamp for multiple packets, these can get mistaken for duplicates and discarded. that's just how it is.

so accordingly, tcpslice will not discard duplicates in the same trace file. plus, you can use the -D option to suppress any discarding of duplicates entirely, if you're feeling paranoid 💅

and one more thing — tcpslice will refuse to merge multiple files if they don't have the same link-layer header type. she has standards. she's not gonna mix that. periodt.

---

🎀 OPTIONS 🎀

okay so first the vibe check: if any of -R, -r or -t are specified, then tcpslice reports the timestamps of the first and last packets in each input file and exits. and you can only pick one of those three, bestie. choose your fighter.

• -D — Do not discard duplicate packets seen when merging multiple trace files. ✨
• -d — Dump the start and end times specified by the given range and exit. This option is useful for checking that the given range actually specifies the times you think it does. If one of -R, -r or -t has been specified then the times are dumped in the corresponding format; otherwise, -R (raw format) is used. it's a vibe check on your own time math, lowkey iconic 🫶
• -e seconds — Specify a number of seconds to wait after the last packet was seen before considering a session to be expired (default: 0 = do not expire inactive sessions). This is only effective when the -s option is used to track sessions. 🕰️
• -f format — Specify the name format of PCAP files to which each session will be extracted (default: NULL = do not extract sessions to separate files). This is only effective when the -s option is used to track sessions. 🍓
• -h — Print the tcpslice and libpcap version strings, print a usage message, and exit. hello, goodbye, slay 💅
• -l — When merging more than one file, merge on the basis of relative time, rather than absolute time. Normally, when merging files is done, packets are merged based on absolute time stamps. With -l packets are merged based on the relative time between the start of the file in which the packet is found and the time stamp of the packet itself. The time stamp of packets in the output file is calculated as the relative time for the packet within its file plus first time. ⏳
• -R — Dump the timestamps of the first and last packets in each input file as raw timestamps (i.e., in the form sssssssss.uuuuuu). 🔥
• -r — Same as -R except the timestamps are dumped in human-readable format, similar to that used by date(1). 🌸
• -s types — Enable session tracking for the specified types, which is a comma-separated list of the following:
  • tcp — track all TCP connections
  • sip — track SIP-based VoIP calls, which may enable tracking of TCP connections but only the ones that are related to SIP calls. This feature is only available if tcpslice was linked against Aymeric Moizard's GNU oSIP library; if not, install the latest version of libosip2 from https://www.gnu.org/software/osip/ and recompile tcpslice.
  • h323 — track H.323-based VoIP calls, which may enable tracking of TCP connections but only the ones that are related to H.323 calls. This feature is only available if tcpslice was linked against Objective Systems' Open H.323 library for C; if not, install the latest version of libooh323c from https://sourceforge.net/projects/ooh323c/ and recompile tcpslice.

⚠️ and listen, session tracking altogether is only available if tcpslice was linked against a recent version (>1.20) of Rafal Wojtczuk's Network Intrusion Detection System library; if not, install the latest version of libnids from http://libnids.sourceforge.net/ and recompile tcpslice. no shortcuts bestie 😭

• -t — Same as -R except the timestamps are dumped in tcpslice format, i.e., in the ymdhmsu format discussed above. 🧚
• -v — Turn on verbose mode. Currently this only affects session tracking (-s) messages: if specified at least once, sessions openings and closings are displayed regardless of the time (by default the closings are only displayed past end-time); if specified at least twice, subsessions (sessions initiated by other sessions) openings and closings are also displayed. talkative queen 👑
• -w output-file — Direct the output to output-file rather than stdout. 📁

---

👀 SEE ALSO 👀

tcpdump(1)

---

💜 AUTHORS 💜

The original author was:

Vern Paxson, of Lawrence Berkeley Laboratory, University of California, Berkeley, CA. 🌈

It is currently maintained by The Tcpdump Group.

The current version is available at:

https://github.com/the-tcpdump-group/tcpslice

The original distribution is available via anonymous ftp:

ftp://ftp.ee.lbl.gov/tcpslice-1.2a3.tar.gz

💀 BUGS (no cap, we have notes) 💀

okay so bestie, nothing is perfect and this is the section where we're honest about it 🫶 Found a problem? A bug? A question? An enhancement you're desperate to see? Send it to:

tcpdump-workers@lists.tcpdump.org

And if you're bringing source code contributions? Those go as git pull requests through the project page up there ☝️ slay.

---

the filename lore (iykyk) 🎀

So there's this little identity crisis situation: an input filename that matches exactly the sssssssss.uuuuuu format or the ymdhmsu format we talked about earlier can get confused with a start/end time — and that's true regardless of whether the date and time are actually valid in the latter case 🙈

The fix? Sneak a leading ./ in there. For example:

• specify the file 1976y07m04d as ./1976y07m04d
• and 00000123 as ./00000123

Alternatively, just rename them to 1976y07m04d.pcap and 00000123.pcap respectively and boom, ambiguity resolved ✨

---

stuff tcpslice simply will not do 💅

• No stdin, periodt. tcpslice cannot read its input from stdin, because it uses random-access to rummage through its input files. It needs to be able to jump around, bestie, and stdin does not offer that vibe.
• Two packets minimum. tcpslice cannot process an otherwise valid input file that contains fewer than two packets. That's the floor. That's the bar. Two or nothing 😤
• It will not yeet binary garbage at your terminal. tcpslice refuses to write to its output if it's a terminal (as indicated by isatty(3)). And listen — this is not a bug but a feature, fr fr, it exists to prevent it from spraying binary data all over your terminal. Note that this means you must either redirect stdout or specify an output file via -w. Choose your fighter 🫡

---

the actual "it breaks" list 😭

tcpslice will not work properly on: - pcap files spanning more than one year - files containing portions of packets whose original length was more than 65,535 bytes - files containing fewer than two packets

Such files result in this error message:

couldn't find final packet in file

These problems are all thanks to the interpolation scheme tcpslice uses to greatly speed up its processing when dealing with large trace files — highkey a tradeoff 💀

But bestie, note the glow-up: tcpslice can efficiently extract slices from the middle of trace files of any size, and it can also work with truncated trace files (i.e., the final packet in the file is only partially present, typically due to tcpdump being ungracefully killed). Obsessed, honestly 🔥

---

compatibility tea ☕

Adding -l has broken some compatibility with older versions, since tcpslice now merges its input files, rather than (approximately) concatenating them together as it did previously. Different behaviour, different era, we move 🌈

---

wishlist era (would be nice) 🌸

• It would sometimes be convenient if you could specify a clock offset to use with the -l option.
• It would be nice if tcpslice supported more general editing of trace files.

Manifesting ✨🕯️

---

and that's the whole page, bestie!! 🎀 this one's from the tcpdump crew, dated 22 March 2024, and it lives under the name TCPSLICE(8) in the manual pages. mwah 💋 go slice some packets 💖