ci / test (push) Successful in 2m39s
Ansible collection that converges MeshCore repeaters through a companion radio (TCP, USB serial or BLE): admin ACL, CLI prefs, region tree, firmware facts, companion remote-CLI ACL, and the meshcore-tth extras (BLE on/off and own BLE PIN, channel-hash filter, message age, advert fairness). Every change is read, diffed, sent and read back; --check only reads. ansible-test sanity, unit tests and a galaxy build in CI. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
131 lines
4.9 KiB
Python
131 lines
4.9 KiB
Python
# Copyright: (c) 2026, TeTeHacko <tth@rfa.cz>
|
|
# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)
|
|
DOCUMENTATION = r"""
|
|
module: meshcore_acl
|
|
short_description: Admin ACL of a MeshCore repeater, over RF through a companion
|
|
author: TeTeHacko (@TeTeHacko)
|
|
description:
|
|
- Reads the repeater's real ACL with the binary access-list request (the only
|
|
way to see it remotely; `get acl` prints to the node's USB serial), then sends
|
|
`setperm <pubkey> 3` for missing admins and, with I(exclusive), `setperm <prefix> 0`
|
|
for everything else. Reads the ACL back afterwards and fails on a mismatch.
|
|
- The companion this runs through must stay admin, otherwise the next run could
|
|
not log in. It is kept even when not listed in I(admins).
|
|
options:
|
|
transport:
|
|
description:
|
|
- "Companion to talk through: C({type: tcp, host, port}), C({type: serial, port, baud})
|
|
or C({type: ble, address})."
|
|
- A BLE companion must already be bonded on the host the module runs on
|
|
(C(bluetoothctl pair)); there is no PIN option, so it never lands in a log.
|
|
While the module holds the link, the companion is not reachable from a phone.
|
|
- C(expect_freq) (MHz) refuses to send anything when the companion is on another
|
|
frequency; C(retries) and C(reply_timeout) tune the RF exchange.
|
|
type: dict
|
|
required: true
|
|
target:
|
|
description: Full 64-hex pubkey of the repeater.
|
|
type: str
|
|
required: true
|
|
password:
|
|
description: Admin password. Empty = blank login, works for a companion already in the ACL.
|
|
type: str
|
|
default: ""
|
|
admins:
|
|
description: Full 64-hex pubkeys that must be admin.
|
|
type: list
|
|
elements: str
|
|
required: true
|
|
exclusive:
|
|
description: Remove every ACL entry that is not in I(admins).
|
|
type: bool
|
|
default: true
|
|
"""
|
|
|
|
EXAMPLES = r"""
|
|
- name: Exactly these admins
|
|
tth.meshcore.meshcore_acl:
|
|
transport: {type: tcp, host: 127.0.0.1, port: 5000}
|
|
target: "{{ mc_target }}"
|
|
password: "{{ vault_meshcore_admin_password }}"
|
|
admins:
|
|
- "{{ managing_companion_pubkey }}"
|
|
- "{{ my_phone_pubkey }}"
|
|
"""
|
|
|
|
from ansible.module_utils.basic import AnsibleModule, missing_required_lib
|
|
from ansible_collections.tth.meshcore.plugins.module_utils.meshcore_link import (
|
|
HAS_MESHCORE,
|
|
HEX64,
|
|
Link,
|
|
LinkError,
|
|
run,
|
|
)
|
|
from ansible_collections.tth.meshcore.plugins.module_utils.meshcore_plan import PERM_ADMIN, plan_acl
|
|
|
|
|
|
async def work(module, link):
|
|
p = module.params
|
|
await link.open()
|
|
try:
|
|
await link.login()
|
|
before = await link.acl()
|
|
me = link.self_pubkey()
|
|
add, remove = plan_acl(before, p["admins"], p["exclusive"], keep=[me])
|
|
add_pfx = {a[:12] for a in add}
|
|
expected = (set(before) - set(remove)) | add_pfx
|
|
result = {
|
|
"changed": bool(add or remove),
|
|
"add": add,
|
|
"remove": remove,
|
|
"diff": {
|
|
"before": "".join(f"{k} {before[k]}\n" for k in sorted(before)),
|
|
"after": "".join(f"{k} {PERM_ADMIN if k in add_pfx else before[k]}\n" for k in sorted(expected)),
|
|
},
|
|
}
|
|
if module.check_mode or not result["changed"]:
|
|
return result
|
|
for pk in add:
|
|
await link.cli(f"setperm {pk} {PERM_ADMIN}", r"^(OK|Err)")
|
|
for pfx in remove:
|
|
# a prefix that is gone already answers "Err - invalid params": fine
|
|
await link.cli(f"setperm {pfx} 0", r"^(OK|Err)")
|
|
after = await link.acl()
|
|
left_add, left_remove = plan_acl(after, p["admins"], p["exclusive"], keep=[me])
|
|
if left_add or left_remove:
|
|
raise LinkError(f"ACL after apply still differs: missing {left_add}, extra {left_remove}")
|
|
result["acl"] = after
|
|
return result
|
|
finally:
|
|
await link.close()
|
|
|
|
|
|
def main():
|
|
module = AnsibleModule(
|
|
argument_spec={
|
|
"transport": {"type": "dict", "required": True},
|
|
"target": {"type": "str", "required": True},
|
|
"password": {"type": "str", "default": "", "no_log": True},
|
|
"admins": {"type": "list", "elements": "str", "required": True},
|
|
"exclusive": {"type": "bool", "default": True},
|
|
},
|
|
supports_check_mode=True,
|
|
)
|
|
if not HAS_MESHCORE:
|
|
module.fail_json(msg=missing_required_lib("meshcore"))
|
|
admins = [a.lower() for a in module.params["admins"]]
|
|
bad = [a for a in admins if not HEX64.match(a)]
|
|
if bad:
|
|
module.fail_json(msg=f"admins must be full 64-hex pubkeys: {bad}")
|
|
module.params["admins"] = admins
|
|
link = Link(module.params["transport"], module.params["target"], module.params["password"])
|
|
try:
|
|
result = run(work(module, link))
|
|
except LinkError as e:
|
|
module.fail_json(msg=str(e), log=link.log)
|
|
module.exit_json(log=link.log, **result)
|
|
|
|
|
|
if __name__ == "__main__":
|
|
main()
|