diff --git a/Cargo.lock b/Cargo.lock index 2091482..2fdaef4 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -312,6 +312,7 @@ dependencies = [ "bgp-rpki", "bgp-server", "futures", + "nix", "prometheus", "serde", "tokio", diff --git a/bin/bgp/src/main.rs b/bin/bgp/src/main.rs index 12f8d71..7ad2cf9 100644 --- a/bin/bgp/src/main.rs +++ b/bin/bgp/src/main.rs @@ -5,7 +5,7 @@ use std::sync::Arc; use bgp_server::config::Config; use bgp_server::proto::config::BgpConfig; use bgp_server::server::{BgpServer, leave_for_restart, shut_down}; -use bgp_web::{AppState, RouterInfo}; +use bgp_web::{AppState, CommunityName, RouterInfo}; use clap::Parser; use eyre::{Context, Result}; use tracing::{error, info}; @@ -80,12 +80,23 @@ async fn main() -> Result { env!("CARGO_PKG_VERSION"), ) .with_config(args.config.to_string_lossy(), &config_string) - .with_control_communities(server.config().control.is_some()), + .with_control_communities(server.config().control.is_some()) + .with_community_names( + server + .config() + .community_names + .iter() + .map(|(community, name)| CommunityName { + community: community.clone(), + name: name.clone(), + }) + .collect(), + ), ), registry: server.registry.clone(), local_rib: server.local_rib.clone(), rib: Arc::clone(&server.rib), - refusals: server.refusals.clone(), + rejections: server.rejections.clone(), rpki: server.rpki.clone(), kernel: server.kernel.clone(), restarts: Arc::clone(&server.restarts), diff --git a/crates/integration-tests/src/test_server.rs b/crates/integration-tests/src/test_server.rs index c4c49cd..58d9528 100644 --- a/crates/integration-tests/src/test_server.rs +++ b/crates/integration-tests/src/test_server.rs @@ -78,6 +78,7 @@ impl TestServer { kernel: None, export: Default::default(), export_limits: None, + community_names: Vec::new(), control: None, graceful_restart: Default::default(), }; diff --git a/crates/server/proto/config.proto b/crates/server/proto/config.proto index 0c09164..2efe0d1 100644 --- a/crates/server/proto/config.proto +++ b/crates/server/proto/config.proto @@ -120,6 +120,23 @@ message BgpConfig { // passed on to customers only; these keep it from going further even // if a route is not marked as it should be. ExportLimits export_limits = 16; + + // Names for communities, for the status page to show in place of the + // numbers: what the marks on routes mean to a reader. A name for one + // community ("64601:100:2" is "comrack"), or for a kind of them, with + // `*` for the part left open ("64601:102:*" is "interconnection"), which + // is shown with the open part after the name. The daemon itself does + // nothing with them. + repeated CommunityName community_names = 17; +} + +// A name for a community, or for a kind of them. +message CommunityName { + // The community, standard ("64601:100") or large ("64601:100:2"), or a + // pattern of them with `*` for a part left open ("64601:102:*"). + string community = 1; + // What it is shown as. + string name = 2; } // Limits on what is announced to a peer, which hold whatever `export` diff --git a/crates/server/src/config.rs b/crates/server/src/config.rs index 8cb424f..3c27d7c 100644 --- a/crates/server/src/config.rs +++ b/crates/server/src/config.rs @@ -67,6 +67,9 @@ pub struct Config { /// The communities by which routes say who is told of them, if they /// are honoured. pub control: Option, + /// Names for communities, as (community or pattern, name), for the + /// status page. + pub community_names: Vec<(String, String)>, /// Graceful restart for peers that have no setting of their own; and /// the restart time this daemon gives, which decides how long it waits /// after it starts for its peers to send their routes. @@ -158,6 +161,7 @@ impl Config { proto.local_asn, )?; let originate = parse_originate(&proto.originate)?; + let community_names = parse_community_names(&proto.community_names)?; let ours = Ours { local_asn: proto.local_asn, router_id, @@ -202,11 +206,36 @@ impl Config { control: proto.control_communities.then_some(Control { local_asn: proto.local_asn, }), + community_names, graceful_restart: defaults.graceful_restart, }) } } +/// The names for communities, each checked to name a community or a +/// pattern of them. +fn parse_community_names( + names: &[proto::CommunityName], +) -> Result, ConfigError> { + names + .iter() + .map(|entry| { + Patterns::parse(std::slice::from_ref(&entry.community)).map_err(|problem| { + ConfigError::CommunityName { + community: entry.community.clone(), + problem, + } + })?; + if entry.name.trim().is_empty() { + return Err(ConfigError::CommunityNameEmpty { + community: entry.community.clone(), + }); + } + Ok((entry.community.clone(), entry.name.clone())) + }) + .collect() +} + /// Where BGP connections are taken: as configured, or on every address. fn parse_listen_endpoints( endpoints: &[proto::TcpEndpoint], diff --git a/crates/server/src/error.rs b/crates/server/src/error.rs index d00d27d..220fd10 100644 --- a/crates/server/src/error.rs +++ b/crates/server/src/error.rs @@ -213,6 +213,13 @@ pub enum ConfigError { Export(#[from] ExportProblem), #[error("export_limits: {0}")] ExportLimits(ImportProblem), + #[error("community_names {community:?}: {problem}")] + CommunityName { + community: String, + problem: crate::marks::MarksProblem, + }, + #[error("community_names {community:?}: the name is empty")] + CommunityNameEmpty { community: String }, #[error( "accept_unconfigured_peers is set and export.learned_routes passes learned routes on: \ a peer that is not configured has no role, so the routes it sends would go to every \ diff --git a/crates/web/Cargo.toml b/crates/web/Cargo.toml index 19acbfd..c047d36 100644 --- a/crates/web/Cargo.toml +++ b/crates/web/Cargo.toml @@ -22,6 +22,7 @@ serde.workspace = true tokio.workspace = true tokio-stream.workspace = true tracing.workspace = true +nix = { workspace = true, features = ["hostname"] } [lints] workspace = true diff --git a/crates/web/src/api.rs b/crates/web/src/api.rs index 6e90a50..f37fff3 100644 --- a/crates/web/src/api.rs +++ b/crates/web/src/api.rs @@ -25,7 +25,7 @@ use bgp_server::rpki::PathCheck; use bgp_server::session::{ConfiguredPeer, DialState, PeerId, SessionHandle, SessionRegistry}; use serde::{Deserialize, Serialize}; -use crate::AppState; +use crate::{AppState, CommunityName}; // --------------------------------------------------------------------------- // Views @@ -54,6 +54,9 @@ pub struct StatusView { /// Whether large communities of our AS ask for things here /// (`control_communities`). pub control_communities: bool, + /// Names for communities, as configured, for showing in place of the + /// numbers. + pub community_names: Vec, } #[derive(Debug, Clone, Serialize)] @@ -600,6 +603,7 @@ pub async fn status(State(state): State) -> Result, U received_routes: state.rib.len(), received_prefixes: state.rib.prefix_count(), control_communities: state.info.control_communities, + community_names: state.info.community_names.clone(), })) } diff --git a/crates/web/src/lib.rs b/crates/web/src/lib.rs index 292ee89..5db1421 100644 --- a/crates/web/src/lib.rs +++ b/crates/web/src/lib.rs @@ -23,6 +23,7 @@ use bgp_rpki::Rpki; use bgp_server::rejections::RejectionLog; use bgp_server::restart::Restarts; use bgp_server::session::SessionRegistry; +use serde::Serialize; use tokio::net::TcpListener; use tracing::info; @@ -48,6 +49,18 @@ pub struct RouterInfo { /// Whether large communities of our AS ask for things here /// (`control_communities`), so that the status page can say what. pub control_communities: bool, + /// Names for communities, as configured (`community_names`), for the + /// status page to show in place of the numbers. + pub community_names: Vec, +} + +/// A name for a community, or for a kind of them. +#[derive(Debug, Clone, Serialize)] +pub struct CommunityName { + /// The community, or a pattern of them with `*` for a part left open: + /// `64601:100:2`, `64601:102:*`. + pub community: String, + pub name: String, } impl RouterInfo { @@ -61,9 +74,16 @@ impl RouterInfo { hostname: hostname(), config: None, control_communities: false, + community_names: Vec::new(), } } + /// Records the names configured for communities. + pub fn with_community_names(mut self, names: Vec) -> Self { + self.community_names = names; + self + } + /// Records whether control communities are acted on. pub fn with_control_communities(mut self, on: bool) -> Self { self.control_communities = on; @@ -80,13 +100,10 @@ impl RouterInfo { /// Best-effort host name without pulling in a dependency: ask the `hostname` /// utility, which exists on every platform we run on. fn hostname() -> String { - std::process::Command::new("hostname") - .output() + nix::unistd::gethostname() .ok() - .filter(|o| o.status.success()) - .and_then(|o| String::from_utf8(o.stdout).ok()) - .map(|s| s.trim().to_string()) - .filter(|s| !s.is_empty()) + .and_then(|name| name.into_string().ok()) + .filter(|name| !name.is_empty()) .unwrap_or_else(|| "unknown host".into()) } diff --git a/crates/web/static/statusz.html b/crates/web/static/statusz.html index 1a2493e..35cc1dd 100644 --- a/crates/web/static/statusz.html +++ b/crates/web/static/statusz.html @@ -12,45 +12,77 @@ framework, no external resources. Everything shown comes from /api/*, except the names of AS numbers: pointing at one asks RIPEstat for its holder, from the browser (the daemon itself looks nothing up). + + How colour is used, and not used: what is normal is black on white, and + draws no attention. Red is for what has failed and needs a hand (a + session down, the kernel refusing routes). Amber is for what is degraded + or wants watching (routes held or stale, a peer restarting, RPKI data + about to expire). Green is for a system that is actively doing its job + (RPKI synchronised, kernel in step), set small. Grey is for what is + inactive or expected (a passive peer waiting, a rejection count). What + repeats on every row is a glyph with a tooltip, not a sentence. --> @@ -59,43 +91,19 @@ form.lookup input[type=text] { font-family: monospace; }
-Started: ... (up ...)
-Version ...
-Router ID ..., local AS ...
+...: router ID ..., AS ..., Ferrix ...
+Started ..., up ...
-Running on ...
-View: variables, status json, peers json, originated routes json, received routes json, rejected routes json, rpki json, kernel json

+JSON: status, peers, originated, received, rejected, rpki, kernel; metrics
- +
...
-

Peers (...)

- - - -
namepeerASstateopened bylocal address (next hop)establisheduptime4-byte ASaddress familiesroutesrejected announcementsdetail
- -

Route origin and path validation (RPKI)

-
...
- -

Originated routes (...)

- - - -
prefixoriginAS pathMEDcommunitieslarge communitiessince
- -

Kernel routes

-
...
- -

Received routes (...)

-Look up +Look up show all
+ + + +

Peers (...)

+
+ +Glyphs: v4v6 address families · GR graceful restart · ENH IPv4 with IPv6 next hops · AP ADD-PATH · 2B two-octet AS numbers only · ↑ provider ↓ customer ↔ peer RS route server RSC its client iBGP our AS. Point at one for its meaning; click a peer's name to look at its routes. +
+ + + +
namepeerstateup forour address (next hop)sessionroutesrejected · helddetail
+ +

Route origin and path validation (RPKI)

+
...
+ +

Originated routes (...)

+ + + +
prefixoriginAS pathMEDcommunitieslarge communitiessince
+ +

Kernel routes

+
...
+ +

Received routes (...)

- +
prefixfrom peerAS pathnext hoporiginMEDlocal prefcommunitieslarge communitiesother attributesRPKIASPAbest
prefixfrom peerAS pathnext hoporiginMEDlocal prefcommunitieslarge communitiesattrsRPKI · ASPA

Rejected routes (...)

-
Routes that peers announced and their import policies did not take. The counts are of announcements since the daemon started: a route that a peer announces again, and that is rejected again, counts again. The latest rejected routes of each peer are kept.
+
Routes that peers announced and their import policies did not take. The counts are of announcements since the daemon started: a route announced again and rejected again counts again. Of each peer's latest rejections, those alike are one line, with how many and when the last was.
- +
peerprefixAS pathreasonwhennext hoporiginMEDlocal prefcommunitieslarge communitiesother attributes
peerprefixAS pathreasontimeslastnext hoporigincommunitieslarge communitiesattrs
@@ -138,7 +175,10 @@ from const $ = id => document.getElementById(id); const esc = s => String(s).replace(/[&<>"']/g, c => ({'&':'&','<':'<','>':'>','"':'"',"'":'''}[c])); const state = { status: null, peers: [], local: [], received: [], receivedPage: {}, rejected: [], rpki: null, kernel: null }; - const DASH = '-'; + const DASH = '–'; + const fmtCount = n => Number(n).toLocaleString('en-US'); + // A glyph: a small badge with its meaning as the tooltip. + const glyph = (text, title, cls = '') => `${esc(text)}`; // ---- helpers ----------------------------------------------------------- const fmtDur = s => { @@ -160,8 +200,7 @@ from document.querySelectorAll('[data-until]').forEach(e => { const v = fmtDur(e.dataset.until - t); if (e.textContent !== v) e.textContent = v; }); if (state.status) $('s-uptime').textContent = fmtDur(t - state.status.started_at_unix); } - const fmtTime = unix => new Date(unix * 1000).toLocaleTimeString(); - const fmtCount = n => Number(n).toLocaleString('en-US'); + const fmtWhen = unix => new Date(unix * 1000).toLocaleString(); // What a community of ours asks for where control communities are on // (control_communities), or ''. They are acted on where a route leaves @@ -188,10 +227,30 @@ from return ''; } + // The configured name for a community (community_names): an exact one + // first, then a pattern, whose open part is shown after the name. + function communityName(c) { + // An older daemon's status has no names. + const names = (state.status && state.status.community_names) || []; + const parts = c.split(':'); + let fallback = null; + for (const entry of names) { + const pattern = entry.community.split(':'); + if (pattern.length !== parts.length) continue; + if (entry.community === c) return entry.name; + if (!fallback && pattern.every((p, i) => p === '*' || p === parts[i])) { + const open = parts.filter((_, i) => pattern[i] === '*').join(':'); + fallback = `${entry.name} ${open}`; + } + } + return fallback; + } + // Communities, one line for each AS that defines them, in the order the - // route has them; each whole, so it can be copied. Pointing at a line - // names its AS. Well-known ones by name, and ours that ask for something - // with what they ask. + // route has them. Well-known ones by name; ours that ask for something + // with what they ask as a tooltip; those with a configured name as a + // badge with that name, the number as the tooltip. Pointing at a line + // names its AS. function commList(list, large) { if (!list.length) return DASH; const owners = new Map(); @@ -203,9 +262,11 @@ from const local = state.status ? String(state.status.local_asn) : null; const lines = [...owners].map(([owner, cs]) => { const items = cs.map(c => { - const name = !large && WELL_KNOWN[c]; - if (name) return `${name}`; + const wk = !large && WELL_KNOWN[c]; + if (wk) return glyph(wk, c, 'wk'); + const name = communityName(c); const meaning = controlMeaning(c, large); + if (name) return glyph(name, meaning ? `${c}: ${meaning}` : c, meaning ? 'ctl' : 'mark'); return meaning ? `${esc(c)}` : `${esc(c)}`; @@ -217,9 +278,21 @@ from return `
${lines.join('')}
`; } - // The attributes that have no column of their own. + // The attributes that have no column of their own, as glyphs. + const OTHER_GLYPHS = { + 'atomic aggregate': ['AA', 'ATOMIC_AGGREGATE: the route is an aggregate that lost information'], + 'aggregator': ['AGG', 'AGGREGATOR: the AS and router that made the aggregate'], + 'extended communities': ['EXT', 'Extended communities'], + 'AS4_PATH': ['AS4', 'AS4_PATH: the path with four-octet AS numbers, from a two-octet session'], + 'only to customer': ['OTC', 'Only to Customer (RFC 9234): the route came down or across from this AS, and may only go on to customers'], + 'originator ID': ['OID', 'ORIGINATOR_ID: the router of our AS that learned the route from outside'], + 'cluster list': ['CL', 'CLUSTER_LIST: the route reflector clusters the route has passed through'], + }; const otherList = list => list && list.length - ? list.map(a => `
${esc(a.name)} ${esc(a.value)}
`).join('') + ? list.map(a => { + const [text, meaning] = OTHER_GLYPHS[a.name] || [a.name, a.name]; + return glyph(text, `${meaning}: ${a.value}`); + }).join('') : DASH; // An AS number, whose holder's name is shown when it is pointed at. @@ -242,43 +315,136 @@ from tick(); } - const STATE_CLASS = { Established: 'ok', Connecting: 'warn', Backoff: 'bad', Idle: 'dim', Passive: 'dim' }; - // Where several routes for a prefix are exchanged (ADD-PATH), and which way. - function addPath(p) { - const rx = p.add_path_receive || [], tx = p.add_path_send || []; - if (!rx.length && !tx.length) return ''; - const parts = []; - if (rx.length) parts.push(`receive ${esc(rx.join(', '))}`); - if (tx.length) parts.push(`send ${esc(tx.join(', '))}`); - return ` · add-path: ${parts.join('; ')}`; + // Where a peer stands, for the strip and for sorting: 0 failed, 1 + // degraded, 2 normal, 3 inactive and expected. + function peerRank(p) { + if (p.state === 'Backoff' || p.state === 'Connecting') return p.stale_until_unix ? 1 : 0; + if (p.state === 'Established') return p.stale_routes ? 1 : 2; + return 3; } + const ROLE_GLYPH = { + provider: ['↑', 'provider: we buy transit from it'], + customer: ['↓', 'customer: it buys transit from us'], + peer: ['↔', 'peer: we exchange our own and our customers’ routes'], + 'route server': ['RS', 'route server of an Internet exchange'], + 'route server client': ['RSC', 'client of a route server we run'], + }; + function roleGlyph(p) { + if (p.peer_asn === (state.status || {}).local_asn) return glyph('iBGP', 'a router of our own AS'); + const r = ROLE_GLYPH[p.role]; + if (!r) return glyph('?', 'no role configured', 'amber'); + const confirmed = p.role_confirmed ? '; the peer says so too (RFC 9234)' : p.state === 'Established' ? '; by our configuration, the peer has not said what it is' : ''; + return glyph(r[0], r[1] + confirmed); + } + // The session's capabilities as glyphs. + function sessionGlyphs(p) { + const out = []; + const families = p.address_families || []; + if (families.some(f => f.startsWith('IPv4'))) out.push(glyph('v4', 'IPv4 unicast')); + if (families.some(f => f.startsWith('IPv6'))) out.push(glyph('v6', 'IPv6 unicast')); + if (p.extended_next_hop) out.push(glyph('ENH', 'IPv4 routes go with IPv6 next hops (RFC 8950)')); + const gr = p.graceful_restart; + if (gr) out.push(glyph('GR', `Graceful restart (RFC 4724): the peer says a restart takes ${gr.restart_time_secs}s${gr.notification ? '; NOTIFICATIONs other than Hard Reset count as restarts (RFC 8538)' : ''}`)); + const rx = p.add_path_receive || [], tx = p.add_path_send || []; + if (rx.length || tx.length) out.push(glyph(`AP${rx.length ? '↓' : ''}${tx.length ? '↑' : ''}`, `ADD-PATH (RFC 7911): ${rx.length ? `we receive several paths for ${rx.join(', ')}` : ''}${rx.length && tx.length ? '; ' : ''}${tx.length ? `we send several for ${tx.join(', ')}` : ''}`)); + if (p.four_octet_asn === false) out.push(glyph('2B', 'The peer handles two-octet AS numbers only (no RFC 6793): wide AS numbers go as AS_TRANS', 'amber')); + if (p.direction) out.push(glyph(p.direction === 'outbound' ? '⇢' : '⇠', p.direction === 'outbound' ? 'the connection was opened by us' : 'the connection was opened by the peer', 'dim')); + return out.join(''); + } + const STATE_CLASS = { Established: '', Connecting: 'amber', Backoff: 'red', Idle: 'dim', Passive: 'dim' }; + function peerDetail(p) { + const parts = []; + if (p.state !== 'Established' && p.stale_until_unix) + parts.push(`restarting: ${fmtCount(p.stale_routes)} routes kept for ${until(p.stale_until_unix)}`); + if (p.state === 'Backoff') parts.push(`${esc(p.last_error || '')}; retry in ${until(p.retry_at_unix)}`); + if (p.state === 'Passive') parts.push(`waiting for the peer to connect${p.last_error ? `; last session: ${esc(p.last_error)}` : ''}`); + return parts.join('; '); + } + const ROLE_ORDER = ['iBGP', 'provider', 'route server', 'peer', 'customer', 'route server client', 'none']; + function peerGroup(p) { + if (p.peer_asn === (state.status || {}).local_asn) return 'iBGP'; + return p.role || 'none'; + } + const GROUP_TITLE = { iBGP: 'Our own routers', provider: 'Providers', 'route server': 'Route servers', peer: 'Peers', customer: 'Customers', 'route server client': 'Route server clients', none: 'Without a role' }; function renderPeers() { const b = $('peers-body'); - $('peers-count').textContent = `${state.peers.filter(p => p.state === 'Established').length} of ${state.peers.length} established`; - if (!state.peers.length) { setHTML(b, 'No peers configured and none connected.'); return; } - setHTML(b, state.peers.map(p => { + const peers = state.peers; + const up = peers.filter(p => p.state === 'Established').length; + const down = peers.filter(p => peerRank(p) === 0).length; + const waiting = peers.filter(p => p.state === 'Passive').length; + $('peers-count').textContent = `${up} of ${peers.length} established` + (down ? `, ${down} down` : '') + (waiting ? `, ${waiting} waiting` : ''); + if (!peers.length) { setHTML(b, 'No peers configured and none connected.'); return; } + const problemsOnly = $('peers-problems').checked; + const row = p => { const up = p.state === 'Established'; - const restarting = !up && p.stale_until_unix - ? `restarting: ${p.stale_routes} routes kept for ${until(p.stale_until_unix)}` : ''; - const detail = [restarting, - p.state === 'Backoff' ? `${esc(p.last_error || '')}; retry in ${until(p.retry_at_unix)}` : '', - p.state === 'Passive' ? `waiting for the peer to connect${p.last_error ? `; last session: ${esc(p.last_error)}` : ''}` : ''] - .filter(Boolean).join('; '); - const gr = p.graceful_restart; - const graceful = gr ? ` · graceful restart` : ''; - const stale = p.stale_routes ? ` (${p.stale_routes} stale)` : ''; - return ` - ${p.name ? esc(p.name) : '(inbound)'}${esc(p.peer_addr)}${asn(p.peer_asn)}${p.role ? ` ${esc(p.role)}${p.role_confirmed ? ' ✓' : ''}` : ''} - ${esc(p.state)}${up ? (p.direction === 'outbound' ? 'us' : 'peer') : DASH} - ${up ? esc(p.local_addr) : DASH}${up ? fmtTime(p.established_at_unix) : DASH} - ${up ? age(p.established_at_unix) : DASH}${up ? (p.four_octet_asn ? 'yes' : 'no') : DASH} - ${up ? esc((p.address_families || []).join(', ')) + addPath(p) + (p.extended_next_hop ? ' · IPv4 with IPv6 next hops' : '') + graceful : DASH} - ${up ? p.routes + stale : DASH} - ${up ? (p.rejected_routes ? `${p.rejected_routes}` : 0) + (p.held_routes ? ` · ${p.held_routes} held now` : '') : DASH}${detail}`; - }).join('')); + const name = p.name ? `${esc(p.name)}` : '(inbound)'; + const rejected = up ? `${fmtCount(p.rejected_routes || 0)}` : DASH; + const held = up && p.held_routes ? ` · ${fmtCount(p.held_routes)} held` : ''; + const stale = up && p.stale_routes ? ` ${glyph(`${fmtCount(p.stale_routes)} stale`, 'Kept from the peer’s last session, and not sent again yet', 'amber')}` : ''; + return ` + ${name} + ${esc(p.peer_addr)} AS${asn(p.peer_asn)} ${roleGlyph(p)} + ${esc(p.state)} + ${up ? `${age(p.established_at_unix)}` : DASH} + ${up ? esc(p.local_addr) : DASH} + ${up ? sessionGlyphs(p) : DASH} + ${up ? fmtCount(p.routes) + stale : DASH} + ${rejected}${held} + ${peerDetail(p)}`; + }; + const byName = (a, c) => (a.name || a.peer_addr).localeCompare(c.name || c.peer_addr); + let html = ''; + // What needs attention first, whoever it is; then everyone by what + // they are to us. + const problems = peers.filter(p => peerRank(p) <= 1).sort(byName); + if (problems.length) { + html += `Needing attention (${problems.length})` + problems.map(row).join(''); + } + if (!problemsOnly) { + for (const group of ROLE_ORDER) { + const members = peers.filter(p => peerRank(p) >= 2 && peerGroup(p) === group).sort(byName); + if (!members.length) continue; + html += `${GROUP_TITLE[group]} (${members.length})` + members.map(row).join(''); + } + } else if (!problems.length) { + html += 'Nothing needs attention.'; + } + setHTML(b, html); renderPeerChoices(); } + // The strip: what needs attention, in one line, or that nothing does. + function renderStrip() { + const items = []; + const peers = state.peers, k = state.kernel, r = state.rpki; + const down = peers.filter(p => peerRank(p) === 0); + if (down.length) items.push(`${down.length} session${down.length === 1 ? '' : 's'} down: ${down.map(p => `${esc(p.name || p.peer_addr)} (${esc((p.last_error || p.state).replace(/;.*$/, ''))})`).join(', ')}`); + const restarting = peers.filter(p => peerRank(p) === 1); + if (restarting.length) items.push(`${restarting.length} restarting or stale: ${restarting.map(p => `${esc(p.name || p.peer_addr)}`).join(', ')}`); + if (k && k.enabled) { + if (!k.synced) items.push('kernel catching up with the routing table'); + if (k.refused) items.push(`kernel refused ${fmtCount(k.refused)} routes`); + const unresolved = Object.values(k.unresolved || {}).reduce((a, n) => a + n, 0); + if (unresolved) items.push(`${fmtCount(unresolved)} best routes not installed (next hop unusable)`); + } + if (r && r.enabled) { + if (r.state !== 'synchronised') items.push(`RPKI ${esc(r.state)}${r.last_error ? ` (${esc(r.last_error)})` : ''}`); + else if (!r.updated_at_unix) items.push('RPKI has no data: nothing is refused as invalid'); + else if (r.expires_at_unix && r.expires_at_unix - now() < 3600) items.push(`RPKI data expires in ${until(r.expires_at_unix)} unless confirmed`); + } + const held = peers.reduce((a, p) => a + (p.held_routes || 0), 0); + const normal = []; + const up = peers.filter(p => p.state === 'Established').length; + normal.push(`${up}/${peers.length} sessions up`); + if (k && k.enabled) normal.push(`${fmtCount(k.installed)} routes in the kernel${k.synced ? ', in step' : ''}`); + if (r && r.enabled && r.state === 'synchronised' && r.updated_at_unix) normal.push(`RPKI current`); + if (held) normal.push(`${fmtCount(held)} routes held`); + const waiting = peers.filter(p => p.state === 'Passive').length; + if (waiting) normal.push(`${waiting} waiting to connect`); + const head = items.length ? items.map(i => `${i}`).join('') : 'Nothing needs attention.'; + setHTML($('strip'), head + `
${normal.join(' · ')}`); + } + // ---- looking routes up ------------------------------------------------- // The query lives in the page's address, so that it survives a reload and // auto-refresh, and can be passed on. @@ -321,7 +487,7 @@ from function renderPeerChoices() { const chosen = lookup().peer; const names = [...new Set(state.peers.filter(p => p.state === 'Established') - .map(p => p.name || p.peer_addr.replace(/:\d+$/, '').replace(/^\[|\]$/g, '')))]; + .map(p => p.name || p.peer_addr.replace(/:\d+$/, '').replace(/^\[|\]$/g, '')))].sort(); if (chosen && !names.includes(chosen)) names.push(chosen); setHTML($('lookup-peer'), '' + names.map(n => ``).join('')); @@ -344,6 +510,14 @@ from history.replaceState(null, '', url.pathname + url.search + '#received'); showLookup(); renderRefreshControl(); loadReceived().catch(console.error); + renderRejected(); + } + // What was typed is a peer's name if a peer has it: then it is the peer + // to look at, not a prefix. + function submitLookup() { + const typed = $('lookup-q').value.trim(); + const isPeer = state.peers.some(p => p.name === typed); + setLookup({ q: isPeer ? '' : typed, mode: $('lookup-mode').value, peer: isPeer ? typed : $('lookup-peer').value, best: $('lookup-best').checked }); } function renderLocal() { @@ -352,46 +526,56 @@ from const local = state.status ? state.status.local_asn : '?'; setHTML(b, state.local.map(r => ` ${esc(r.prefix)}${esc(r.origin)} - ${asPath(Array(1 + r.prepend).fill(local))}${r.med ?? DASH} + ${asPath(Array(1 + r.prepend).fill(local))}${r.med ?? DASH} ${commList(r.communities)}${commList(r.large_communities, true)} ${age(r.announced_at_unix)}`).join('')); } + const VALIDITY = { + valid: ['✓', 'green'], invalid: ['✗', 'red'], 'not found': ['–', 'dim'], unknown: ['–', 'dim'], + }; + function validity(what, value) { + if (!value) return `·`; + const [mark, cls] = VALIDITY[value] || [value, '']; + return `${mark}`; + } function renderReceived() { const b = $('received-body'), st = state.status, looking = isLookup(); const page = state.receivedPage, paged = !!(page.next_after || page.prev_before); - const shown = paged ? `${state.received.length} on this page` : `${state.received.length}`; + const shown = paged ? `${fmtCount(state.received.length)} on this page` : fmtCount(state.received.length); $('received-count').textContent = looking - ? `${shown}${paged ? '' : ' found'}${st ? ` among ${st.received_routes}` : ''}` + ? `${shown}${paged ? '' : ' found'}${st ? ` among ${fmtCount(st.received_routes)}` : ''}` : paged && st - ? `${st.received_routes}, for ${st.received_prefixes} prefixes; ${shown}` - : `${shown}${st ? `, for ${st.received_prefixes} prefixes` : ''}`; + ? `${fmtCount(st.received_routes)}, for ${fmtCount(st.received_prefixes)} prefixes; ${shown}` + : `${shown}${st ? `, for ${fmtCount(st.received_prefixes)} prefixes` : ''}`; renderPager(); if (!state.received.length) { - setHTML(b, `${looking ? 'No route matches.' : 'No routes received from peers.'}`); return; + setHTML(b, `${looking ? 'No route matches.' : 'No routes received from peers.'}`); return; } - setHTML(b, state.received.map(r => { const s = r.summary; return ` - ${esc(r.prefix)}${r.peer_name ? esc(r.peer_name) + ' ' : ''}${esc(r.peer_addr)} AS${asn(r.peer_asn)}${r.path_id ? ` path ${r.path_id}` : ''}${asPath(s.as_path)} - ${s.next_hop ? esc(s.next_hop) : DASH}${s.origin ? esc(s.origin) : DASH}${s.med ?? DASH}${s.local_pref ?? DASH} + setHTML(b, state.received.map(r => { const s = r.summary; return ` + ${r.best ? glyph('★', 'The best route for this prefix: the one chosen, installed and passed on', 'green') : ''}${r.stale ? glyph('stale', 'Kept from a session of the peer’s that ended (graceful restart), and not sent again since', 'amber') : ''} + ${esc(r.prefix)} + ${r.peer_name ? `${esc(r.peer_name)} ` : ''}${esc(r.peer_addr)} AS${asn(r.peer_asn)}${r.path_id ? ` path ${r.path_id}` : ''} + ${asPath(s.as_path)} + ${s.next_hop ? esc(s.next_hop) : DASH}${s.origin ? esc(s.origin) : DASH} + ${s.med ?? DASH}${s.local_pref ?? DASH} ${commList(s.communities)}${commList(s.large_communities, true)}${otherList(s.other)} - ${r.rpki ? `${esc(r.rpki)}` : DASH} - ${r.aspa ? `${esc(r.aspa)}` : DASH}${r.best ? 'best' : ''}${r.stale ? ` stale` : ''}`; }).join('')); + ${validity('RPKI', r.rpki)} ${validity('ASPA', r.aspa)}`; }).join('')); } - const RPKI_CLASS = { valid: 'ok', invalid: 'bad', 'not found': 'dim', unknown: 'dim' }; - const RPKI_STATE_CLASS = { synchronised: 'ok', synchronising: 'warn', connecting: 'bad' }; + const RPKI_STATE_CLASS = { synchronised: 'green', synchronising: 'amber', connecting: 'red' }; function renderRpki() { const r = state.rpki, b = $('rpki-body'); if (!r) return; if (!r.enabled) { setHTML(b, 'Not configured: routes are not validated.'); return; } const data = r.updated_at_unix - ? `${r.vrps_ipv4} IPv4 and ${r.vrps_ipv6} IPv6 VRPs and ${r.aspas} ASPAs at serial ${r.serial ?? '?'}, confirmed ${age(r.updated_at_unix)} ago` + + ? `${fmtCount(r.vrps_ipv4)} IPv4 and ${fmtCount(r.vrps_ipv6)} IPv6 VRPs and ${fmtCount(r.aspas)} ASPAs at serial ${r.serial ?? '?'}, confirmed ${age(r.updated_at_unix)} ago` + (r.expires_at_unix ? `, dropped in ${until(r.expires_at_unix)} unless confirmed again` : '') - : 'no data: every route is "not found" and none is rejected as invalid'; + : 'no data: every route is "not found" and none is refused as invalid'; setHTML(b, `Cache ${esc(r.cache || '?')}: ${esc(r.state)}` + ` (RTR version ${r.protocol_version}). ${data}.` + - (r.updated_at_unix && r.protocol_version < 2 ? '
This cache speaks an RTR version without ASPAs: AS paths are not verified.' : '') + - (r.last_error ? `
Last error: ${esc(r.last_error)}` : '')); + (r.updated_at_unix && r.protocol_version < 2 ? '
This cache speaks an RTR version without ASPAs: AS paths are not verified.' : '') + + (r.last_error ? `
Last error: ${esc(r.last_error)}` : '')); } function renderKernel() { @@ -401,13 +585,13 @@ from const row = (name, value) => `${name}${value}`; const unresolved = Object.entries(k.unresolved).map(([why, n]) => `${fmtCount(n)} ${esc(why)}`).join(', '); const summary = '' + - row('state', `${k.synced ? 'in step' : 'catching up'} with the routing table`) + + row('state', `${k.synced ? 'in step' : 'catching up'} with the routing table`) + row('routes installed', `${fmtCount(k.installed)}`) + row('installed as', `table ${k.table} metric ${k.metric} proto bgp`) + - (k.kept ? row('kept from before the restart', `${fmtCount(k.kept)}, not announced again yet`) : '') + - (unresolved ? row('not installed', `${unresolved}`) : '') + - (k.rejected ? row('rejected by the kernel', `${fmtCount(k.rejected)}`) : '') + - (k.last_error ? row('last error', `${esc(k.last_error)} (${fmtCount(k.errors)} errors in all)`) : '') + + (k.kept ? row('kept from before the restart', `${fmtCount(k.kept)}, not announced again yet`) : '') + + (unresolved ? row('not installed', `${unresolved}`) : '') + + (k.refused ? row('refused by the kernel', `${fmtCount(k.refused)}`) : '') + + (k.last_error ? row('last error', `${esc(k.last_error)} (${fmtCount(k.errors)} errors in all)`) : '') + '
'; // Interfaces that are up or have addresses get a row each; the others // (unused ports, mostly) one line between them. @@ -418,7 +602,7 @@ from const interfaces = !k.interfaces.length ? '' : '' + listed.map(i => ` - + `).join('') + @@ -427,31 +611,54 @@ from setHTML(b, summary + interfaces); } - // For each peer a line that says how many and why, then its latest few. + // The breakdown of a peer's rejections by reason: a bar, each reason a + // segment, with the counts after it. + const REASON_COLOURS = ['#88a', '#a60', '#6a6', '#c66', '#69c', '#996', '#a6a', '#999']; + function reasonBar(byReason, total) { + const reasons = Object.entries(byReason).sort((a, c) => c[1] - a[1]); + const bar = reasons.map(([reason, n], i) => + ``).join(''); + const legend = reasons.map(([reason, n], i) => + ` ${fmtCount(n)} ${esc(reason)}`).join(', '); + return `${bar}${legend}`; + } + // For each peer a line that says how many and why, then its latest + // rejections with those alike as one line. const REJECTED_SHOWN = 20; - function renderRefused() { + function renderRejected() { const b = $('rejected-body'); + const chosen = lookup().peer; + const peers = chosen ? state.rejected.filter(p => p.peer === chosen) : state.rejected; const total = state.rejected.reduce((n, p) => n + p.total, 0); - const announcements = n => `${n} announcement${n === 1 ? '' : 's'}`; - $('rejected-count').textContent = total ? `${announcements(total)} from ${state.rejected.length} peer${state.rejected.length === 1 ? '' : 's'}` : '0'; - if (!state.rejected.length) { setHTML(b, ''); return; } - setHTML(b, state.rejected.map(p => { - const why = Object.entries(p.by_reason).sort((a, c) => c[1] - a[1]).map(([reason, n]) => `${n} ${esc(reason)}`).join(', '); - const more = p.recent.length > REJECTED_SHOWN - ? ` Latest ${REJECTED_SHOWN} shown; the latest ${p.recent.length} as json.` : ''; - return `` + - p.recent.slice(0, REJECTED_SHOWN).map(r => { const s = r.summary; return ` + const announcements = n => `${fmtCount(n)} announcement${n === 1 ? '' : 's'}`; + $('rejected-count').textContent = total ? `${announcements(total)} from ${state.rejected.length} peer${state.rejected.length === 1 ? '' : 's'}${chosen ? `; showing ${chosen}` : ''}` : '0'; + if (!peers.length) { setHTML(b, ``); return; } + setHTML(b, peers.map(p => { + // Alike: the same prefix, for the same reason, by the same path. + const alike = new Map(); + for (const r of p.recent) { + const key = `${r.prefix}|${r.reason}|${r.as_path.join(' ')}`; + const seen = alike.get(key); + if (seen) { seen.times += 1; seen.first = Math.min(seen.first, r.at_unix); } + else alike.set(key, { ...r, times: 1, first: r.at_unix }); + } + const lines = [...alike.values()].sort((a, c) => c.at_unix - a.at_unix).slice(0, REJECTED_SHOWN); + const more = alike.size > REJECTED_SHOWN + ? ` ${REJECTED_SHOWN} of ${alike.size} shown; the latest ${p.recent.length} as json.` : ''; + return `` + + lines.map(r => { const s = r.summary; return ` - + + + - `; }).join(''); }).join('')); } // ---- data loading ------------------------------------------------------ - async function loadStatus() { state.status = await getJSON('/api/status'); renderStatus(); renderLocal(); renderReceived(); } - async function loadPeers() { state.peers = await getJSON('/api/peers'); renderPeers(); } + async function loadStatus() { state.status = await getJSON('/api/status'); renderStatus(); renderLocal(); renderReceived(); renderPeers(); renderStrip(); } + async function loadPeers() { state.peers = await getJSON('/api/peers'); renderPeers(); renderStrip(); } // The way to the pages before and after this one, where there are any. function renderPager() { const page = state.receivedPage, place = pagePlace(); @@ -476,14 +683,14 @@ from } catch (e) { // A query the server could not make sense of: say what it said. state.received = []; state.receivedPage = {}; - note.innerHTML = `${esc(e.message.replace(/^[^:]*: \d+ /, ''))}`; + note.innerHTML = `${esc(e.message.replace(/^[^:]*: \d+ /, ''))}`; } renderReceived(); } - async function loadRefused() { state.rejected = await getJSON('/api/routes/rejected'); renderRefused(); } - async function loadRpki() { state.rpki = await getJSON('/api/rpki'); renderRpki(); } - async function loadKernel() { state.kernel = await getJSON('/api/kernel'); renderKernel(); } - async function loadAll() { await Promise.all([loadStatus(), loadPeers(), loadLocal(), loadReceived(), loadRefused(), loadRpki(), loadKernel()]); } + async function loadRejected() { state.rejected = await getJSON('/api/routes/rejected'); renderRejected(); } + async function loadRpki() { state.rpki = await getJSON('/api/rpki'); renderRpki(); renderStrip(); } + async function loadKernel() { state.kernel = await getJSON('/api/kernel'); renderKernel(); renderStrip(); } + async function loadAll() { await Promise.all([loadStatus(), loadPeers(), loadLocal(), loadReceived(), loadRejected(), loadRpki(), loadKernel()]); } // ---- events ------------------------------------------------------------ function logEvent(html) { @@ -494,16 +701,16 @@ from const names = list => list.map(c => WELL_KNOWN[c] || c).map(esc).join(' '); function describe(ev) { switch (ev.type) { - case 'session_up': return `session UP with ${esc(ev.peer.name || ev.peer.peer_addr)} AS${ev.peer.peer_asn} (opened by ${ev.peer.direction === 'outbound' ? 'us' : 'peer'})`; + case 'session_up': return `session UP with ${esc(ev.peer.name || ev.peer.peer_addr)} AS${ev.peer.peer_asn} (opened by ${ev.peer.direction === 'outbound' ? 'us' : 'peer'})`; case 'route_refresh_requested': return `${esc(ev.peer.name || ev.peer.peer_addr)} AS${ev.peer.peer_asn} asked for a route refresh; re-sent its routes`; - case 'session_down': return `session DOWN with ${esc(ev.peer_addr)} AS${ev.peer_asn}`; + case 'session_down': return `session DOWN with ${esc(ev.peer_addr)} AS${ev.peer_asn}`; case 'local_announced': { const r = ev.route; return `originating ${esc(r.prefix)}` + (r.communities.length ? ` [${names(r.communities)}]` : '') + (r.large_communities.length ? ` [${names(r.large_communities)}]` : '') + (r.prepend ? ` prepend ${r.prepend}` : '') + (r.med != null ? ` med ${r.med}` : ''); } - case 'local_withdrawn': return `no longer originating ${esc(ev.prefix)}`; + case 'local_withdrawn': return `no longer originating ${esc(ev.prefix)}`; case 'best_changed': return `best route for ${esc(ev.route.prefix)} is now from AS${ev.route.peer_asn} path [${ev.route.summary.as_path.join(' ')}]`; - case 'best_withdrawn': return `${esc(ev.prefix)} has no route any more`; - case 'lagged': return `missed ${ev.missed == null ? '' : ev.missed + ' '}events on ${esc(ev.stream)}`; + case 'best_withdrawn': return `${esc(ev.prefix)} has no route any more`; + case 'lagged': return `missed ${ev.missed == null ? '' : ev.missed + ' '}events on ${esc(ev.stream)}`; default: return esc(JSON.stringify(ev)); } } @@ -580,11 +787,18 @@ from }).catch(console.error); renderRefreshControl(); showLookup(); - $('lookup').addEventListener('submit', e => { - e.preventDefault(); - setLookup({ q: $('lookup-q').value.trim(), mode: $('lookup-mode').value, peer: $('lookup-peer').value, best: $('lookup-best').checked }); - }); + $('lookup').addEventListener('submit', e => { e.preventDefault(); submitLookup(); }); $('lookup-clear').addEventListener('click', e => { e.preventDefault(); setLookup(null); }); + $('peers-problems').addEventListener('change', renderPeers); + // A peer's name anywhere on the page leads to its routes. + document.addEventListener('click', e => { + const link = e.target.closest('a.peer-link'); + if (!link) return; + e.preventDefault(); + const l = lookup(); + setLookup({ q: '', mode: l.mode, peer: link.dataset.peer, best: false }); + $('received').scrollIntoView(); + }); for (const id of ['received-pager', 'received-pager-below']) { $(id).addEventListener('click', e => { const to = e.target.closest('a[data-page]'); @@ -592,7 +806,7 @@ from e.preventDefault(); setPage(JSON.parse(to.dataset.page)); }); } - loadAll().catch(e => logEvent(`${esc(e.message)}`)); + loadAll().catch(e => logEvent(`${esc(e.message)}`)); if (REFRESH) { connect(); setInterval(() => loadAll().catch(console.error), REFRESH * 1000); diff --git a/docs/content/docs/operations/monitoring.md b/docs/content/docs/operations/monitoring.md index d1dc92d..bb67664 100644 --- a/docs/content/docs/operations/monitoring.md +++ b/docs/content/docs/operations/monitoring.md @@ -25,20 +25,63 @@ Table 1 lists the HTTP endpoints. All endpoints are read-only. ## Status Page -The status page, `/statusz`, displays the following information: +The status page, `/statusz`, opens with a status line that lists what +needs attention: neighbors whose sessions are down, with the reason; +neighbors that are restarting; the kernel not in step with the routing +table, or refusing routes; and RPKI data that is missing or about to +expire. When nothing needs attention, the line says so. A second line +summarizes the normal state: sessions established, routes installed, and +the RPKI state. +Below the status line, the page displays the following information: + +- A lookup of received routes, by prefix, address, or neighbor name. - The configuration that was read at startup. -- Each neighbor, with its session state, address families, role and role - confirmation, number of accepted routes, rejected announcements, and held - routes, and last error. -- The originated routes, and a lookup of received routes. +- Each neighbor, with its session state, time established, next hop, + session properties, number of accepted routes, rejected announcements, + and held routes, and its last error. Neighbors that need attention are + listed first; the others are grouped by role. The **problems only** + option hides the neighbors that need no attention. - RPKI validation: the cache, the RTR version, and the age of the data. +- The originated routes. - Kernel route installation: the number of installed routes, the number of routes not installed and the reason, the last error reported by the kernel, and the interfaces. -- Rejected routes, by neighbor and by reason. +- The received routes that match the lookup, best path first. +- Rejected routes, by neighbor, with the number of rejections for each + reason, and the most recent rejected routes. Rejections of the same + prefix for the same reason by the same AS path are displayed as one row + with a count. - A live event log. +The page uses color as follows: red indicates a failure that requires +action, such as a session that is down; amber indicates a degraded state, +such as held or stale routes; green indicates a function that is operating +normally, such as the RPKI cache being synchronized; gray indicates an +inactive or expected state, such as a passive neighbor waiting for a +connection. Normal values are displayed in black. + +Properties that repeat on many rows are displayed as glyphs. Table 2 lists +them. Point to a glyph to display its meaning. + +| Glyph | Meaning | +|---|---| +| `v4`, `v6` | The address families of the session. | +| `GR` | Graceful restart is in use. | +| `ENH` | IPv4 routes are exchanged with IPv6 next hops (RFC 8950). | +| `AP↓`, `AP↑` | ADD-PATH: several paths per prefix are received, or sent. | +| `2B` | The neighbor supports two-octet AS numbers only. | +| `↑`, `↓`, `↔`, `RS`, `RSC`, `iBGP` | The role of the neighbor: provider, customer, peer, route server, route server client, or a router of the local AS. | +| `★` | The best path for the prefix. | +| `OTC`, `AA`, `AGG`, `AS4`, `OID`, `CL`, `EXT` | Path attributes without a column of their own: Only to Customer, ATOMIC_AGGREGATE, AGGREGATOR, AS4_PATH, ORIGINATOR_ID, CLUSTER_LIST, and extended communities. | +| `✓`, `✗`, `–` | RPKI or ASPA validation state: valid, invalid, or not found. | + +Communities for which `community_names` specifies a name are displayed as +a badge with that name; the community itself is displayed when you point +to the badge. Communities of the local AS that are control communities +display their effect in the same way. Well-known communities are +displayed by name. + To display the name of the holder of an AS number, point to the number. The browser requests the name from [RIPEstat](https://stat.ripe.net/); Ferrix does not send any requests itself. If the browser cannot reach RIPEstat, @@ -47,7 +90,7 @@ the page displays "name not available". ## Route Lookup The status page provides a lookup of received routes. The HTTP endpoint -`/api/routes/received` accepts the same queries. Table 2 lists the query +`/api/routes/received` accepts the same queries. Table 3 lists the query parameters. | Parameter | Result | @@ -77,18 +120,17 @@ Ferrix does not store rejected routes in the routing table. For each neighbor, it records the number of rejected routes for each reason, and the 200 most recent rejected routes with all the path attributes they were received with. The status page displays this information under "Rejected -routes"; to display the attributes of a rejected route, select **show** in -its row. The HTTP endpoint `/api/routes/rejected` returns the same -information as JSON. To display the records for one neighbor, add -`?peer=NAME`. +routes", with the attributes of each rejected route in the same columns as +the received routes. The HTTP endpoint `/api/routes/rejected` returns the +same information as JSON. To display the records for one neighbor, add +`?peer=NAME`, or select the neighbor's name on the status page. The numbers count rejected announcements, not prefixes. When a neighbor announces a route again, for example because an attribute changed, and Ferrix rejects it again, the count increases again. Two neighbors that advertise the same routes can therefore have different counts. The number of routes currently held, because they are RPKI or ASPA invalid or their -next hop is unreachable, is displayed in the neighbor table as **held -now**. +next hop is unreachable, is displayed in the neighbor table as **held**. ```json [{"peer":"transit-a","total":3,"by_reason":{"RPKI invalid":2,"bogon prefix":1}, diff --git a/docs/content/docs/reference/configuration.md b/docs/content/docs/reference/configuration.md index 8df7e9b..0414ab5 100644 --- a/docs/content/docs/reference/configuration.md +++ b/docs/content/docs/reference/configuration.md @@ -58,6 +58,7 @@ Top-level statements. | `cluster_id` string | `router_id` | Specifies the cluster ID that the router uses as a route reflector, as a dotted-quad IPv4 address. See [Route Reflection](@/docs/guides/passing-routes-on.md#route-reflection). | | `graceful_restart` [GracefulRestart](#gracefulrestart) | Enabled | Specifies graceful restart for neighbors that have no `graceful_restart` statement. Its `restart_time_seconds` also limits how long Ferrix waits at startup for neighbors to send their routes. | | `export_limits` [ExportLimits](#exportlimits) | None | Specifies limits on the routes advertised to neighbors whose role is `PROVIDER`, `PEER`, or `ROUTE_SERVER`, and to EBGP neighbors without a role, for neighbors that have no `export_limits` statement. See [Export Limits](@/docs/guides/passing-routes-on.md#export-limits). | +| `community_names` [CommunityName](#communityname), repeated | None | Specifies names that the status page displays for communities, in place of the numbers. Ferrix does not use the names otherwise. | ## Peer @@ -167,6 +168,16 @@ of the export policy, BGP roles, and communities of the routes. See | `prefixes` [PrefixRange](#prefixrange), repeated | All prefixes | Specifies the prefixes that can be advertised to the neighbor. Ferrix does not advertise learned or originated routes for other prefixes. | | `max_prefixes` uint32 | 0 (no limit) | Specifies the maximum number of routes advertised to the neighbor. If more routes are to be advertised, Ferrix advertises none of them, tears down the session with a Cease NOTIFICATION message (subcode Administrative Shutdown) that states the reason (RFC 9003), and places the neighbor in hold-down for its `import.hold_down_seconds`. | +## CommunityName + +A name for a community, or for a kind of community, displayed on the status +page. + +| Statement | Default | Description | +|---|---|---| +| `community` string | Required | Specifies a standard community (`64500:100`), a large community (`64500:100:2`), or a pattern with `*` for a part left open (`64500:102:*`). For a pattern, the status page displays the name followed by the open part. | +| `name` string | Required | Specifies the name to display. | + ## OriginatedRoute A route that Ferrix originates.
interfacestateIPv4IPv6IPv6 link-local
${esc(i.name)}${i.up ? 'up' : 'down'}${i.up ? glyph('▲ up', 'the interface is up', 'green') : glyph('▼ down', 'the interface is down', 'red')} ${lines(i.addresses.filter(v4))} ${lines(i.addresses.filter(a => !v4(a) && !linkLocal(a)))} ${lines(i.addresses.filter(linkLocal))}
Nothing a peer announced has been rejected.
${esc(p.peer)} ${esc(p.peer_addr)}: ${announcements(p.total)} rejected (${why}).${more}
${chosen ? `Nothing ${esc(chosen)} announced has been rejected.` : 'Nothing a peer announced has been rejected.'}
${esc(p.peer)} ${esc(p.peer_addr)}: ${announcements(p.total)} rejected ${reasonBar(p.by_reason, p.total)}${more}
${esc(r.prefix)}${r.path_id ? ` path ${r.path_id}` : ''}${asPath(r.as_path)}${esc(r.reason)}${age(r.at_unix)} ago${asPath(r.as_path)}${esc(r.reason)}${r.times > 1 ? `×${r.times}` : ''}${age(r.at_unix)} ago ${s.next_hop ? esc(s.next_hop) : DASH}${s.origin ? esc(s.origin) : DASH}${s.med ?? DASH}${s.local_pref ?? DASH} ${commList(s.communities)}${commList(s.large_communities, true)}${otherList(s.other)}