fstrm_capture(1)

💖 fstrm_capture(1) 💖

okay bestie, welcome to the fstrm_capture(1) page, General Commands Manual edition — you're gonna eat this up, it's so good.

✨ NAME ✨

fstrm_capture</purl> — receive and save Frame Streams data from a socket. yes literally just vibe in, data in, file out. iconic. 🎀

🌸 SYNOPSIS 🌸

like, here's the shape of it:

fstrm_capture -t content-type -w filename
     [ -u socket-path ] [ -a IP -p port ]
     [ -c max-connections ] [ -b buffer-size ]
     [ -s seconds ] [ --gmtime ] [ --localtime ]
     [ -d [-d ...] ]

and the long-flag glow-up version:

fstrm_capture --type content-type --write filename
     [ --unix socket-path ] [ --tcp IP --port port ]
     [ --maxconns max-connections ] [ --buffersize buffer-size ]
     [ --split seconds ] [ --gmtime ] [ --localtime ]
     [ --debug [--debug ...] ]

🦋 DESCRIPTION 🦋

so basically fstrm_capture listens on a UNIX domain socket or a TCP socket, receives Frame Streams data, and writes that data to a file. that's the whole plot. no cap. 💅

💜 OPTIONS 💜

• -w filename, --write filename — write the data into the file filename. ok but here's the tea 👇
  • if you also passed --gmtime or --localtime, then filename gets preprocessed through strftime(). which means you can put a format string in there with the date and time all up in it, like, for the filename it creates. obsessed.
  • if filename is "-" and standard output is not connected to a terminal, fstrm_capture will write to standard output instead. but heads up bestie: output splitting (-s) may not be used when the filename is "-". that's a hard no. 🚫
  • sending SIGHUP to fstrm_capture flushes any buffered output to the file. sending SIGUSR1 closes and reopens the file. little signal moment, love that for us. ✨
• -t content-type, --type content-type — specify the content-type to receive from the socket and write to the output filename.
• -u socket-path, --unix socket-path — listen on the Unix domain socket socket-path to receive Frame Streams data. ⚠️ only one of -u or -a may be given.
• -a IP, --tcp IP — listen for TCP connections on address IP to receive Frame Streams data. ⚠️ only one of -u or -a may be given. also, using -a requires a port given with -p.
• -p port, --port port — if -a is given, listen on TCP port port to receive Frame Streams data.
• -c max-conns, --maxconns max-conns — allow at most max-conns concurrent connections. if you don't specify it, concurrent connections are just not limited at all. free range. 🐓
• -b buffersize, --buffersize buffersize — set the read buffer size to buffersize bytes. combined with -c, this can be used to limit the total memory usage of fstrm_capture. the buffersize also affects the maximum frame size that fstrm_capture will accept. frames larger than buffersize, including the 4-byte framing overhead, will be discarded. 🗑️
  • the default buffersize is 262144 (256KiB).
• -s interval, --split interval — reopen the output file every interval seconds. requires the use of either the --gmtime or --localtime options. 🔁
  • note that this file rotation is triggered by incoming data, so it may be delayed after the interval. it's giving "whenever it feels like it".
• --gmtime — process the --write filename through strftime() with the current time in GMT. this --gmtime option may be used to provide a timestamped output file when starting fstrm_capture, or when reopening an output file using the --split option, or when receiving a SIGUSR1 signal. 🕐
• --localtime — process the --write filename through strftime() with the current time in the system local time zone. this --localtime option may be used to provide a timestamped output file when starting fstrm_capture, or when reopening an output file using the --split option, or when receiving a SIGUSR1 signal. 🕓
• -d [ -d ... ], --debug [ --debug ] — increase the debugging level. without -d, fstrm_capture prints only critical error messages. up to five -d options may be specified, after which more repetitions will have no effect. so like, five is the max, bestie, don't overdo it. 🐛

🌈 EXAMPLES 🌈

receive dnstap data and save to hourly rotating files (with a converted filename such as /var/log/dnstap/dnstap-2018-05-04-12:58:48.fstrm):

fstrm_capture -t protobuf:dnstap.Dnstap \
     -u /var/run/named/dnstap.sock \
     -w /var/log/dnstap/dnstap-%F-%T.fstrm \
     -s 3600 --gmtime

look at her go. she's serving. 💅✨

👑 SEE ALSO 👑

• fstrm_dump(1)
• fstrm_replay(1)
• strftime(3)
• Frame Streams C Library https://farsightsec.github.io/fstrm

ok that's the whole page bestie, you understood all of it, i know it. go forth and capture those frames. 🫶

and finally, the little sign-off at the bottom of every page: this is the fstrm_capture(1) page from the General Commands Manual — go be the main character of your own socket. 💖 🌸 🎀