{"id":19451837,"url":"https://github.com/skoef/birdwatcher","last_synced_at":"2025-04-25T04:30:31.842Z","repository":{"id":40430180,"uuid":"224627196","full_name":"skoef/birdwatcher","owner":"skoef","description":"healthchecker for BIRD-anycasted services","archived":false,"fork":false,"pushed_at":"2025-03-28T16:31:31.000Z","size":117,"stargazers_count":13,"open_issues_count":4,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-03T15:52:31.551Z","etag":null,"topics":["anycast","bird","ecmp","golang"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skoef.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-28T10:22:20.000Z","updated_at":"2025-03-07T20:47:18.000Z","dependencies_parsed_at":"2024-06-20T18:03:42.839Z","dependency_job_id":null,"html_url":"https://github.com/skoef/birdwatcher","commit_stats":{"total_commits":40,"total_committers":4,"mean_commits":10.0,"dds":0.375,"last_synced_commit":"7c9f0b7a673b7e790c052be628d37c9db3805154"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skoef%2Fbirdwatcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skoef%2Fbirdwatcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skoef%2Fbirdwatcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skoef%2Fbirdwatcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skoef","download_url":"https://codeload.github.com/skoef/birdwatcher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250754543,"owners_count":21481835,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anycast","bird","ecmp","golang"],"created_at":"2024-11-10T16:43:12.733Z","updated_at":"2025-04-25T04:30:31.332Z","avatar_url":"https://github.com/skoef.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# birdwatcher\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/skoef/birdwatcher)](https://goreportcard.com/report/github.com/skoef/birdwatcher)\n\n\u003e healthchecker for [BIRD](https://bird.network.cz/)-anycasted services\n\n:warning: **NOTE**: this version of birdwatcher is designed to work with BIRD version 2 and up. If you want to use birdwatcher with BIRD 1.x, refer to the `bird1` branch.\n\nThis project is heavily influenced by [anycast-healthchecker](https://github.com/unixsurfer/anycast_healthchecker). If you want to know more about use cases of birdwatcher, please read their excellent documention about anycasted services and how a healthchecker can contribute to a more stable service availability.\n\nIn a nutshell: birdwatcher periodically checks a specific service and tells BIRD which prefixes to announce or to withdraw when the service appears to be up or down respectively.\n\n## Why birdwatcher\n\nWhen I found out about anycast-healthchecker (sadly only recently on [HaproxyConf 2019](https://www.haproxyconf.com/)), I figured this would solve the missing link between BIRD and whatever anycasted services I have running (mostly haproxy though). Currently however in anycast-healthchecker, it is not possible to specify multiple prefixes to a service. Some machines in these kind of setups are announcing _many_ `/32` and `/128` prefixes and I ended up specifiying so many services (one per prefix) that python crashed giving me a `too many open files` error. At first I tried to patch anycast-healthchecker but ended up writing something similar, hence birdwatcher.\n\nIt is written in Go because I like it and running multiple threads is easy.\n\n## Upgrading\n\n### Upgrading from 1.0.0-beta2 to 1.0.0-beta3\n\nThe notation of `timeout` for services changed from int (for number of seconds) to the format `time.ParseDuration` uses, such as \"300ms\", \"-1.5h\" or \"2h45m\".\n\nFor example: `10` should become `\"10s\"` in your config files.\n\n## Example usage\n\nThis simple example configures a single service, runs `haproxy_check.sh` every second and manages 2 prefixes based on the exit code of the script:\n\n```toml\n[services]\n  [services.\"foo\"]\n  command = \"/usr/bin/haproxy_check.sh\"\n  prefixes = [\"192.168.0.0/24\", \"fc00::/7\"]\n\n```\n\nSample output in `/etc/bird/birdwatcher.conf` if `haproxy_check.sh` checks out would be:\n\n```\n# DO NOT EDIT MANUALLY\nfunction match_route() -\u003e bool\n{\n\treturn net ~ [\n\t\t192.168.0.0/24,\n\t\tfc00::/7\n\t];\n}\n```\n\nAs soon as birdwatcher finds out haproxy is down, it will change the content in `/etc/bird/birdwatcher.conf` to:\n\n```\n# DO NOT EDIT MANUALLY\nfunction match_route() -\u003e bool\n{\n\treturn false;\n}\n```\n\nand reconfigures BIRD by given `reloadcommand`. Obviously, if you have multiple services being checked by birdwatcher, only the prefixes of that particular service would be removed from the list in `match_route`.\n\nIntegration in BIRD is a matter of including `/etc/bird/birdwatcher.conf` (or whatever you configured at `configfile`) in the configuration for BIRD and use it in a protocol like this:\n\n```\nprotocol bgp my_bgp_proto {\n  local as 12345;\n  neighbor 1.2.3.4 as 23435;\n  ...\n  ipv4 {\n    ...\n    export where match_route();\n  }\n  ...\n  ipv6 {\n    ...\n    export where match_route();\n  }\n}\n```\n\n## Configuration\n\n## **global**\n\nConfiguration section for global options.\n\n| key           | description                                                                                                                                     |\n| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |\n| configfile    | Path to configuration file that will be generated and should be included in the BIRD configuration. Defaults to **/etc/bird/birdwatcher.conf**. |\n| reloadcommand | Command to invoke to signal BIRD the configuration should be reloaded. Defaults to **/usr/sbin/birdc configure**.                               |\n| compatbird213 | To use birdwatcher with BIRD 2.13 or earlier, enable this flag. It will remove the function return types from the output                        |\n\n## **[services]**\n\nEach service under this section can have the following settings:\n\n| key          | description                                                                                                                                                                                                                              |\n| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| command      | Command that will be periodically run to check if the service should be considered up or down. The result is based on the exit code: a non-zero exit codes makes birdwatcher decide the service is down, otherwise it's up. **Required** |\n| functionname | Specify the name of the function birdwatcher will generate. You can use this function name to use in your protocol export filter in BIRD. Defaults to **match_route**.                                                                   |\n| interval     | The interval in seconds at which birdwatcher will check the service. Defaults to **1**                                                                                                                                                   |\n| timeout      | Time in which the check command should complete. Afterwards it will be handled as if the check command failed. Defaults to **10s**, format following that of [`time.ParseDuration`](https://pkg.go.dev/time#ParseDuration).              |\n| fail         | The amount of times the check command should fail before the service is considered to be down. Defaults to **1**                                                                                                                         |\n| rise         | The amount of times the check command should succeed before the service is considered to be up. Defaults to **1**                                                                                                                        |\n| prefixes     | Array of prefixes, mixed IPv4 and IPv6. At least 1 prefix is **required** per service                                                                                                                                                    |\n\n## **[prometheus]**\n\nConfiguration for the prometheus exporter\n\n| key     | description                                                                  |\n| ------- | ---------------------------------------------------------------------------- |\n| enabled | Boolean whether you want to export prometheus metrics. Defaults to **false** |\n| port    | Port to export prometheus metrics on. Defaults to **9091**                   |\n| path    | Path to the prometheus metrics. Defaults to **/metrics**                     |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskoef%2Fbirdwatcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskoef%2Fbirdwatcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskoef%2Fbirdwatcher/lists"}