{"id":14965333,"url":"https://github.com/faelix/hphr","last_synced_at":"2025-10-25T11:31:26.161Z","repository":{"id":88008940,"uuid":"186883621","full_name":"faelix/hphr","owner":"faelix","description":"Halophile Router (a VyOS-based, SaltStack-automated, NetBox-configured router for small provider networks)","archived":false,"fork":false,"pushed_at":"2020-04-04T08:01:42.000Z","size":36,"stargazers_count":45,"open_issues_count":5,"forks_count":5,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-01-31T07:04:08.925Z","etag":null,"topics":["automation","bgp","ipv4","ipv6","isp","netbox","network","ospf","router","rpki","saltstack","vyos"],"latest_commit_sha":null,"homepage":null,"language":"SaltStack","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/faelix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-05-15T18:39:18.000Z","updated_at":"2024-06-03T16:56:26.000Z","dependencies_parsed_at":"2023-06-29T02:45:11.998Z","dependency_job_id":null,"html_url":"https://github.com/faelix/hphr","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faelix%2Fhphr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faelix%2Fhphr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faelix%2Fhphr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faelix%2Fhphr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/faelix","download_url":"https://codeload.github.com/faelix/hphr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238128553,"owners_count":19421053,"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":["automation","bgp","ipv4","ipv6","isp","netbox","network","ospf","router","rpki","saltstack","vyos"],"created_at":"2024-09-24T13:34:36.080Z","updated_at":"2025-10-25T11:31:20.835Z","avatar_url":"https://github.com/faelix.png","language":"SaltStack","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Image of a female moose](hphr-logo.svg)\n\n# Halophile Router (hphr)\n\nThe Halophile Router is a [VyOS](https://vyos.io/)-based, [SaltStack](https://github.com/saltstack/)-automated, [NetBox](http://github.com/digitalocean/netbox)-configured router for small provider networks.\n\nThe [slides for a short presentation](http://faelix.link/netmcr40) are available by way of explanation of this background to this project.\n\n## Using hphr\n\nYou will need:\n\n1. a salt-master server\n2. one or more VyOS routers running on amd64 architecture\n3. an instance of NetBox\n4. a shim module to add some extra data in your Salt pillar from Netbox\n\n## Configuring salt-master\n\nCopy `modules/netbox2.py` into `/home/salt/base/modules` (or similar location as appropriate).  Add and adjust the following `ext_pillar` to your Salt master's configuration:\n\n```\nextension_modules: /home/salt/base/modules\n\next_pillar:\n  - netbox2:\n      api_url: https://netbox.example.com/api/\n      api_token: f00f00f00f00f00f00f00f00f00f00f00f00f00d\n      site_details: True\n      site_prefixes: False\n      device_interfaces: True\n      ip_addresses: True\n```\n\nThen copy the contents of `salt/` to your Salt master's `file_roots` (by default this will be `/srv/salt`).\n\n## Configuring your states\n\nYou will either need to:\n\n* make a node group called `hphr` via a `node_groups.conf` file\n\n```\nnodegroups:\n  hphr:\n    - router*.example.com\n```\n\n* or adjust `salt/top.sls` to be something like:\n\n```\nbase:\n  router*.example.com:\n    - hphr\n```\n\n## Configuring your pillar\n\nWe have included `pillar-example/` to show you how we are using hphr at [FAELIX](https://faelix.net/).  **You will need to customise this heavily for your network.**\n\n## Configuration in Netbox\n\nYour routers will need to exist as devices in Netbox, with the device name matching the system host-name.\n\n### Physical Interfaces\n\nCreate physical interfaces in Netbox to match your routers' physical configuration.  Interfaces specified as \"management only\" will not be deployed to VyOS, and as such are suitable for IPMI, ILO, or other out-of-band management.\n\nAdd your IPv4 and IPv6 addresses to the interface as required.  MAC address, MTU, and up/down status are also supported.\n\n### VLANs Tagged on Physical Interfaces\n\nTo configure `vif` VLAN sub-interfaces you must ensure that the VLANs are added to the physical interface in Netbox as tagged.  For each such tagged VLAN hphr will search for a virtual interface with the name `ethX.VLAN` (e.g. `eth1.42` for VLAN 42 on `eth1`).\n\nAdd addresses to your subinterfaces as required.  Don't forget to tag them on the (real-life) devices that they are connected to.\n\n## Deploying routers\n\nYour router will need to be bootstrapped with basic Internet connectivity.  It will need that connectivity to download a compiled version of [bgpq3](https://github.com/snar/bgpq3), and subsquently fetch data to build your router's prefix-lists.\n\nThen:\n\n```\nrouter1$ configure\nrouter1# set system host-name router1.example.com\nrouter1# set service salt-minion master salt-master.example.com\nrouter1# commit\nrouter1# save\n```\n\nYou will need to accept the key:\n\n```\nsalt-master# salt-key -a router1.example.com\nsalt-master# salt router1.example.com test.ping\nrouter1.example.com:\n    True\n```\n\nAnd finally you can deploy the configuration and commit it to the router:\n\n```\nsalt-master# salt router1.example.com state.highstate\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaelix%2Fhphr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffaelix%2Fhphr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaelix%2Fhphr/lists"}