diff --git a/roles/coturn/meta/argument_specs.yml b/roles/coturn/meta/argument_specs.yml new file mode 100644 index 0000000..55a9b3e --- /dev/null +++ b/roles/coturn/meta/argument_specs.yml @@ -0,0 +1,148 @@ +--- +argument_specs: + main: + short_description: Deploy a coturn TURN/STUN server with optional acme.sh sidecar. + description: + - "Renders a Docker Compose stack for coturn running in + C(network_mode: host), with an optional C(acme.sh) sidecar that + issues + renews a public TLS certificate via RFC2136 / nsupdate + and restarts coturn on renewal." + - Designed to be paired with the C(digitalboard.core.talk) role + (Nextcloud Talk High Performance Backend). + options: + docker_compose_base_dir: + type: path + default: /etc/docker/compose + docker_volume_base_dir: + type: path + default: /srv/data + coturn_service_name: + type: str + default: coturn + coturn_docker_compose_dir: + type: path + coturn_docker_volume_dir: + type: path + + coturn_image: + type: str + default: "coturn/coturn:4.6.2-r5-alpine" + coturn_acme_image: + type: str + default: "neilpang/acme.sh:3.1.0" + + coturn_realm: + type: str + default: stun.example.test + description: Public DNS name used for the TURN realm and the public certificate. + coturn_internal_realm: + type: str + default: '' + description: + - Optional second DNS name issued on the same certificate, used for + split-horizon internal access (e.g. C(stun.int.example.test)). + + coturn_listening_port: + type: int + default: 3478 + description: TURN/STUN port (TCP + UDP). IANA standard is 3478. + coturn_tls_listening_port: + type: int + default: 5349 + description: TURNS port (TCP + UDP). IANA standard is 5349. + coturn_min_relay_port: + type: int + default: 49160 + coturn_max_relay_port: + type: int + default: 49200 + + coturn_external_ip: + type: str + default: '' + description: + - coturn C(--external-ip) value. Format C("PUBLIC_IP") or + C("PUBLIC_IP/PRIVATE_IP"). Must be set in host_vars for production. + coturn_listening_ip: + type: str + default: '0.0.0.0' + + coturn_static_auth_secret: + type: str + required: true + description: + - Shared secret used by the HPB signaling server to mint short-lived + TURN credentials. Default lookup reads + C(playbooks/secrets//coturn_static_auth_secret). + + coturn_extra_args: + type: list + elements: str + default: [] + description: Additional CLI flags appended verbatim to the container C(command:). + + coturn_cert_mode: + type: str + choices: [acme, file, selfsigned] + default: file + description: + - C(acme) runs an acme.sh sidecar that issues + renews via RFC2136 + and restarts coturn. C(file) assumes a certificate already lives + on the host (you manage it). C(selfsigned) generates one on first + run (vagrant/dev only). + coturn_cert_dir: + type: path + coturn_cert_file: + type: str + default: fullchain.cer + coturn_key_file: + type: str + description: Defaults to C("{{ coturn_realm }}.key"). + + coturn_acme_email: + type: str + default: admin@example.test + coturn_acme_directory: + type: str + default: https://acme-v02.api.letsencrypt.org/directory + coturn_acme_keylength: + type: str + default: ec-256 + choices: [ec-256, ec-384, '2048', '3072', '4096'] + coturn_acme_dnssleep: + type: int + default: 60 + coturn_acme_data_dir: + type: path + + coturn_acme_nsupdate_server: + type: str + default: '' + description: Authoritative nameserver acme.sh sends C(nsupdate) packets to. + coturn_acme_nsupdate_server_ip: + type: str + default: '' + description: Optional C(extra_hosts) pin (string IP) for the nsupdate server. + coturn_acme_nsupdate_zone: + type: str + default: '' + description: Delegated challenge zone (e.g. C(example._acme.example.test)). + coturn_acme_challenge_aliases: + type: list + elements: dict + default: [] + description: + - Per-name challenge alias zones (one entry per SAN). When empty, + built automatically as C({{ realm }}._acme.{{ zone-tail }}). + options: + name: + type: str + required: true + description: SAN the challenge is for. + alias: + type: str + required: true + description: CNAME target where the C(_acme-challenge) TXT lives. + coturn_acme_nsupdate_key_src: + type: path + description: Path of the TSIG key file on the controller, mounted into the acme container. diff --git a/roles/coturn/vars/main.yml b/roles/coturn/vars/main.yml index fedd529..f2a4ea3 100644 --- a/roles/coturn/vars/main.yml +++ b/roles/coturn/vars/main.yml @@ -1,3 +1,3 @@ #SPDX-License-Identifier: MIT-0 --- -# vars file for httpbin +# vars file for coturn diff --git a/roles/talk/meta/argument_specs.yml b/roles/talk/meta/argument_specs.yml new file mode 100644 index 0000000..9117ea8 --- /dev/null +++ b/roles/talk/meta/argument_specs.yml @@ -0,0 +1,161 @@ +--- +argument_specs: + main: + short_description: Deploy the Nextcloud Talk High Performance Backend (HPB) stack. + description: + - Renders a Docker Compose stack with C(nextcloud-spreed-signaling) + (Strukturag), C(janus-gateway) (canyan build) and C(nats) (internal + message broker) behind Traefik. + - Designed to be paired with the C(digitalboard.core.coturn) role + (TURN/STUN) and registered in Nextcloud via + C(digitalboard.core.nextcloud)'s C(talk.yml) task. + options: + docker_compose_base_dir: + type: path + default: /etc/docker/compose + docker_volume_base_dir: + type: path + default: /srv/data + talk_service_name: + type: str + default: signaling + talk_docker_compose_dir: + type: path + talk_docker_volume_dir: + type: path + + talk_signaling_image: + type: str + default: "strukturag/nextcloud-spreed-signaling:1.3.4" + talk_janus_image: + type: str + default: "canyan/janus-gateway:1.2.4" + talk_nats_image: + type: str + default: "nats:2.10-alpine" + + talk_traefik_network: + type: str + default: proxy + talk_internal_network: + type: str + default: hpb_internal + + talk_use_ssl: + type: bool + default: true + talk_cert_resolver: + type: str + default: dns + talk_domain: + type: str + default: signaling.example.test + description: Public domain (typically routed through the DMZ Traefik). + talk_internal_domain: + type: str + default: '' + description: + - Optional split-horizon C(*.int.*) domain for server-to-server + traffic (e.g. C(signaling.int.example.test)). + + talk_nextcloud_url: + type: str + default: https://cloud.example.test + description: Nextcloud base URL the HPB talks back to. Must be reachable from the HPB container. + talk_nextcloud_extra_host_ip: + type: str + default: '' + description: + - Pin the Nextcloud hostname to a backend IP via C(extra_hosts) to bypass + DMZ hairpin / SNI issues. Empty disables the pin. + + talk_backend_secret: + type: str + required: true + description: + - HMAC secret shared with Nextcloud Talk. Default lookup reads + C(playbooks/secrets//talk_backend_secret). + + talk_turn_secret: + type: str + required: true + description: + - Shared secret with coturn (must match C(coturn_static_auth_secret) + on the TURN host). Default lookup reads + C(playbooks/secrets//talk_turn_secret). + talk_turn_servers: + type: str + default: "turns:stun.example.test:5349?transport=tcp,turn:stun.example.test:3478" + description: + - TURN server URI list as understood by the signaling server. + Override to C(:443) when coturn binds on 443 in restrictive networks. + talk_turn_realm: + type: str + default: stun.example.test + talk_turn_apikey: + type: str + default: '' + description: Optional explicit API key; when empty a random one is generated on first run. + + talk_session_hashkey: + type: str + required: true + description: + - 32-byte hex string. Default lookup reads + C(playbooks/secrets//talk_session_hashkey). + talk_session_blockkey: + type: str + required: true + description: + - 32-byte hex string. Default lookup reads + C(playbooks/secrets//talk_session_blockkey). + + talk_mcu_type: + type: str + choices: [janus] + default: janus + talk_janus_public_ip: + type: str + default: '' + description: Must be set in host_vars. Goes into janus C(nat_1_1_mapping). + talk_janus_rtp_port_min: + type: int + default: 20000 + talk_janus_rtp_port_max: + type: int + default: 21000 + talk_janus_stun_server: + type: str + default: stun.int.example.test + description: STUN server janus uses for its own ICE candidate gathering. + talk_janus_stun_port: + type: int + default: 5349 + talk_janus_ice_lite: + type: bool + default: true + talk_janus_ice_tcp: + type: bool + default: true + + talk_trusted_proxies: + type: list + elements: str + default: + - "172.16.0.0/12" + - "192.168.0.0/16" + - "10.0.0.0/8" + talk_allowed_hosts: + type: list + elements: str + default: + - "172.16.0.0/12" + + talk_extra_hosts: + type: list + elements: str + default: [] + description: + - Extra C(host:ip) entries forwarded to all three containers. + Pre-populated with the Nextcloud pin when + C(talk_nextcloud_extra_host_ip) is set. diff --git a/roles/talk/vars/main.yml b/roles/talk/vars/main.yml index fedd529..a131766 100644 --- a/roles/talk/vars/main.yml +++ b/roles/talk/vars/main.yml @@ -1,3 +1,3 @@ #SPDX-License-Identifier: MIT-0 --- -# vars file for httpbin +# vars file for talk