Skip to content

Commit 79ab18c

Browse files
authored
Fix fresh install and pin Telemt 3.5.11 with real runtime checks
Harden fresh installation, rollback and release bootstrap; pin the audited Telemt 3.5.11 build; simplify runtime WARN handling; and add real runtime coverage for conntrack, listener, HTTP and capability behavior. Validated in GitHub Actions and by full live acceptance on Ubuntu 26.04.1 with systemd, Nginx, Let's Encrypt renewal, SOCKS/Xray egress, Telegram WEB client traffic, service restart and full VPS reboot.
1 parent 40d4ebc commit 79ab18c

29 files changed

Lines changed: 2755 additions & 656 deletions

‎.github/workflows/checks.yml‎

Lines changed: 28 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -13,18 +13,36 @@ jobs:
1313
with:
1414
persist-credentials: false
1515
- name: Install test tools
16-
run: sudo apt-get update && sudo apt-get install -y shellcheck jq nginx libnginx-mod-stream iptables
16+
run: sudo apt-get update && sudo apt-get install -y shellcheck jq nginx libnginx-mod-stream iptables nftables conntrack passwd iproute2 util-linux curl python3 openssl ca-certificates
17+
- name: Telemt conntrack dependency and default systemd runtime PATH
18+
run: |
19+
command -v conntrack
20+
systemd-path search-binaries-default
21+
env -i PATH="$(systemd-path search-binaries-default)" conntrack --version
22+
evidence="$RUNNER_TEMP/telemt-pinned-evidence"
23+
mkdir -m 0700 "$evidence"
24+
printf 'TELEMT_TEST_EVIDENCE_DIR=%s\n' "$evidence" >> "$GITHUB_ENV"
1725
- name: Bash syntax
18-
run: for file in telemt-web-manager.sh tests/*.sh; do bash -n "$file"; done
26+
run: for file in install.sh telemt-web-manager.sh tests/*.sh; do bash -n "$file"; done
1927
- name: ShellCheck
20-
run: shellcheck -x telemt-web-manager.sh tests/*.sh
21-
- name: Unit and fixture tests (no root, no production access)
22-
run: bash tests/run.sh && bash tests/fresh.sh && bash tests/download.sh
23-
- name: Published Telemt configuration contract (SHA256 verified)
24-
run: bash tests/upstream.sh
25-
- name: Version-independent compatibility, downgrade and rollback regressions
26-
run: bash tests/versions.sh && FIXTURE_VERSION=42.7.123 bash tests/fresh.sh && FIXTURE_VERSION=42.7.123 FIXTURE_INCOMPATIBLE=1 bash tests/fresh.sh
27-
- name: Actual Ubuntu nf_tables missing-chain diagnostic (isolated namespace)
28+
run: shellcheck -x install.sh telemt-web-manager.sh tests/*.sh
29+
- name: Parser/unit and fresh transaction fixtures (service/path/journal transport mocked)
30+
run: bash tests/run.sh && bash tests/fresh.sh && bash tests/fresh-rollback.sh && bash tests/download.sh && bash tests/bootstrap_versions.sh && bash tests/preflight.sh
31+
- name: Real fresh account and owned runtime-state rollback (temporary root-owned fixtures)
32+
run: sudo bash tests/fresh-account.sh
33+
- name: Pinned Telemt 3.5.11 release provenance and real config healthcheck (no runtime)
34+
run: bash tests/pinned.sh && bash tests/upstream.sh
35+
- name: Pinned Telemt 3.5.11 staging healthcheck (service/path health mocked)
36+
run: bash tests/staging.sh
37+
- name: Real Telemt 3.5.11 runtime smoke in isolated network namespace (no systemd)
38+
run: sudo env TELEMT_TEST_EVIDENCE_DIR="$TELEMT_TEST_EVIDENCE_DIR" bash tests/runtime.sh
39+
- name: Production pin equals real downloaded, staging, runtime and documented version
40+
run: bash tests/pinned.sh --versions
41+
- name: Manager bootstrap release selection, atomic pair update and rollback (temporary root-owned fixtures)
42+
run: sudo bash tests/bootstrap.sh
43+
- name: Pinned upgrade/newer-version refusal and rollback fixtures (synthetic binary/lifecycle)
44+
run: bash tests/versions.sh
45+
- name: Real nf_tables diagnostic in namespace (synthetic log bridge; no Telemt runtime)
2846
run: bash tests/conntrack.sh
2947
- name: Writable state and systemd contract
3048
run: bash tests/contracts.sh

‎README.md‎

Lines changed: 70 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -15,44 +15,29 @@ port 443 through Nginx `stream` / `ssl_preread`.
1515
- Health checks, bounded startup readiness and automatic transaction rollback.
1616
- Hardened systemd service; existing TOML preserved during updates.
1717

18-
## Installation
18+
## Quick installation
1919

20-
Run in a **root shell**, initially on a disposable test VPS.
21-
Prerequisites: Ubuntu 24.04/26.04, systemd, Bash 5+, Python 3.11+, an active
22-
recognized Nginx router and SSL, HTTP/2, realip, stream/ssl_preread modules.
23-
Install command dependencies without replacing your working Nginx:
20+
Run in a **root shell**, initially on a disposable test VPS:
2421

2522
```bash
26-
apt-get update
27-
apt-get install git shellcheck bash python3 curl ca-certificates tar openssl jq \
28-
dnsutils util-linux iproute2 coreutils passwd certbot iptables nftables
23+
bash <(curl -fsSL https://raw.githubusercontent.com/xPROMSx/telemt-web-manager/main/install.sh)
2924
```
3025

31-
Obtain and inspect the source, validate it and install both files:
32-
33-
```bash
34-
git clone https://github.com/xPROMSx/telemt-web-manager.git
35-
cd telemt-web-manager
26+
The installer installs the manager and opens its menu when stdin/stdout are a TTY.
27+
It needs Bash, curl, CA certificates and Python 3.11+; it does not install packages
28+
or change Telemt, Nginx, Certbot or Xray. Review the script first if preferred.
3629

37-
bash -n telemt-web-manager.sh
38-
shellcheck telemt-web-manager.sh
39-
40-
install -d -m 0755 /opt/telemt-web-manager/lib
41-
install -m 0755 telemt-web-manager.sh /opt/telemt-web-manager/
42-
install -m 0644 lib/safety.py /opt/telemt-web-manager/lib/
43-
```
44-
45-
Keep `/opt/telemt-web-manager` root-owned and unwritable by others.
46-
On a clean Nginx package, stream usually requires `libnginx-mod-stream`;
47-
match modules to your installed Nginx and verify `nginx -t`.
48-
The manager checks dependencies; it does not install packages or run `curl | bash`.
30+
Both program files come from one published manager release resolved to a commit.
31+
The highest stable SemVer is selected; if none exists, the highest prerelease is
32+
used. Automatic manager downgrades are refused. Testing an unpublished commit
33+
uses the advanced/manual workflow below. [Release policy and recovery](docs/OPERATIONS.md#manager-bootstrap).
4934

5035
## First run
5136

52-
Start the interactive menu:
37+
Open the menu again after installation:
5338

5439
```bash
55-
/opt/telemt-web-manager/telemt-web-manager.sh
40+
telemt-web-manager
5641
```
5742

5843
Choose Install and supply your WEB domain, public IPv4 and optional SOCKS5 address.
@@ -71,15 +56,15 @@ Replace the example domain and TEST-NET address with your own values.
7156
Direct egress:
7257

7358
```bash
74-
/opt/telemt-web-manager/telemt-web-manager.sh --install \
59+
telemt-web-manager --install \
7560
--domain proxy.example.com \
7661
--public-ip 203.0.113.10
7762
```
7863

7964
SOCKS5 egress:
8065

8166
```bash
82-
/opt/telemt-web-manager/telemt-web-manager.sh --install \
67+
telemt-web-manager --install \
8368
--domain proxy.example.com \
8469
--public-ip 203.0.113.10 \
8570
--socks 127.0.0.1:1080
@@ -92,27 +77,31 @@ agreement. An unrelated existing certificate is not automatically adopted.
9277
## Update, check and repair
9378

9479
```bash
95-
/opt/telemt-web-manager/telemt-web-manager.sh --update
96-
/opt/telemt-web-manager/telemt-web-manager.sh --check
97-
/opt/telemt-web-manager/telemt-web-manager.sh --repair
80+
telemt-web-manager --update
81+
telemt-web-manager --check
82+
telemt-web-manager --repair
9883
```
9984

100-
`--update` updates the audited **Telemt binary**, with validation and rollback;
85+
`--update` updates the **Telemt binary**, with validation and rollback;
10186
it does not update the manager or rewrite TOML.
10287
`--check` validates managed files, configuration, renewal state and service health.
10388
`--repair` restarts/reloads only verified managed services, without reconstructing
104-
changed files. To update the manager, review a newer checkout and repeat the
105-
validation/copy steps above.
89+
changed files. To update the manager itself, rerun the quick installation command.
90+
This preserves the existing Telemt deployment.
10691

107-
## Intended environment
92+
## Requirements and supported environment
10893

109-
Ubuntu 24.04/26.04 on x86_64 or aarch64, with one recognized Nginx SNI map/router,
94+
Ubuntu 24.04/26.04, systemd, Bash 5+, Python 3.11+, active Nginx with SSL, HTTP/2,
95+
realip and stream/ssl_preread modules. x86_64 or aarch64, one recognized Nginx SNI map/router,
11096
IPv4 `:443`, optional existing `[::]:443`, outgoing PROXY protocol and an HTTP
11197
`conf.d/*.conf` include. The manager adds a loopback TLS frontend and an IPv4-only
11298
Telemt WEB listener. Telegram egress is direct or unauthenticated SOCKS5.
113-
Source-audited baseline: **3.5.9**; official 3.5.7/3.5.9 configuration tests are retained.
114-
Stable releases are evaluated against explicit configuration/runtime health contracts;
115-
incompatible candidates are refused or rolled back, without a version-number gate.
99+
Supported Telemt: **3.5.11**. Fresh installs and updates use only this reviewed
100+
release and embedded official SHA256 values. Older managed installs must pass
101+
compatibility checks; newer installs are never downgraded. Supporting a future
102+
release requires a new reviewed manager version. `--check` reports installed and
103+
supported versions locally. WARN is diagnostic; genuine ERROR/FATAL/panic and
104+
failed objective health checks cause failure. [CI coverage](docs/CI-COVERAGE.md).
116105

117106
HTTP-01 uses standalone on free port 80, or a persistent managed webroot when
118107
port 80 belongs to the recognized Nginx redirect topology. Nginx is never stopped.
@@ -132,9 +121,49 @@ are not automatically supported. Xray and 3x-ui configuration/database are not m
132121
CI uses the verified official Telemt binary and real Nginx traffic tests.
133122
Systemd and Certbot lifecycle operations use mocks. Live VPS acceptance is still required.
134123

124+
The enabled conntrack-control contract requires the Ubuntu `conntrack` package,
125+
iptables/ip6tables/nft and CAP_NET_ADMIN. Preflight checks `conntrack` on both
126+
the root shell PATH and systemd's default runtime PATH before installation work;
127+
the manager does not install missing packages.
128+
129+
## Advanced / manual installation
130+
131+
Review a trusted checkout (or the PR checkout during acceptance) and install both
132+
files. This path does not install the convenient launcher:
133+
134+
```bash
135+
git clone https://github.com/xPROMSx/telemt-web-manager.git
136+
cd telemt-web-manager
137+
bash -n telemt-web-manager.sh
138+
shellcheck telemt-web-manager.sh
139+
install -d -m 0755 /opt/telemt-web-manager/lib
140+
install -m 0755 telemt-web-manager.sh /opt/telemt-web-manager/
141+
install -m 0644 lib/safety.py /opt/telemt-web-manager/lib/
142+
/opt/telemt-web-manager/telemt-web-manager.sh
143+
```
144+
145+
Keep the installation root-owned and unwritable by others. Install missing
146+
manager dependencies deliberately, without replacing the working Nginx stack:
147+
148+
```bash
149+
apt-get update
150+
apt-get install git shellcheck bash python3 curl ca-certificates tar openssl jq \
151+
dnsutils util-linux iproute2 coreutils passwd certbot iptables nftables conntrack
152+
```
153+
154+
On a clean package Nginx, stream usually needs `libnginx-mod-stream`; match modules
155+
to the installed Nginx and verify `nginx -t`. The manager checks dependencies.
156+
Bootstrap options: `--version v0.1.0` selects a published release; `--no-start`
157+
suppresses the menu. See [operations](docs/OPERATIONS.md#manager-bootstrap).
158+
159+
## Technical documentation
160+
161+
- [Upstream audit and version/configuration contracts](docs/UPSTREAM.md).
162+
- [Architecture, security, ACME recovery, tests and operations](docs/OPERATIONS.md).
163+
135164
## Important limitations
136165

137-
- Unknown Nginx topology, changed managed contracts and unaudited versions fail closed.
166+
- Unknown Nginx topology or incompatible/changed managed runtime contracts fail closed.
138167
- Unrelated existing Telemt installations and certificates require manual review.
139168
- No firewall/UFW changes, automatic TOML migrations or automatic uninstall.
140169
- WEB AAAA, authenticated/IPv6 SOCKS and custom HTTP-80 routing require manual review.
@@ -143,11 +172,6 @@ Systemd and Certbot lifecycle operations use mocks. Live VPS acceptance is still
143172
- SIGINT/TERM/HUP trigger transactional rollback. Power loss, SIGKILL, disk failure
144173
and concurrent root edits remain manual recovery boundaries.
145174

146-
## Technical documentation
147-
148-
- [Upstream audit and version/configuration contracts](docs/UPSTREAM.md).
149-
- [Architecture, security, ACME recovery, tests and operations](docs/OPERATIONS.md).
150-
151175
## License and independence
152176

153177
[MIT License](LICENSE). Independent project, not affiliated with, endorsed by,

0 commit comments

Comments
 (0)