Files
tthandClaude Opus 5.5 0a4cfafc78
ci / test (push) Successful in 2m39s
tth.meshcore: MeshCore repeaters as code, over RF
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>
2026-11-03 02:23:24 +01:00

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()