fstrm_capture(1)            General Commands Manual           fstrm_capture(1)



NAME
       fstrm_capture - Receive and save Frame Streams data from a socket.


SYNOPSIS
       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 ...] ]


       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
       fstrm_capture listens on a UNIX domain or TCP socket, receives Frame
       Streams data, and writes the data to a file.


OPTIONS
       -w filename | --write filename
              Write data to the file filename.

              If the --gmtime or --localtime option is given, filename is
              preprocessed with strftime().  This will allow specifying a
              format string which includes the date and time, for example, for
              the created filename.

              If filename is "-" and standard output is not connected to a
              terminal, fstrm_capture will write to standard output. Output
              splitting (-s) may not be used with a filename of "-".

              Sending SIGHUP to fstrm_capture will flush any buffered output
              to the file. Sending SIGUSR1 will close and reopen the file.


       -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. Use of -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 not
              specified, concurrent connections are not limited.


       -b buffersize | --buffersize buffersize
              Set 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 which
              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 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.


       --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 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.


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


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

                                                              fstrm_capture(1)