165 lines
4.4 KiB
Groff
165 lines
4.4 KiB
Groff
.TH BIRD-EXPORTER 1 "December 2024" "bird-exporter 0.1.0" "User Commands"
|
|
.SH NAME
|
|
bird-exporter \- Prometheus exporter for BIRD routing daemon
|
|
.SH SYNOPSIS
|
|
.B bird-exporter
|
|
[\fIOPTIONS\fR]
|
|
.SH DESCRIPTION
|
|
.B bird-exporter
|
|
is a Prometheus metrics exporter for the BIRD routing daemon. It connects to
|
|
BIRD's control socket and exports metrics about protocols, routes, and BGP
|
|
sessions in a format that can be scraped by Prometheus.
|
|
.PP
|
|
The exporter periodically queries BIRD for protocol information and caches the
|
|
results to minimize load on the BIRD daemon. The cache is updated at a
|
|
configurable interval (default: 60 seconds) and served to Prometheus on each
|
|
scrape request.
|
|
.SH OPTIONS
|
|
.TP
|
|
.B \-web.listen\-address \fIstring\fR
|
|
Address to listen on for web interface and telemetry (default: ":9324")
|
|
.TP
|
|
.B \-bird.socket \fIstring\fR
|
|
Path to BIRD control socket (default: "/var/run/bird/bird.ctl")
|
|
.TP
|
|
.B \-period \fIduration\fR
|
|
Period between scrapes of BIRD data (default: 60s)
|
|
.TP
|
|
.B \-debug
|
|
Enable debug logging (default: false)
|
|
.SH METRICS
|
|
The exporter provides the following metrics:
|
|
.TP
|
|
.B bird_protocol_up
|
|
Protocol status (1 = up, 0 = down). Labels: name, proto, table, info
|
|
.TP
|
|
.B bird_bgp_state
|
|
BGP session state (1 = Established, 0 = other). Labels: name, neighbor_address, neighbor_as, local_as, neighbor_id
|
|
.TP
|
|
.B bird_route_imported
|
|
Number of imported routes. Labels: name, proto, channel, table
|
|
.TP
|
|
.B bird_route_filtered
|
|
Number of filtered routes. Labels: name, proto, channel, table
|
|
.TP
|
|
.B bird_route_exported
|
|
Number of exported routes. Labels: name, proto, channel, table
|
|
.TP
|
|
.B bird_route_preferred
|
|
Number of preferred routes. Labels: name, proto, channel, table
|
|
.TP
|
|
.B bird_route_import_updates_total
|
|
Total number of import updates. Labels: name, proto, channel, table
|
|
.TP
|
|
.B bird_route_import_withdraws_total
|
|
Total number of import withdraws. Labels: name, proto, channel, table
|
|
.TP
|
|
.B bird_route_import_rejected_total
|
|
Total number of rejected imports. Labels: name, proto, channel, table
|
|
.TP
|
|
.B bird_route_import_filtered_total
|
|
Total number of filtered imports. Labels: name, proto, channel, table
|
|
.TP
|
|
.B bird_route_import_ignored_total
|
|
Total number of ignored imports. Labels: name, proto, channel, table
|
|
.TP
|
|
.B bird_route_import_accepted_total
|
|
Total number of accepted imports. Labels: name, proto, channel, table
|
|
.TP
|
|
.B bird_route_export_updates_total
|
|
Total number of export updates. Labels: name, proto, channel, table
|
|
.TP
|
|
.B bird_route_export_withdraws_total
|
|
Total number of export withdraws. Labels: name, proto, channel, table
|
|
.TP
|
|
.B bird_route_export_rejected_total
|
|
Total number of rejected exports. Labels: name, proto, channel, table
|
|
.TP
|
|
.B bird_route_export_filtered_total
|
|
Total number of filtered exports. Labels: name, proto, channel, table
|
|
.TP
|
|
.B bird_route_export_accepted_total
|
|
Total number of accepted exports. Labels: name, proto, channel, table
|
|
.TP
|
|
.B bird_bgp_hold_timer_seconds
|
|
BGP hold timer in seconds. Labels: name, neighbor_address
|
|
.TP
|
|
.B bird_bgp_keepalive_timer_seconds
|
|
BGP keepalive timer in seconds. Labels: name, neighbor_address
|
|
.TP
|
|
.B bird_bgp_send_hold_timer_seconds
|
|
BGP send hold timer in seconds. Labels: name, neighbor_address
|
|
.SH CONFIGURATION
|
|
Default configuration can be set in \fB/etc/default/bird-exporter\fR. The file
|
|
should contain a BIRD_EXPORTER_ARGS variable with command line arguments.
|
|
.PP
|
|
Example:
|
|
.PP
|
|
.nf
|
|
.RS
|
|
BIRD_EXPORTER_ARGS="-period=60s -bird.socket=/var/run/bird/bird.ctl"
|
|
.RE
|
|
.fi
|
|
.SH EXAMPLES
|
|
Start the exporter with default settings:
|
|
.PP
|
|
.nf
|
|
.RS
|
|
bird-exporter
|
|
.RE
|
|
.fi
|
|
.PP
|
|
Start with custom BIRD socket path:
|
|
.PP
|
|
.nf
|
|
.RS
|
|
bird-exporter -bird.socket=/run/bird.ctl
|
|
.RE
|
|
.fi
|
|
.PP
|
|
Start with custom scrape interval and listen address:
|
|
.PP
|
|
.nf
|
|
.RS
|
|
bird-exporter -period=30s -web.listen-address=:9999
|
|
.RE
|
|
.fi
|
|
.PP
|
|
Start with debug logging enabled:
|
|
.PP
|
|
.nf
|
|
.RS
|
|
bird-exporter -debug
|
|
.RE
|
|
.fi
|
|
.PP
|
|
Query metrics using curl:
|
|
.PP
|
|
.nf
|
|
.RS
|
|
curl http://localhost:9324/metrics
|
|
.RE
|
|
.fi
|
|
.SH FILES
|
|
.TP
|
|
.B /etc/default/bird-exporter
|
|
Default configuration file
|
|
.TP
|
|
.B /var/run/bird/bird.ctl
|
|
Default BIRD control socket path
|
|
.TP
|
|
.B /lib/systemd/system/bird-exporter.service
|
|
Systemd service unit file
|
|
.SH PERMISSIONS
|
|
The exporter needs read/write access to the BIRD control socket. When running
|
|
as a systemd service, it runs as the \fBbird\fR user which should have
|
|
appropriate permissions.
|
|
.SH SEE ALSO
|
|
.BR bird (1),
|
|
.BR birdc (1),
|
|
.BR prometheus (1)
|
|
.PP
|
|
Project homepage: https://git.ipng.ch/ipng/bird-exporter
|
|
.SH AUTHOR
|
|
BIRD Exporter Authors
|