write¶
Write messages to a file or standard output.
Synopsis¶
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:
$TIMEis 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:
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:
Append to an existing log: