{"id":13558169,"url":"https://github.com/archf/ansible-network","last_synced_at":"2026-03-09T15:02:22.643Z","repository":{"id":89975034,"uuid":"49601543","full_name":"archf/ansible-network","owner":"archf","description":"Configure network interfaces on a target host","archived":false,"fork":false,"pushed_at":"2016-11-17T16:56:05.000Z","size":47,"stargazers_count":5,"open_issues_count":1,"forks_count":5,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-11T04:04:46.516Z","etag":null,"topics":["ansible","network","role","system"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","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/archf.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}},"created_at":"2016-01-13T21:01:40.000Z","updated_at":"2021-04-09T16:27:14.000Z","dependencies_parsed_at":"2023-06-18T16:05:04.409Z","dependency_job_id":null,"html_url":"https://github.com/archf/ansible-network","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/archf/ansible-network","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/archf%2Fansible-network","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/archf%2Fansible-network/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/archf%2Fansible-network/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/archf%2Fansible-network/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/archf","download_url":"https://codeload.github.com/archf/ansible-network/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/archf%2Fansible-network/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264803504,"owners_count":23666506,"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","network","role","system"],"created_at":"2024-08-01T12:04:47.478Z","updated_at":"2026-03-09T15:02:17.600Z","avatar_url":"https://github.com/archf.png","language":"Ruby","funding_links":[],"categories":["Ruby","ansible"],"sub_categories":[],"readme":"# ansible-network\n\nConfigure network devices on a target host.\n\n## Requirements\n\n### Ansible version\n\nMinimum required ansible version is 2.0.\n\n### Other considerations\n\nFor real devices, you must know your devices' names beforehand. You also need\nto have `python-netaddr` on your control machine.\n\n```bash\nsudo pip install python-netaddr\n```\n\n\n## Description\n\n\nConfigure network devices on a target host. This roles aims to provide a seemless\nrhel or debian derivatives configuration experience.\n\n### Templates\n\nThere are 4 templates.\n\nFor FEDORA | RHEL | CENTOS\n  * Redhat_routes.j2      -\u003e routes-* configuration files\n  * Redhat_device.j2      -\u003e ifcfg-* device files in `/etc/sysconfig/network-scripts/`\n\nFor DEBIAN | UBUNTU\n  * Debian_interfaces.j2  -\u003e main file `/etc/network/interfaces`\n  * Debian_devices.j2     -\u003e device file that goes in `/etc/network/interfaces.d/`\n\n### Configuration table\n\nList of variables to describing a device\n\n```\n| variable      | description                                        | value               | type |\n|---------------|----------------------------------------------------|---------------------|------|\n| device        | device name                                        | \u003cname\u003e              | dict |\n| type          | device type                                        | see type table      | dict |\n| stp           | on by default, force stp off when device == bridge | on,off              | dict |\n| bridge        | specify bridge to attach device to                 | \u003cname\u003e              | dict |\n| bootproto     | specify boot protocol                              | static or none,dhcp | dict |\n| onboot        | bring up at boot time                              | yes,no              | dict |\n| gw            | gateway list of ipv4 and ipv6 cidr                 | \u003cgateway ip\u003e        | dict |\n| ips           | list of ipv4 and ipv6 cidr                         | cidr                | list |\n| delay         | wait time for bridge to join network               | \u003cseconds\u003e           | dict |\n| peerdns       | use dns from option 6 (will overwite resolv.conf   | yes,no              | dict |\n| dns           | list of dns to override resolv.conf with           | see example         | list |\n| linkdelay     | wait time for ethernet, (stp converence)           | \u003cseconds\u003e           | dict |\n| routes        | list of static routes to add                       | see routes table    | list |\n| ipv6_init     | enable ipv6                                        | yes,no              | dict |\n| ipv6_fatal    | disable device on failure                          | yes,no              | dict |\n| ipv4_fatal    | disable device on failure                          | yes,no              | dict |\n| ipv6_autoconf | stateless configuration                            | yes,no              | dict |\n| ipv6_router   | node is an ipv6 router (enables ipv6 forwarding)   | yes,no              | dict |\n```\n\n* type=ovsbridge is supported\n* stp is always enabled for bridge devices unless you explicitly turn it off\n* `bootproto` defaults to 'dhcp' if ommited\n* gw is also used by ip route to set the gateway\n* if list contains multiple ips, secondary ips will be add\n* if and ipv6 addr is not in cidr notation, will default to a /64 prefix.\n* ipv6 is always enabled.\n\nDevice types\n\n```\n| value     | description                   |\n|-----------|-------------------------------|\n| Ethernet  | real physical ethernet device |\n| Bridge    | built-in linux bridge         |\n| ovsbridge | openvswitch bridge            |\n| bond      | bond several devices together |\n| 6to4      | 6to4 tunnel                   |\n```\n\n_Notes_\n  * bond support not yet implemented\n  * to detrunk a vlan, simply create a device using `\u003cdevice name\u003e.\u003cvlan_id\u003e` as device name\n\n*Routes*\n\n```\n| Variables | description  | value                                       | type |\n|-----------|--------------|---------------------------------------------|------|\n| to        | route target | cidr ip (or any value accepted by ip route) | dict |\n| gw        | gw device    | /32 ip address*                             | dict |\n```\n\nNotes:\n  * if no specific gw is provided, it will default to the device gateway\n  * to avoid duplicate default gateway, routes are defined for each devices based on subnet and subnet mask\n\n### Interesting Tips\n\n¡This sections needs a cleanup!\n\nList all fedora|rhel|centos usable device options.\n\n```bash\ncd /etc/sysconfig/network-scripts \u0026\u0026 grep -r -E -o '\\{[a-zA-Z0-9]+\\}'  | grep -E -i -I -v 'device|1|2|down|ppp|down' | uniq -u\n```\n\n```bash\n# quick nating using nftables wip\nsudo nft add table nat\nsudo nft add chain nat prerouting { type nat hook prerouting priority 0 \\; }\nsudo nft add rule nat postrouting masquerade\n```\n\n*lxc bridge nating*\n\nReplace vars with according to your needs.\n\n```bash\nLXC_BRIDGE=lxcbr0\nLXC_NETWORK=192.168.0.1\nuse_iptables_lock=\"-w\"\necho 1 \u003e /proc/sys/net/ipv4/ip_forward\niptables $use_iptables_lock -I INPUT -i ${LXC_BRIDGE} -p udp --dport 67 -j ACCEPT\niptables $use_iptables_lock -I INPUT -i ${LXC_BRIDGE} -p tcp --dport 67 -j ACCEPT\niptables $use_iptables_lock -I INPUT -i ${LXC_BRIDGE} -p udp --dport 53 -j ACCEPT\niptables $use_iptables_lock -I INPUT -i ${LXC_BRIDGE} -p tcp --dport 53 -j ACCEPT\niptables $use_iptables_lock -I FORWARD -i ${LXC_BRIDGE} -j ACCEPT\niptables $use_iptables_lock -I FORWARD -o ${LXC_BRIDGE} -j ACCEPT\niptables $use_iptables_lock -t nat -A POSTROUTING -s ${LXC_NETWORK} ! -d ${LXC_NETWORK} -j MASQUERADE\niptables $use_iptables_lock -t mangle -A POSTROUTING -o ${LXC_BRIDGE} -p udp -m udp --dport 68 -j CHECKSUM --checksum-fill\n```\n\n*enable ipv6 forwarding on bridge*\n\n```bash\nLXC_BRIDGE=lxcbr0\necho 1 \u003e /proc/sys/net/ipv6/conf/all/forwarding\necho 2 \u003e /proc/sys/net/ipv6/conf/all/accept_ra\necho 1 \u003e /proc/sys/net/ipv6/conf/all/accept_ra_from_local\ns sysctl -w net.ipv6.conf.all.accept_ra_from_local=1\ns sysctl -w net.ipv6.conf.all.accept_ra_defrtr=1\n\necho 1 \u003e /proc/sys/net/ipv6/conf/${LXC_BRIDGE}/forwarding\necho 2 \u003e /proc/sys/net/ipv6/conf/${LXC_BRIDGE}/accept_ra\ns sysctl -w net.ipv6.conf.lxcbr0.accept_ra_from_local=1\n\necho 0 \u003e /proc/sys/net/ipv6/conf/${LXC_BRIDGE}/autoconf\necho 0 \\\u003e /proc/sys/net/ipv6/conf/\\${LXC\\_BRIDGE}/accept\\_dad || true\n\nLXC_BRIDGE=lxcbr0\nLXC_IPV6_NETWORK=fd56:db20:4808:25ae::/64\nuse_iptables_lock=\"-w\"\nip6tables $use_iptables_lock -I INPUT -i ${LXC_BRIDGE} -p udp --dport 67 -j ACCEPT\nip6tables $use_iptables_lock -I INPUT -i ${LXC_BRIDGE} -p tcp --dport 67 -j ACCEPT\nip6tables $use_iptables_lock -I INPUT -i ${LXC_BRIDGE} -p udp --dport 53 -j ACCEPT\nip6tables $use_iptables_lock -I INPUT -i ${LXC_BRIDGE} -p tcp --dport 53 -j ACCEPT\nip6tables $use_iptables_lock -I FORWARD -i ${LXC_BRIDGE} -j ACCEPT\nip6tables $use_iptables_lock -I FORWARD -o ${LXC_BRIDGE} -j ACCEPT\nip6tables $use_iptables_lock -t nat -A POSTROUTING -s ${LXC_IPV6_NETWORK} ! -d ${LXC_IPV6_NETWORK} -j MASQUERADE\n```\n\n\n## Role Variables\n\n### Variables conditionally loaded\n\nThose variables from `vars/*.{yml,json}` are loaded dynamically during task\nruntime using the `include_vars` module.\n\nVariables loaded from `vars/main.yml`.\n\n```yaml\n# vars file for network\n\n```\n\nVariables loaded from `vars/Debian.yml`.\n\n```yaml\nnetwork_pkgs:\n  - bridge-utils\n  - ifenslave\n\nnetwork_ovs_service: openvswitch-nonetwork.service\nnetwork_ovs_pkg: openvswitch-switch\n\nnetwork_conf_path: \"/etc/network/interfaces.d\"\nnetwork_device_file_prefix: ''\n\n```\n\nVariables loaded from `vars/RedHat.yml`.\n\n```yaml\nnetwork_pkgs:\n  - libselinux-python\n  - bridge-utils\n  - iputils\n\nnetwork_ovs_service: openvswitch.service\nnetwork_ovs_pkg: openvswitch\n\nnetwork_conf_path: \"/etc/sysconfig/network-scripts\"\nnetwork_device_file_prefix: \"ifcfg-\"\n\n```\n\n### Default vars\n\nDefaults from `defaults/main.yml`.\n\n```yaml\n# defaults file for network\n\nnetwork_pkg_state: latest\n\n# device defaults\nnetwork_onboot: 'yes'\nnetwork_peerdns: 'no'\nnetwork_device_type: Ethernet\n\n# ethernet defaults\nnetwork_ethernet_linkdelay: 1\n\n# bridge defaults\nnetwork_bridge_delay: 1\n\n# ipv4 defaults\nnetwork_ipv4_fatal: 'no'\n\n# RHEL ipv6 defaults\nnetwork_ipv6_init: 'yes'\nnetwork_ipv6_fatal: 'no'\nnetwork_ipv6_autoconf: 'no'\nnetwork_ipv6_router: 'no'\nnetwork_ipv6_forwarding: 'no'\n\n# Debian ifupdown ipv6 defaults\n# see http://manpages.ubuntu.com/manpages/wily/en/man5/interfaces.5.html\n\n# accept_ra default value differ according to method\n#   dhcp -\u003e 1\n#   static -\u003e 2\n#   auto -\u003e 2\nnetwork_accept_ra: 1        # (0=off, 1=on, 2=on+forwarding)\nnetwork_dhcp: 0             # auto method -\u003e use stateless DHCPv6 (0=off, 1=on)\n\nnetwork_autoconf: 0         # Perform stateless autoconfiguration (0=off, 1=on)\nnetwork_dad_attempts: 60    # Number of attempts to settle DAD (0 to disable)\nnetwork_dad_interval: 0.1   # DAD state polling interval in seconds\n\n# prevent deletion on cleanup\nnetwork_unmanaged_devices:\n  - lo\n  - ovs-system\n  - vboxnet0\n  - vibr0\n\n```\n\n\n## Installation\n\n### Install with Ansible Galaxy\n\n```shell\nansible-galaxy install archf.network\n```\n\nBasic usage is:\n\n```yaml\n- hosts: all\n  roles:\n    - role: archf.network\n```\n\n### Install with git\n\nIf you do not want a global installation, clone it into your `roles_path`.\n\n```shell\ngit clone git@github.com:archf/ansible-network.git /path/to/roles_path\n```\n\nBut I often add it as a submdule in a given `playbook_dir` repository.\n\n```shell\ngit submodule add git@github.com:archf/ansible-network.git \u003cplaybook_dir\u003e/roles/network\n```\n\nAs the role is not managed by Ansible Galaxy, you do not have to specify the\ngithub user account.\n\nBasic usage is:\n\n```yaml\n- hosts: all\n  roles:\n  - role: network\n```\n\n## Ansible role dependencies\n\nNone.\n\n## Todo\n\n  * improve route template (scope \u0026 type support)\n  * improve device handler -\u003e reconfigure live ip addr with ip commands\n  * improve device handler -\u003e reconfigure live routes with ip commands\n  * make it work on ubuntu//debian\n\n## License\n\nMIT.\n\n## Author Information\n\nFelix Archambault.\n\n## Role stack\n\nThis role was carefully selected to be part an ultimate deck of roles to manage\nyour infrastructure.\n\nAll roles' documentation is wrapped in this [convenient guide](http://127.0.0.1:8000/).\n\n\n---\nThis README was generated using ansidoc. This tool is available on pypi!\n\n```shell\npip3 install ansidoc\n\n# validate by running a dry-run (will output result to stdout)\nansidoc --dry-run \u003crolepath\u003e\n\n# generate you role readme file\nansidoc \u003crolepath\u003e\n```\n\nYou can even use it programatically from sphinx. Check it out.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farchf%2Fansible-network","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farchf%2Fansible-network","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farchf%2Fansible-network/lists"}