Skip to content

Latest commit

 

History

History
280 lines (236 loc) · 16.9 KB

MANAGER.md

File metadata and controls

280 lines (236 loc) · 16.9 KB

Installer menu, domain changes and Backup management

Download the installer to a file using the README command, then run it from an interactive terminal. Remote sessions need a TTY (ssh -t). With no arguments, first choose 1 English, 2 Русский, or 3 Exit / Выход. Invalid input repeats this question; EOF exits safely. Language selection and this Exit require no root access, downloads, network checks or system changes, including when a domain recovery journal exists. The language lasts for this invocation only and is not asked again when returning to the main menu.

The English and Russian screens share section headings, readable result blocks and 60-column ASCII separators. Color is optional: NO_COLOR, TERM=dumb and redirected output remain readable without ANSI escapes. System logs stay visible.

The main menu is 1 Installation / Установка, 2 Change Domains / Смена доменов, 3 Backups / Резервные копии, 4 Telegram Web Proxy Manager, 0 Exit / Выход. With no unfinished domain operation, opening it, Back and Exit need no root access and perform no downloads, IP lookups or system preparation. An unfinished domain journal instead requires root and verified recovery before another menu action.

Installation is the existing destructive fresh install/rebuild, with the same YES confirmation for an existing deployment. Existing explicit installation arguments run directly in English, without language selection. The former -uninstall option has been removed; it now fails with exit code 2. Without arguments and without an interactive stdin/stdout TTY, the script refuses to install. Do not pipe the script into Bash; download it to a file so prompts keep their terminal input.

Russian covers the main menus, installation questions, confirmations, warnings and result summaries. Product/protocol names, commands, paths, YES, y/N, Y/n, technical status markers and machine formats stay unchanged. System logs and internal Python/Backup/Restore/Change Domains diagnostics remain in English; user-facing explanations can accompany them. Language selection changes no installation, Backup/Restore or recovery behavior.

Backups offers Create, List and Restore. Create reports the exact archive made by that operation. Listing shows numbered entries, UTC file dates, filenames and readable sizes (KiB/MiB/GiB), without opening each archive. A listed filename is not evidence of integrity or trusted provenance. Restore accepts a list number or absolute path, shows human-readable metadata from the existing inspect result, and asks for YES before replacing managed data. Restore keeps the existing Backup v3 OS/version/architecture and recovery contracts.

Successful Installation, Change Domains and Restore finish at their result and exit to the shell. Installation ends with the credential-saving notice and, only when required, the manual reboot instruction. Create and List return to the Backups submenu; 0 Back returns to the main menu. Cancellation, EOF and invalid selections do not start another stack operation. Failed or partial operations preserve their nonzero exit status and recovery diagnostics.

Restore offers two independent options, both No by default:

  • Automatic security updates + SSH Fail2ban: one combined choice, using the existing Security helper without system DoT or initial installation. The policy permits automatic reboot at 04:38 server time, including with active users; the menu warns before asking for consent.
  • UFW with SSH protection: after Restore has added project rules, preserve an already active UFW without changing it, or enable inactive UFW only on a simple supported Ubuntu 24.04/26.04 configuration. It validates sshd, standard ssh.service/ssh.socket, actual listeners and owners, packaged UFW defaults, simple project/SSH allows and absence of other kernel firewall rules. It allows the confirmed SSH TCP ports before enabling UFW and verifies effective rules. Nonstandard SSH ports and socket activation are supported. Custom before/after files, policies, DENY/route/application rules, another firewall manager or ambiguous listeners cause refusal; rules are never deleted or reordered. The distro nftables inspection tool is installed if missing.

When either option is selected, the manager pins its exact source revision and prepares the matching helper before Restore, in a private root-owned 0700 temporary directory under /run, outside restored trees. It runs Python in isolated mode and never executes a helper from the archive or reloads mutable main afterwards. If preparation fails, explicitly choose ordinary Restore without Security or cancel.

Security starts only after the foreground Restore process has completely exited, including EXIT cleanup, with status 0. The existing operation lock remains held through all requested actions. Results show Restore, APT, Fail2ban, UFW and Overall separately. Security failure returns nonzero with Overall: PARTIAL while retaining successfully restored data; it does not trigger Restore rollback. Installed package changes are not rolled back. A possibly enabled but unverified firewall is reported FAILED_UNVERIFIED; check ufw status verbose and establish a new external SSH connection before relying on access. Interruption can leave Security state unverified and does not promise rollback.

The standalone x-ui-backup restore keeps its existing contract and does not run these optional actions. Backup v3 layout/metadata remain unchanged. Restore accepts the native AmneziaWG empty stream_settings without rewriting that value; an expected active panel must own its saved localhost web listener. Saved stopped panel state is preserved.

The standalone CLI remains available:

