threexui

• 1: Ansible
• 2: OpenSpec
• 2.1: Specifications
• 2.1.1: Infra threexui
• 2.1.1.1: Infrastructure 3x-ui
• 2.1.2: Owned dns
• 2.1.2.1: owned-dns Specification
• 3: sub
• 4: Tf
• 5: Tf setup

bazel run //infra/threexui:fix_subs -- --hosts njalla1.nodes.threexui.alwaldend.com,yc1.nodes.threexui.alwaldend.com --sub_id subid

bazel run //infra/threexui:fix_subs -- --sub_file path_to_file

1 - Ansible

2 - OpenSpec

2.1 - Specifications

2.1.1 - Infra threexui

2.1.1.1 - Infrastructure 3x-ui

Purpose

Describe 3x-ui provisioning, host deployment, node routing configuration, and the subscription URL transformer. This baseline describes checked-in source, not verified live node access. The advertised host-only subscription command has a source limitation: sub/main.go also attempts to read sub_file when it is empty, so successful host-only operation is not a baseline guarantee.

Baseline source revision: 550d7e79b1f5fdbc2b6017b75178471d6914082f. Observation date: 2026-09-08. Sources are linked in full; no excerpts are used.

Sources: component documentation, root wrappers, provisioning package, configuration package, host playbook, Traefik routes, node definitions, node inbounds, node routing, and subscription transformer.

Requirements

Requirement: Separate provisioning, deployment, and service configuration

The package SHALL keep infrastructure creation in tf_setup, host deployment in Ansible, and 3x-ui API resources in tf. The deployment playbook SHALL apply host, Traefik, and 3x-ui roles to the control-plane and data-plane inventory groups.

Scenario: Select a 3x-ui workflow

• WHEN an authorized operator selects the setup or main Terraform wrapper
• THEN its AL plugin selects the corresponding Terraform stage
• AND the Ansible playbook remains the owner of host and service installation

Requirement: Terminate proxy traffic at the declared local services

The Traefik route template SHALL forward the panel to loopback port 2053 and subscription requests to loopback port 2096. It SHALL define HTTP inbound routes for ports 40000 through 40149 and TCP inbound routes for ports 40150 through 40299, forwarding to corresponding loopback ports.

Scenario: Render a subscription route

• WHEN the checked-in dynamic Traefik template is rendered
• THEN requests matching the configured subscription path prefix route to http://127.0.0.1:2096
• AND the router selects the configured TLS certificate resolver

Requirement: Declare explicit node and outbound routing relationships

Terraform SHALL configure the njalla1 and yc1 nodes through the shared node module. The node routing declaration SHALL block the advertising category and private IP destinations before routing the freedom inbound directly and each mullvad_min or http_proxy inbound through its named WireGuard outbound. The enabled mullvad_min_lb inbound has no active dedicated balancing rule; commented balancing rules SHALL NOT be treated as enabled routing behavior.

Scenario: Inspect a configured Mullvad inbound route

• WHEN a node’s selected relay creates a Mullvad inbound
• THEN the inbound listens on loopback
• AND its routing rule selects the matching out-mullvad-min- outbound tag
• AND the node declaration supplies its own relay selection to the module

Requirement: Normalize subscription URLs from readable inputs

For readable local subscription files, the transformer SHALL ignore blank and comment lines, parse each remaining URL, set security=tls and sni to the URL hostname, sort URLs by fragment, and write one URL per output line. It SHALL return a nonzero exit status when input reading or URL parsing fails.

Scenario: Transform a local subscription file

• WHEN fix_subs receives a readable --sub_file containing subscription URLs
• THEN output URL queries contain security=tls and the matching hostname SNI
• AND output is ordered by URL fragment with blank and comment lines omitted

2.1.2 - Owned dns

2.1.2.1 - owned-dns Specification

Purpose

Define retained 3x-ui DNS ownership through the owner’s tf_setup root, including canonical declarations, scoped execution, and offline source checks.

Requirements

Requirement: Owner-local DNS configuration

The tf_setup root SHALL consume this owner’s canonical dnsconfig.json through the shared DNS Terraform module, preserving declared record identities and views. DNS resources SHALL default to disabled before the adoption revision and SHALL retain enabled ownership after authorized adoption into the owner’s state. Reconciliation against adopted state and unchanged declarations SHALL propose no record additions, changes, replacements, or deletions.

Scenario: Inspect the preparatory configuration

• WHEN the preparatory root is evaluated with default inputs before its adoption revision
• THEN it reads this owner’s declaration and disables managed DNS records
• AND the package contains the module and declaration inputs

Scenario: Inspect adopted source defaults

• WHEN the adopted root is evaluated with its checked-in default inputs
• THEN DNS ownership is enabled and the root reads the canonical declaration
• AND the package contains the module and declaration inputs

Scenario: Adopt existing DNS records

• WHEN authorized adoption coordinates the previous writers and enables this owner’s record ownership
• THEN the owner imports existing provider identities into its own state through the owning scoped DNS wrappers and reviewed saved-plan import blocks
• AND existing record values and declared DNS views are preserved

Scenario: Reconcile adopted DNS records

• WHEN the owner plans against its adopted state and unchanged declarations
• THEN it proposes no record additions, changes, replacements, or deletions
• AND unrelated records remain unchanged

Requirement: Scoped DNS execution and offline checks

The DNS wrappers SHALL select src_infra_threexui through the repository AL flow and keep secret values in injected variables. dns.plan, dns.show, and dns.apply SHALL retain the owning root and backend, select dns=1, and scope planning to module.dns. Apply SHALL require the reviewed saved plan. This workflow SHALL preserve ordinary service authentication and SHALL NOT establish overall service health. Required DNS credentials and Vault grants SHALL remain operational prerequisites, and RouterOS DNS credentials SHALL remain isolated from unrelated RouterOS resources. The package SHALL expose a format test without Vault authentication or DNS provider access.

Scenario: Validate the Terraform source

• WHEN the package format test executes
• THEN it checks the packaged Terraform configuration without live credentials
• AND existing non-DNS authentication and backend paths remain unchanged

Scenario: Prepare an operational Terraform invocation

• WHEN the operator selects the owning DNS wrappers
• THEN they select DNS credential injection through the owner AppRole with dns=1
• AND their scoped plan validates DNS and its dependencies
• AND disabled DNS resources do not imply offline provider configuration

3 - sub

4 - Tf

5 - Tf setup

Use this package’s dns.plan, dns.show, and dns.apply targets for the scoped DNS adoption workflow.

DNS ownership is enabled by default after the verified 2026-09-13 adoption. The adoption evidence records 12 imports, a no-change follow-up plan, and preserved provider inventories. The DNS wrappers select dns=1 and module.dns within this setup root and backend; their validation covers DNS and its dependencies. Apply requires a reviewed saved plan, and ordinary service authentication remains separate.