{"id":15676953,"url":"https://github.com/rgl/ansible-collection-tp-link-easy-smart-switch","last_synced_at":"2025-09-03T23:38:59.673Z","repository":{"id":38460630,"uuid":"365797258","full_name":"rgl/ansible-collection-tp-link-easy-smart-switch","owner":"rgl","description":"Manage TP-Link Easy Smart Switches with Ansible","archived":false,"fork":false,"pushed_at":"2022-06-03T07:40:25.000Z","size":73,"stargazers_count":35,"open_issues_count":2,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-06T22:04:50.906Z","etag":null,"topics":["ansible","switch","tl-sg108e","tp-link"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rgl.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}},"created_at":"2021-05-09T16:24:32.000Z","updated_at":"2025-02-05T21:49:50.000Z","dependencies_parsed_at":"2022-08-19T18:42:08.022Z","dependency_job_id":null,"html_url":"https://github.com/rgl/ansible-collection-tp-link-easy-smart-switch","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/rgl/ansible-collection-tp-link-easy-smart-switch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgl%2Fansible-collection-tp-link-easy-smart-switch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgl%2Fansible-collection-tp-link-easy-smart-switch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgl%2Fansible-collection-tp-link-easy-smart-switch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgl%2Fansible-collection-tp-link-easy-smart-switch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rgl","download_url":"https://codeload.github.com/rgl/ansible-collection-tp-link-easy-smart-switch/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgl%2Fansible-collection-tp-link-easy-smart-switch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273528914,"owners_count":25121822,"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","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","switch","tl-sg108e","tp-link"],"created_at":"2024-10-03T16:07:39.121Z","updated_at":"2025-09-03T23:38:59.640Z","avatar_url":"https://github.com/rgl.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ansible Collection - rgl.tp_link_easy_smart_switch\n\n[![Build status](https://github.com/rgl/ansible-collection-tp-link-easy-smart-switch/workflows/Build/badge.svg)](https://github.com/rgl/ansible-collection-tp-link-easy-smart-switch/actions?query=workflow%3ABuild)\n\n**NB** This is an experimental collection.\n\nThis collection configures the [TP-Link Easy Smart switches](https://www.tp-link.com/en/business-networking/easy-smart-switch/).\n\nThis was only tested with the [TL-SG108E switch](https://www.tp-link.com/en/business-networking/easy-smart-switch/tl-sg108e/).\n\nThe switch is managed by sending commands to the UDP `255.255.255.255:29808` broadcast endpoint (and the switch replies to the `255.255.255.255:29809` endpoint).\n\n**NB** This line of switches is somewhat insecure as, at least, its configuration protocol (UDP port 29808 and TCP port 80) uses cleartext messages. For more information see [How I can gain control of your TP-LINK home switch](https://www.pentestpartners.com/security-blog/how-i-can-gain-control-of-your-tp-link-home-switch/) and [Information disclosure vulnerability in TP-Link Easy Smart switches](https://www.chrisdcmoore.co.uk/post/tplink-easy-smart-switch-vulnerabilities/).\n\n**NB** This line of switches also implements the [Realtek Remote Control Protocol (RRCP)](https://en.wikipedia.org/wiki/Realtek_Remote_Control_Protocol).\n\n## Usage\n\nInstall the required python libraries:\n\n```bash\n# install dependencies in ubuntu 20.04.\nsudo apt-get install -y --no-install-recommends \\\n    python3-netifaces\n```\n\nInstall [this collection from Ansible Galaxy](https://galaxy.ansible.com/rgl/tp_link_easy_smart_switch) with:\n\n```bash\nansible-galaxy collection install rgl.tp_link_easy_smart_switch\n```\n\nShow the documentation:\n\n```bash\nansible-doc --list rgl.tp_link_easy_smart_switch\nansible-doc rgl.tp_link_easy_smart_switch.smrt_config\n```\n\n[Take ownership](#take-ownership-procedure) of the switch.\n\n**NB** Normally you only need to do this once.\n\nReview the [example-playbook.yml](example-playbook.yml) playbook and the [example-inventory.yml](example-inventory.yml) inventory files.\n\nExecute the playbook:\n\n```bash\nansible-playbook example-playbook.yml --check --diff -vvv\nansible-playbook example-playbook.yml --diff -vvv\n```\n\nTo build this collection from source code see the [Development section](#development).\n\n## Take Ownership Procedure\n\nThis procedure resets the switch to the default factory settings and sets the\nswitch `admin` user password and static IP configuration.\n\nMake sure your computer has an IP address in the switch final network and\nanother in the switch default `192.168.0.0/24` network.\n\n**NB** The switch will use the 192.168.0.1 IP address when there is no DHCP\nserver in the network.\n\nThis procedure assumes the host has the following netplan configuration at `/etc/netplan/config.yaml`:\n\n```yaml\nnetwork:\n  version: 2\n  renderer: networkd\n  ethernets:\n    enp3s0:\n      link-local: []\n      addresses:\n        - 10.1.0.1/24\n        - 192.168.0.254/24\n  bridges:\n    br-rpi:\n      link-local: []\n      addresses:\n        - 10.3.0.1/24\n      interfaces:\n        - vlan.rpi\n  vlans:\n    vlan.wan:\n      id: 2\n      link: enp3s0\n      link-local: []\n      addresses:\n        - 192.168.1.1/24\n      gateway4: 192.168.1.254\n      nameservers:\n        addresses:\n          # cloudflare+apnic public dns resolvers.\n          # see https://en.wikipedia.org/wiki/1.1.1.1\n          - \"1.1.1.1\"\n          - \"1.0.0.1\"\n          # google public dns resolvers.\n          # see https://en.wikipedia.org/wiki/8.8.8.8\n          #- \"8.8.8.8\"\n          #- \"8.8.4.4\"\n    vlan.rpi:\n      id: 3\n      link: enp3s0\n      link-local: []\n```\n\nAnd forwarding within the `br-rpi` interface is allowed, e.g.:\n\n```bash\nsudo -i\napt-get install iptables-persistent\ncat \u003e/etc/iptables/rules.v4 \u003c\u003c'EOF'\n*filter\n:INPUT ACCEPT [0:0]\n:FORWARD DROP [0:0]\n:OUTPUT ACCEPT [0:0]\n-A FORWARD -i br-rpi -o br-rpi -j ACCEPT\nCOMMIT\nEOF\nsed -i -E 's,^\\s*#?\\s*(net.ipv4.ip_forward=).+,\\11,g' /etc/sysctl.conf\nreboot\n```\n\n**NB** This is needed when you use docker, because it sets the default filter FORWARD policy to DROP.\n\nEnsure that the correct ip (and mac) addresses are defined in your inventory and playbook.\n\nAs an example, ensure they are defined in:\n\n* [example-inventory.yml](example-inventory.yml)\n* [example-take-ownership-playbook.yml](example-take-ownership-playbook.yml)\n* [example-playbook.yml](example-inventory.yml)\n\nWhile the switch is powered on:\n\n1. Remove all cables (except your computer) from the switch ports.\n2. Hold the switch Reset pin for 10 seconds and wait for it to reboot (when it blinks all the ports lights).\n3. Wait for the switch to boot (when your computer switch port light blinks again, it should be good to go).\n4. Execute the take ownership playbook, e.g.:\n   ```bash\n   ansible-playbook example-take-ownership-playbook.yml\n   ```\n\nYou are now ready to execute the regular (non take-ownership) playbooks.\n\n## Wireshark Filters\n\n| Display filter                  | Capture filter                          | Description                     |\n|---------------------------------|-----------------------------------------|---------------------------------|\n| `eth.src[0:3] == 50:d4:f7`      | `ether[6:4] \u0026 0xffffff00 == 0x50d4f700` | From TP-Link vendor             |\n| `eth.dst[0:3] == 50:d4:f7`      | `ether[0:4] \u0026 0xffffff00 == 0x50d4f700` | To TP-Link vendor               |\n| `eth.addr[0:3] == 50:d4:f7`     | do an `and` of the previous two lines   | From or To TP-Link vendor       |\n| `eth.addr == 50:d4:f7:22:22:22` | `ether host 50:d4:f7:22:22:22`          | Specific MAC address            |\n| `vlan`                          | `vlan`                                  | All VLANs                       |\n| `vlan.id == 2`                  | `vlan 2`                                | Specific VLAN                   |\n\nFor more information see:\n\n* [Wireshark Display Filters](https://gitlab.com/wireshark/wireshark/-/wikis/DisplayFilters).\n* [Wireshark Capture Filters](https://gitlab.com/wireshark/wireshark/-/wikis/CaptureFilters).\n* [pcap capture filters `pcap-filter(7)`](http://manpages.ubuntu.com/manpages/focal/man7/pcap-filter.7.html).\n\n## Development\n\nThis collection is developed in a Ubuntu 20.04 host by following these instructions.\n\nInstall the build environment:\n\n```bash\n./build-install.sh\n```\n\nFor historical purposes, this collection skeleton was [created with `ansible-galaxy collection init`](https://docs.ansible.com/ansible/2.11/dev_guide/developing_collections.html#creating-a-collection-skeleton) as:\n\n```bash\nansible-galaxy collection init rgl.tp_link_easy_smart_switch\ncd rgl.tp_link_easy_smart_switch\ngit init\n```\n\nBuild and install the collection:\n\n```bash\n./build.sh\n```\n\nTry the collection:\n\n```bash\nsource build-env.sh\nansible-galaxy collection install -r example-playbook-requirements.yml\nansible-inventory --list --yaml\nansible-lint example-playbook.yml\nansible-playbook example-playbook.yml --syntax-check\nansible-playbook example-playbook.yml --list-hosts\nansible-playbook example-playbook.yml --diff --check #-vvv\nansible-playbook example-playbook.yml --diff #-vvv\n```\n\nPublish the collection:\n\n```bash\n# NB get this API key/token from https://galaxy.ansible.com/me/preferences.\nexport ANSIBLE_GALAXY_SERVER_RELEASE_GALAXY_TOKEN='my-api-token'\n# NB as of 2021-05-09 there is no way to delete a collection from\n#    galaxy.ansible.com. once published, there is no going back.\n#    see https://github.com/ansible/galaxy/issues/1977\nansible-galaxy collection publish --verbose -vvv ./rgl-tp_link_easy_smart_switch-*.tar.gz\n```\n\n## Reference\n\n* [Ansible: Developing collections](https://docs.ansible.com/ansible/2.11/dev_guide/developing_collections.html).\n* [Ansible: Working With Plugins](https://docs.ansible.com/ansible/2.11/plugins/plugins.html).\n* [The Easy Smart Configuration Protocol (ESCP)](https://www.chrisdcmoore.co.uk/post/tplink-easy-smart-switch-vulnerabilities/#the-easy-smart-configuration-protocol-escp).\n* smrt python library\n  * [Forked smrt library by Philippe Chataignon](https://github.com/philippechataignon/smrt)\n    * the [`plugins/module_utils`](plugins/module_utils) directory contains a\n      slightly modified version of the `smrt` library from the [e545df10a0abf4c576b1aedf1b54a8d0faebf290](https://github.com/philippechataignon/smrt/tree/e545df10a0abf4c576b1aedf1b54a8d0faebf290) tree.\n  * [Original smrt library by Philipp Klaus](https://github.com/pklaus/smrt/tree/master/smrt)\n* IRC Channels on [Freenode](https://en.wikipedia.org/wiki/Freenode):\n  * [#ansible](irc://irc.freenode.net/#ansible)\n  * [#ansible-community](irc://irc.freenode.net/#ansible-community)\n  * [#ansible-galaxy](irc://irc.freenode.net/#ansible-galaxy)\n  * [#ansible-devel](irc://irc.freenode.net/#ansible-devel)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frgl%2Fansible-collection-tp-link-easy-smart-switch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frgl%2Fansible-collection-tp-link-easy-smart-switch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frgl%2Fansible-collection-tp-link-easy-smart-switch/lists"}