{"id":15051118,"url":"https://github.com/ansibleguy/linux_networking","last_synced_at":"2025-04-10T02:20:50.835Z","repository":{"id":53920705,"uuid":"404442328","full_name":"ansibleguy/linux_networking","owner":"ansibleguy","description":"Ansible Role to provision Linux network \u0026 routing","archived":false,"fork":false,"pushed_at":"2024-10-06T11:41:30.000Z","size":134,"stargazers_count":7,"open_issues_count":5,"forks_count":2,"subscribers_count":1,"default_branch":"latest","last_synced_at":"2024-10-13T17:42:42.912Z","etag":null,"topics":["ansible","ansible-role","automation","debian-linux","iac","infrastructure-as-code","linux-server","networking"],"latest_commit_sha":null,"homepage":"","language":"Jinja","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ansibleguy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","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},"funding":{"ko_fi":"ansible0guy","github":"ansibleguy"}},"created_at":"2021-09-08T17:46:19.000Z","updated_at":"2024-10-06T11:41:34.000Z","dependencies_parsed_at":"2023-02-12T11:20:14.393Z","dependency_job_id":"3bc18bed-43f9-4a99-811b-da72b2a1591c","html_url":"https://github.com/ansibleguy/linux_networking","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansibleguy%2Flinux_networking","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansibleguy%2Flinux_networking/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansibleguy%2Flinux_networking/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansibleguy%2Flinux_networking/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ansibleguy","download_url":"https://codeload.github.com/ansibleguy/linux_networking/tar.gz/refs/heads/latest","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248143084,"owners_count":21054702,"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":["ansible","ansible-role","automation","debian-linux","iac","infrastructure-as-code","linux-server","networking"],"created_at":"2024-09-24T21:31:00.019Z","updated_at":"2025-04-10T02:20:50.785Z","avatar_url":"https://github.com/ansibleguy.png","language":"Jinja","readme":"# Ansible Role - Linux Network Configuration\n\nAnsible Role to deploy network configuration/interfaces on linux servers. \n\n[![Lint](https://github.com/ansibleguy/linux_networking/actions/workflows/lint.yml/badge.svg)](https://github.com/ansibleguy/linux_networking/actions/workflows/lint.yml)\n[![Ansible Galaxy](https://badges.ansibleguy.net/galaxy.badge.svg)](https://galaxy.ansible.com/ui/standalone/roles/ansibleguy/linux_networking)\n\n**Molecule Integration-Tests**:\n\n* Status: [![Molecule Test Status](https://badges.ansibleguy.net/linux_networking.molecule.svg)](https://github.com/ansibleguy/_meta_cicd/blob/latest/templates/usr/local/bin/cicd/molecule.sh.j2) |\n[![Functional-Tests](https://github.com/ansibleguy/linux_networking/actions/workflows/integration_test_result.yml/badge.svg)](https://github.com/ansibleguy/linux_networking/actions/workflows/integration_test_result.yml)\n* Logs: [API](https://ci.ansibleguy.net/api/job/ansible-test-molecule-linux_networking/logs?token=2b7bba30-9a37-4b57-be8a-99e23016ce70\u0026lines=1000) | [Short](https://badges.ansibleguy.net/log/molecule_linux_networking_test_short.log) | [Full](https://badges.ansibleguy.net/log/molecule_linux_networking_test.log)\n\nInternal CI: [Tester Role](https://github.com/ansibleguy/_meta_cicd) | [Jobs API](https://github.com/O-X-L/github-self-hosted-jobs-systemd)\n\n**Tested:**\n* Debian 11\n* Debian 12\n\n----\n\n## Install\n\n```bash\n# latest\nansible-galaxy role install git+https://github.com/ansibleguy/linux_networking\n\n# from galaxy\nansible-galaxy install ansibleguy.linux_networking\n\n# or to custom role-path\nansible-galaxy install ansibleguy.linux_networking --roles-path ./roles\n\n# install dependencies\nansible-galaxy install -r requirements.yml\npython3 -m pip install -r requirements.txt\n```\n\n----\n\n## Advertisement\n\n* Need **professional support** using Ansible or Linux? Contact us:\n\n  E-Mail: [contact@oxl.at](mailto:contact@oxl.at)\n\n  Tel: [+43 3115 40 900 0](tel:+433115409000)\n\n  Web: [EN](https://www.o-x-l.com) | [DE](https://www.oxl.at)\n\n  Language: German or English\n\n* You want a simple **Ansible GUI**?\n\n  Check-out this [Ansible WebUI](https://github.com/ansibleguy/webui)\n\n----\n\n## Usage\n\n### Config\n\nDefine the network config as needed:\n```yaml\nnetwork:\n  support:\n    vlan: true\n    bridge: true\n    bonding: true\n    traffic_forwarding: true\n    ipv6: true\n\n  purge_orphaned_interfaces: true\n    \n  interfaces:  # for more config-details see: https://wiki.debian.org/NetworkConfiguration\n    ens192:\n      address: '192.168.142.90/24'\n      gateway: '192.168.142.1'\n      script_post-up: ['ip route add 172.16.100.0/24 dev ens192 src 192.168.142.90 via 192.168.142.10']\n      aliases:\n        - address: '2a09:cd41:f:42ee::1'\n          gateway: '2a09:cd41:f:42ee::f'\n        - '2a09:cd41:f:42ee::1'\n    bridge01:\n      bridge_ports: ['ens193', 'ens194']\n      script_down: ['/usr/local/sbin/random_script.sh']\n    ens195:  # initialize parent interface\n    ens195.85:\n      vlan: true\n      hotplug: false\n      address: '10.0.85.90/24'\n      gateway: '10.0.85.1'\n      nameservers: ['10.0.85.1']\n    # nic bonding\n    #   supported modes: 'balance-rr', 'active-backup', 'balance-xor', 'broadcast', '802.3ad', 'balance-tlb', 'balance-alb', 'lacp' (lacp =\u003e alias for 802.3ad)\n    #   lacp bonding =\u003e lacp needs the switch-ports to be configured as well\n    bond01:\n      bond-mode: '802.3ad'\n      bond-lacp-rate: 1\n      bond-miimon: 100\n      address: '192.168.200.10/26'\n      bond-slaves: ['ens196', 'ens197']  # don't define slave interfaces on their own\n    #   active-passive bonding\n    bond02:\n      bond-mode: 'active-passive'\n      address: '192.168.210.10/26'\n      bond-slaves: ['ens198', 'ens199']\n      # bond-primary: 'ens198'  # if no primary is defined, it will be chosen automatically\n\n  validation:\n    enable: true\n    # tests to run when a network change is done\n    #   if the tests fail; the changes of the current session will be restored\n    tests:\n      ping:\n        google_dns: '8.8.8.8'\n      port:  # will test if the remote port is reachable (only TCP)\n        internal_web:\n          host: 'someSite.internal'\n          port: 443\n\n  startup_service:\n    enable: true\n    interfaces:\n      tunnel01:\n        type: 'vti'\n        args:\n          key: 32\n          local: '192.168.133.1'\n          remote: '192.168.133.2'\n    \n    routes:\n      '192.168.142.1':\n        - net: '10.10.40.0/22'\n          metric: 50\n      tunnel01:\n        - net: '10.10.52.0/24'\n    \n    routes_cmd:\n      - 'ip route add 0.0.0.0/0 via 192.168.142.254 metric 200'\n```\n\n### Execution\n\nRun the playbook:\n```bash\nansible-playbook -K -D -i inventory/hosts.yml playbook.yml\n```\n\nThere are also some useful **tags** available:\n* base\n* interfaces\n* routing\n\n----\n\n## Functionality\n\n* **Network interfaces**\n  * bridges\n  * bonding\n  * vlans\n  * ipv4 \u0026 ipv6\n\n\n* **Static routing**\n  * via interface up-/down-scripts\n  * via startup service\n\n\n* **Default opt-in**:\n  * installing basic network-diagnostic tools\n  * purging of orphaned interfaces\n  * support for:\n    * ipv6\n\n\n* **Default opt-out**:\n  * network startup-service to allow specific configurations\n  * anti-lockout via network-validation script\n  * support for:\n    * interface bonding\n    * interface bridging\n    * vlan interfaces\n    * traffic forwarding (_router-like_)\n\n## Info\n\n\n* **Note:** this role currently only supports debian systems (_ubuntu partly_)\n\n\n* **Note:** Most of the role's functionality can be opted in or out.\n\n  For all available options - see the default-config located in [the main defaults-file](https://github.com/ansibleguy/linux_networking/blob/latest/defaults/main/1_main.yml)!\n\n\n* **Warning:** Not every setting/variable you provide will be checked for validity. Bad config might break the role!\n\n\n* **Note:** The network-validation port-check only supports TCP target-ports as UDP-connectivity cannot be verified that easily.\n\n----\n\n### Example\n\n#### Basic, Bond, Vlan\n\n**Config**\n```yaml\nnetwork:\n  support:\n    vlan: true\n    bridge: true\n    bonding: true\n    ipv6: false\n\n  interfaces:\n    ens192:\n      address: '10.48.2.90/24'\n      gateway: '10.48.2.254'\n    bond01:\n      bond-mode: 'balance-tlb'\n      address: '10.48.2.92/24'\n      bond-slaves: ['ens224', 'ens256']\n    ens161:\n    ens161.5:\n      vlan: true\n      hotplug: false\n      address: '10.10.55.10/24'\n      nameservers: ['10.0.55.1']\n      script_post-up: ['ip route add 192.168.4.0/22 via 10.10.55.1 metric 50']\n```\n\n**Result:**\n(_prettified_)\n```bash\nguy@ansible:~# ip a\n\u003e 2: ens192:\n\u003e     altname enp11s0\n\u003e     inet 10.48.2.90/24 brd 10.48.2.255 scope global ens192\n\u003e 3: bond01 \u003cMASTER,UP\u003e\n\u003e     inet 10.48.2.92/24 brd 10.48.2.255 scope global bond01\n\u003e 4: ens256: \u003cSLAVE,UP\u003e\n\u003e     altname enp27s0\n\u003e 5: ens224: \u003cSLAVE,UP\u003e\n\u003e     altname enp19s0\n\u003e 6: ens161:\n\u003e     altname enp4s0\n\u003e 7: ens161.5@ens161:\n\u003e     inet 10.10.55.10/24 brd 10.10.55.255 scope global ens161.5\n\nguy@ansible:~# ip route show\n\u003e default via 10.48.2.254 dev ens192 onlink \n\u003e 10.10.55.0/24 dev ens161.5 proto kernel scope link src 10.10.55.10 \n\u003e 10.48.2.0/24 dev bond01 proto kernel scope link src 10.48.2.92 linkdown \n\u003e 10.48.2.0/24 dev ens192 proto kernel scope link src 10.48.2.90\n\u003e 192.168.4.0/22 via 10.10.55.1 dev ens161.5 metric 50\n\nguy@ansible:~# cat /proc/net/bonding/bond01\n\u003e Ethernet Channel Bonding Driver: v5.10.0-8-amd64\n\u003e \n\u003e Bonding Mode: transmit load balancing\n\u003e Primary Slave: None\n\u003e Currently Active Slave: ens224\n\u003e MII Status: up\n\u003e MII Polling Interval (ms): 100\n\u003e Up Delay (ms): 200\n\u003e Down Delay (ms): 200\n\u003e Peer Notification Delay (ms): 0\n\u003e \n\u003e Slave Interface: ens224\n\u003e MII Status: up\n\u003e Speed: 10000 Mbps\n\u003e Duplex: full\n\u003e Link Failure Count: 0\n\u003e Permanent HW addr: xx:xx:xx:xx:xx:xx\n\u003e Slave queue ID: 0\n\u003e \n\u003e Slave Interface: ens256\n\u003e MII Status: up\n\u003e Speed: 10000 Mbps\n\u003e Duplex: full\n\u003e Link Failure Count: 0\n\u003e Permanent HW addr: xx:xx:xx:xx:xx:xx\n\u003e Slave queue ID: 0\n```\n\n#### IPv6 \u0026 Aliases\n\n**Config**\n```yaml\nnetwork:\n  validation:\n    enable: true\n  interfaces:\n    eth0:\n      address: '10.0.85.90/24'\n      gateway: '10.0.85.1'\n      aliases:\n        - address: '2a09:cd41:f:42ee::1/124'\n          gateway: '2a09:cd41:f:42ee::f'\n        - '2a09:cd41:f:42ee::2'\n```\n\n**Result:**\n(_prettified_)\n```bash\nguy@ansible:~# ping -6 one.one.one.one -I 2a09:cd41:f:42ee::2\n\u003e PING one.one.one.one(one.one.one.one (2606:4700:4700::1111)) from 2a09:cd41:f:42ee::2 : 56 data bytes\n\u003e 64 bytes from one.one.one.one (2606:4700:4700::1111): icmp_seq=1 ttl=58 time=14.7 ms\n\nguy@ansible:~# ip a\n\u003e 1: lo: \u003cLOOPBACK,UP,LOWER_UP\u003e\n\u003e 2: eth0: \u003cBROADCAST,MULTICAST,UP,LOWER_UP\u003e mtu 1500 qdisc pfifo_fast state UP group default qlen 1000\n\u003e     inet 10.0.85.90/24 brd 10.0.85.255 scope global eth0\n\u003e     inet6 2a09:cd41:f:42ee::2/128 scope global deprecated \n\u003e     inet6 2a09:cd41:f:42ee::1/124 scope global deprecated \n\nguy@ansible:~# cat /etc/network/interfaces.d/eth0\n\u003e # Ansible managed\n\u003e # ansibleguy.linux_networking\n\u003e \n\u003e # for more config-details see: https://wiki.debian.org/NetworkConfiguration\n\u003e \n\u003e auto eth0\n\u003e allow-hotplug eth0\n\u003e \n\u003e iface eth0 inet static\n\u003e     address 194.32.76.202/24\n\u003e     gateway 194.32.76.1\n\u003e     dns-nameservers 8.8.8.8 1.1.1.1\n\u003e \n\u003e # Interface aliases (additional ips)\n\u003e auto eth0:1\n\u003e allow-hotplug eth0:1\n\u003e iface eth0:1 inet6 static\n\u003e     address 2a09:cd41:f:42ee::1/124\n\u003e     gateway 2a09:cd41:f:42ee::f\n\u003e \n\u003e auto eth0:2\n\u003e allow-hotplug eth0:2\n\u003e iface eth0:2 inet6 static\n\u003e     address 2a09:cd41:f:42ee::2\n\n```","funding_links":["https://ko-fi.com/ansible0guy","https://github.com/sponsors/ansibleguy"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fansibleguy%2Flinux_networking","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fansibleguy%2Flinux_networking","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fansibleguy%2Flinux_networking/lists"}