Initial commit

docs/bird-exporter.1

@@ -0,0 +1,164 @@
+.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