Skip to content

write

Write messages to a file or standard output.

Synopsis

bgpipe [...] -- write [OPTIONS] PATH

Description

The write stage writes BGP messages to a local file, or to standard output when PATH is -. It is a consumer that supports bidirectional operation with -LR and mirrors messages flowing through the pipeline, serializing them to disk without consuming them - downstream stages still see every message.

The PATH argument supports time-based placeholders for automatic file rotation:

  • $TIME is replaced with the current time formatted according to --time-format
  • ${format} uses a custom Go time format (e.g., ${2006-01-02})

When --every is set, the stage rotates to a new file at the given interval. The minimum rotation interval is 60 seconds.

Files are written atomically: data is first written to a uniquely named .tmp file next to the target (eg. out.json.123456.tmp), then renamed to the final path on successful completion. Empty files are removed automatically. If PATH uses time placeholders and the target already exists (eg. after a restart within the same --every period), the file is published under a numbered name instead of overwriting it, eg. out.20260101.1500.1.json.gz. After a crash, the leftover .tmp files are kept as-is for manual recovery. Parent directories are created as needed. With --append or --create, and for targets that are not regular files (eg. /dev/null or a named pipe), data is written directly to the target instead.

The output format is auto-detected from the file extension by default. For example, output.json selects JSON, output.mrt selects MRT. The known extensions are .json, .jsonl and .txt (JSON), .mrt, .exa (ExaBGP commands), .bmp, .obmp, and .raw, .bin, .bgp (raw BGP); for any other name, use --format. Compression is also auto-detected: .gz (gzip), .bz2 (bzip2), .zst / .zstd (Zstandard). Writing to standard output defaults to JSON; use --format to override.

With --format bmp, the output is a complete BMP session: an Initiation first, then a Peer Up before the first message of each peer, and the UPDATEs as Route Monitoring. So it can be replayed to any BMP station, eg. with nc station 11019 <file.bmp. With --every, each file starts a new session. --format obmp writes each UPDATE as a standalone OpenBMP message.

Options

Option Type Default Description
--format string auto Data format: json, raw, mrt, exa, bmp, obmp, or auto (detected from extension)
--append bool false Append to file if it already exists
--create bool false Fail if the file already exists
--compress string auto Compression: auto, gz, bzip2, zstd, or none
--every duration 0 Rotate to a new file at this interval (min 60s)
--time-format string 20060102.1504 Go time format for $TIME placeholder
--type strings Write only messages of given type(s)
--skip strings Skip messages of given type(s)

Examples

Write a BGP session to a JSON file:

bgpipe -- connect 192.0.2.1 -- write -LR session.json -- connect 10.0.0.1

Write compressed MRT with hourly rotation:

bgpipe \
    -- connect 192.0.2.1 \
    -- write -LR --every 1h 'updates.$TIME.mrt.gz' \
    -- connect 10.0.0.1

Archive only UPDATE messages:

bgpipe -- read input.mrt.gz -- write --type UPDATE updates.json

Append to an existing log:

bgpipe -- read new-data.mrt.gz -- write --append archive.json

See Also

read, stdout, Stages overview