sudo x-ui-backup backup
sudo x-ui-backup backup --json
sudo x-ui-backup inspect /path/to/archive.tar.gz
sudo x-ui-backup restore /path/to/archive.tar.gz
sudo x-ui-backup list

inspect validates the existing archive contract without extraction, APT or service changes. It prints JSON containing only format, OS/version/architecture, creation date, panel/Xray versions, AGH presence and any saved service states. Control characters are escaped. Missing Python 3/gzip produces an error without installing packages. Validation does not authenticate who created the archive.

backup --json keeps progress on stderr and writes one successful result to stdout: {"status":"success","archive":"/exact/archive/path"}. A result-output failure returns nonzero and retains the already verified archive. Default Backup output remains human readable. Backups contain secrets; keep an off-host copy.

The menu reuses a trusted root-owned compatible installed utility offline. For an older utility it prepares and validates a replacement before atomic installation; failed download/replacement preserves the previous utility. The selected project source is pinned before downloading code, with no fallback to a different tree. Mutable main/tag downloads must match the running script (allowing only the published asset's source-default substitution), otherwise preparation stops.

Change Domains

Run the current manager from a file through an SSH TTY as root, select 2, and choose Panel, REALITY or both. The submenu shows current domains. Review the old and new names and type the exact uppercase YES. Existing installation flags continue to select Installation directly; Change Domains does not reinstall or update 3x-ui.

Point all new A/AAAA records to this VPS and keep TCP/80 reachable for Let's Encrypt HTTP-01. Domains must remain distinct from each other and Vision. Neither new domain may take the other role's current name. Unknown DNS identity, foreign/ambiguous lineages, certificate or SNI overrides, custom SQLite storage, unknown service/layout or contradictory manifest cause refusal before switching. Known local SQLite layouts are 3x-ui v3.10.2/v3.11.0 on the supported OSes.

A consistent /etc/x-ui/auto-nginx-managed.json is checked against the real inbounds, Hosts, nginx, certificates and optional components. A missing manifest is supported for an unambiguously recognized v2.1.7 project layout: standard paths, separate loopback Panel/REALITY TLS, exact project hook and stream map, matching five transport roles/Hosts and optional routes. Names/tags alone are not ownership evidence. No reinstall is needed to obtain a manifest; a successful legacy switch records installed_by=legacy-v2.1.7-layout. Other layouts/versions are deliberately refused rather than guessed.

The official archives retain UID/GID 1001:1001 on the panel directory/binary. That exact 0755 metadata is recognized only while UID 1001 has no account and no active process on the host. Ownership is preserved. An assigned/active identity or another non-root owner is refused before Backup or changes.

Before the first stack change, the selected tree's existing Backup v3 creates a full verified archive in /var/backups/x-ui. An old installed Backup utility is not replaced: a private current copy performs this archive under the inherited lock. New certificates are obtained with the existing webroot/account while old HTTP-01 routes stay available. The complete candidate nginx include tree is tested before the short x-ui stop and compare-and-set SQLite updates.

Panel changes update its public endpoints, TLS paths, managed Hosts (including the REALITY connection address), WS/gRPC metadata, AWG share address, Clash template, Diagnostics and optional AGH metadata. In the fresh HTTP/3 cover layout, Hysteria2 instead follows REALITY: REALITY changes update its Host/SNI, certificate paths and static Unix vhost; Panel-only leaves them unchanged. The previous supported Panel-bound Hysteria2 layout retains its existing role behavior without migration. Both changes share one Backup and recovery snapshot. Explicitly disabled managed inbounds keep their flags while their domain parameters update; maintenance validates listeners only for enabled known roles. IDs, client secrets/bindings, traffic, REALITY keys/shortIds/target, user settings and Vision are preserved. Existing paths are retained. Clients and old subscription URLs may need updating; an old domain is not guaranteed to work after its DNS is removed. Old certificates/lineages are never deleted by this operation.

The root-only 0700 directory /var/lib/3x-ui-auto-nginx/change-domains holds a private 0600 data journal with atomic, fsynced prepared, switching, committed phases and snapshots of only affected resources. Preparation/switch failures restore and verify the original configuration. ROLLBACK_UNVERIFIED means recovery could not be proved: retain this directory and the reported full Backup; do not delete the journal or run Installation to bypass it. Start the manager again through SSH. It checks and recovers an unfinished operation before new changes; conflicting independent edits stop recovery. Backup inspect/list remain available, while modifying Backup/Restore commands stop until manager recovery completes. No boot service or daemon is installed. A healthy committed state is retained on optional cleanup failure and is never rolled back for that reason. Prepared new lineages may remain after a failed operation; inspect dependencies before owner cleanup.

Private fixture fault/SIGKILL tests do not certify every power-loss/provider scenario. Existing Full Fresh additionally exercises P/R/Both on one installed systemd guest with real Backup, Pebble, nginx, 3x-ui/Xray and consumers. Public DNS/Let's Encrypt and a live VPS acceptance remain separate owner actions.

Operation locking

Installation, rebuild, Change Domains and the updated standalone Backup/Restore and update-hooks share a nonblocking flock. Contention returns 75 before stack changes. /run/3x-ui-auto-nginx is root-owned 0700; its regular 0600 operation.lock is never deleted to release a lock and lies outside Restore trees.

Protocol 1 uses inherited descriptor 9. A child validates its inode against the private lock file and takes flock on the same open-file description. An independent session opens a different description and cannot acquire a held lock. There is no skip-lock flag or environment override. Foreground children retain ownership through operation cleanup/rollback; the kernel releases it when the last owning descriptor closes. Do not pass descriptor 9 to unrelated daemons. Systemd-started services are launched by the service manager, not as shell children.

Helper preparation checks both capabilities and actual contention through lock-check. Identifiable already-running historical Backup/Restore/update-hooks script processes cause refusal; they are never killed. Advisory locking cannot retroactively coordinate old or third-party processes that do not use the protocol, including unidentifiable copies or processes started after the scan. Let existing maintenance finish and use the updated utility in other sessions.

On success the menu allows another action. On an operation failure it reports the original exit code and exits, allowing inspection of the reported recovery state before further changes. Exit/EOF without an operation, or after success, returns 0. Direct operation calls preserve their error status. Ctrl-C uses normal shell signal handling; it does not start another menu action.

The lightweight real Restore acceptance reuses the existing networked QEMU/SSH stand; it creates one minimal source installation and real Backup v3, restores to a clean target of the same Ubuntu version, configures Security, opens a new SSH connection from outside the VM (including socket port 2222), and checks a cold boot. Run each version once from a committed, remotely available exact HEAD:

XUI_RESTORE_ACCEPTANCE=1 XUI_TEST_DISTRO=ubuntu:24.04 bash tests/fresh/run.sh
XUI_RESTORE_ACCEPTANCE=1 XUI_TEST_DISTRO=ubuntu:26.04 bash tests/fresh/run.sh

This opt-in mode does not change the ordinary CI jobs or the default full fresh installer acceptance. It selects no Vision, AWG, AGH or client/Mihomo integration. Private archives, database digests, keys and logs stay in the disposable stand and are removed by its existing cleanup; only fixed check results are public.

Installed description

After a healthy fresh installation, /etc/x-ui/auto-nginx-managed.json describes the actual domain roles, inbound IDs and successfully configured optional components. It contains no credentials and is atomically written root:root 0600. installed_by=source@<SHA> records source provenance without claiming an unpublished project release. source_ref is the exact revision used for assets. Marker failure makes installation nonzero while retaining installed core data.

This description is included in Backup v3 under /etc/x-ui; older v3 archives without it remain valid. It is descriptive metadata, not proof of ownership and not permission to modify a restored installation without checking actual state.

Telegram Web Proxy Manager

Option 4 contacts GitHub on every launch, including when Telegram Web Proxy Manager is already installed. An existing launcher at the fixed path /usr/local/bin/telegram-web-proxy-manager must still be a root-owned regular 0755 file, not a symlink. It is not executed directly by option 4.

On first installation only, the entry point requires root, Ubuntu 24.04/26.04, the local 3X-UI database and Nginx configuration, active x-ui/nginx and successful nginx -t -q. Consent defaults to No; cancellation/EOF downloads nothing and returns to the main menu. Existing installations require root and launcher safety checks, without an additional confirmation or active-stack requirement.

The current official bootstrap is downloaded over verified HTTPS from https://raw.githubusercontent.com/xPROMSx/telegram-web-proxy-manager/main/install.sh into a private temporary directory. Download must complete successfully and the file must be nonempty before a separate Bash process executes it with default arguments. This deliberately trusts the official current GitHub main branch instead of the previous immutable bootstrap commit and SHA-256 pin. The official bootstrap owns selection of a current main SHA, provenance and compatibility checks, pair installation, locks, recovery barriers, rollback and menu launch. No --version is passed; there is no local cache or fallback to the old launcher.

If GitHub is unavailable or the bootstrap refuses/fails, option 4 reports the error and returns a nonzero status. Direct local use remains available through telegram-web-proxy-manager. Successful completion ends the 3X-UI menu session with status 0, as before. Refreshing the manager program does not automatically update the Telemt engine or initiate Universal Update.

Ordinary Telegram Manager updates need no 3X-UI PR while public interfaces stay compatible. The companion owns Telemt, TLS and its data/recovery lifecycle. No 3X-UI lock is held across this handoff; existing pending Change Domains recovery still runs before menu actions.