FRR-WATCHFRR(8)

📦
version 10.7.1 · 23 versions
, in ubuntu stonking

💖 FRR-WATCHFRR(8) 💖

okay bestie, sit down, hydrate, and let me tell you about frr-watchfrr — this is the manual page for the FRR watchdog thing and it's genuinely SO useful. no cap.

✨ NAME ✨

frr-watchfrr — a program to monitor the status of FRRouting daemons 🫶

🌸 SYNOPSIS 🌸

watchfrr [-h] [-v]

watchfrr [option...] <daemon>...

like, that's the whole vibe. two ways to call it. slay.

🦋 DESCRIPTION 🦋

okay so watchfrr is a watchdog program. and not the creepy kind — the good kind 💅. it monitors the status of the frr daemons you hand it, and it tries to restart them if they become unresponsive or just,,, shut down. honestly? iconic behavior. protective. main character energy.

so how does it even know if a daemon is running?? great question bestie. it tries to connect to the daemon's VTY UNIX stream socket, and sends echo commands to make sure the daemon actually responds back. the way that when the daemon crashes, EOF is received from the socket — so watchfrr can react immediately. no waiting around, no ghosting. 🔥

now, to avoid restarting the daemons in quick succession (which would be messy and chaotic, and not the cute kind of chaotic), you can supply the -m and -M options to set the minimum and maximum delay between the restart commands. here's the tea on the math ☕: the minimum restart delay is recalculated each time a restart is attempted. if the time since the last restart attempt exceeds twice the value of -M, the restart delay is set to the value of -m, otherwise the interval is doubled (but capped at the value of -M). periodt.

🎀 OPTIONS 🎀

  • --dry — run watchfrr in "dry-run" mode. it only monitors the specified daemons but performs no start/stop/restart actions at all. just vibes, no touching 💀
  • -d, --daemon — run in daemon mode. when you supply this, error messages go to Syslog instead of standard output (stdout).
  • -S <directory>, --statedir <directory> — set the VTY socket directory (the default value is /var/run/frr).
  • -N <name>, --pathspace <name> — insert the given name into paths used by the FRR daemons. this gets appended to the VTY socket directory and passed to the daemons, which also add it to their paths in /etc.
  • --netns[=<name>] — (Linux only 🐧) switch network namespaces when starting watchfrr. the name defaults to the value passed with -N (which it should be used in conjunction with, iykyk). if the name is not specified, the option has no effect.

if the network namespace does not exist, it is created in a manner compatible with iproute2. network namespaces are not removed by FRR — this must be done with ip netns delete.

  • -l <level>, --loglevel <level> — set the logging level (the default value is 6). the value should range from 0 (LOG_EMERG) to 7 (LOG_DEBUG), but higher numbers can be supplied if extra debugging messages are required. go off, honestly.
  • --min-restart-interval <number> — set the minimum number of seconds to wait between invocations of the daemon restart commands (the default value is 60).
  • --max-restart-interval <number> — set the maximum number of seconds to wait between invocations of the daemon restart commands (the default value is 600).
  • -i <number>, --interval <number> — set the status polling interval in seconds (the default value is 5).
  • -t <number>, --timeout <number> — set the unresponsiveness timeout in seconds (the default value is 10).
  • -T <number>, --restart-timeout <number> — set the restart (kill) timeout in seconds (the default value is 20). if any background jobs are still running after this period has elapsed, they will be killed. brutal but necessary 💅
  • -p <filename>, --pid-file <filename> — set the process identifier filename (the default value is /var/run/frr/watchfrr.pid).
  • -b <string>, --blank-string <string> — when the supplied string is found in any of the command line option arguments (i.e., -r, -s, or -k), replace it with a space.

this is, and I quote, an "ugly hack" to circumvent problems with passing the command line arguments containing embedded spaces. at least it's self-aware 🙈

  • -v, --version — display the version information and exit.
  • -h, --help — display the usage information and exit.

the following 3 options specify scripts that watchfrr uses to perform start/stop/restart actions. reasonable default values are built into watchfrr, so the use of these options should no longer be necessary (they're giving legacy, ngl):

  • -s command, --start-command command — supply a Bourne shell command to start a single daemon. the command string should contain the '%s' placeholder to be substituted with the daemon name.
  • -k command, --kill-command command — supply a Bourne shell command to stop a single daemon. the command string should contain the '%s' placeholder to be substituted with the daemon name.
  • -r command, --restart command — supply a Bourne shell command to restart a single daemon. the command string should contain the '%s' placeholder to be substituted with the daemon name.

💀 PREVIOUS OPTIONS 💀

bestie. gather round. prior versions of watchfrr supported some additional options that no longer exist:

-a, -A, -e, -R, -z

here's what happened to them, lore drop 📖:

  • the -a, -A and -R options were used to select alternate monitoring modes that offered different patterns of restarting daemons. the "correct" mode (phased restart) is now the default 👑.
  • the -e and -z options used to disable some monitoring aspects — watchfrr now always has all monitoring features enabled.

removing these options should result in correct operation. if it does not, please file a bug report 🐛.

🍓 FILES 🍓

  • /usr/lib/frr/watchfrr — the default location of the watchfrr binary.
  • /etc/frr/watchfrr.conf — the default location of the watchfrr config file.
  • $(PWD)/watchfrr.log — if the watchfrr process is configured to output logs to a file, then you will find this file in the directory where you started watchfrr.

🌈 WARNING 🌈

this man page is intended to be a quick reference for command line options. the definitive document is the info file frr latest or the documentation available on the project website at <https://frrouting.org/>. so like, don't come for me if you need the full deep dive 💜

🧚 DIAGNOSTICS 🧚

the daemon may log to standard output, to a VTY, to a log file, or through syslog to the system logs. FRR supports many debugging options — see the Info file, web docs or source for details. she's flexible, she contains multitudes ✨

⭐ SEE ALSO ⭐

frr-zebra(8), vtysh(1), frr-ripd(8), frr-ripngd(8), frr-ospfd(8), frr-ospf6d(8), frr-bgpd(8), frr-isisd(8), frr-babeld(8), frr-nhrpd(8), frr-pimd(8), frr-pbrd(8), frr-ldpd(8), frr-eigrpd(8), frr-staticd(8), frr-fabricd(8), frr-vrrpd(8), mtracebis(8) <https://frrouting.org/>

🐛 BUGS 🐛

FRR eats bugs for breakfast. if you have food for the maintainers, please email <dev@lists.frrouting.org>. they're hungry, feed them 🫶

2017, FRR

that's a wrap bestie!! this page is from the latest manual, dated Sep 22, 2026, and it's the FRR-WATCHFRR(8) page 💖✨ go watch those daemons, you got this 🎀

📦 where this page comes from