GOST Manager

GOST Manager is a menu-based Bash project for installing GOST v3 and managing numbered Iran/Kharej Direct Mode tunnels with systemd on Ubuntu servers.

Direct Mode is the only supported traffic mode in GOST Manager v2.0.3. The project installs the official go-gost/gost release artifact unchanged; GOST Manager is only an installer, configuration, and service wrapper and does not alter upstream protocol behavior. Multiple independent Iran and Kharej profiles are supported.

NGINX Gateway and Native GOST Gateway are cancelled. There is no placeholder, hidden command, route runtime, controller, failover layer, or NGINX dependency. Direct Mode profile management supports safe create, inspect, edit, clone, restart, and delete operations without changing the independent-process traffic architecture.

Supported OS

• Ubuntu 22.04 LTS
• Ubuntu 24.04 LTS

Supported Architectures

• x86_64 / amd64
• aarch64 / arm64

Installation

Run the public setup command from a root shell. It selects the latest stable GitHub Release, verifies its SHA256 checksum, validates the archive, runs the local transactional installer, and keeps the verified source at /opt/GOST-Manager:

bash <(curl -fsSL https://raw.githubusercontent.com/WikiPanel/GOST-Manager/main/setup.sh)

This default is equivalent to selecting GOST_MANAGER_VERSION=latest. Setup accepts both a regular /etc/os-release file and Ubuntu's standard symlink to /usr/lib/os-release; OS metadata is resolved within those trusted paths and parsed as data before any download begins.

Pin an exact release with either v2.0.3 or 2.0.3:

GOST_MANAGER_VERSION=v2.0.3 \
bash <(curl -fsSL https://raw.githubusercontent.com/WikiPanel/GOST-Manager/main/setup.sh)

Upgrade safely by rerunning the latest setup command. Same-version setup is idempotent. Check or launch the installed manager with:

gost-manager --version
gost-manager

setup.sh is the small online release selector, downloader, checksum verifier, archive validator, and /opt/GOST-Manager updater. install.sh is the local transactional installer inside the verified release; it does not download the GOST Manager application. The raw setup script is therefore not the complete payload: release contents are saved to disk and checksum-verified before any downloaded script is executed. Release assets and checksums come from the official WikiPanel/GOST-Manager GitHub Releases page over HTTPS.

Manual Git installation remains available as a fallback:

apt-get update
apt-get install -y git ca-certificates curl
git clone --depth 1 https://github.com/WikiPanel/GOST-Manager.git /opt/GOST-Manager
cd /opt/GOST-Manager
bash install.sh --install-dependencies
gost-manager

The local installer copies:

• gost-manager.sh to /usr/local/sbin/gost-manager
• VERSION to /usr/local/lib/gost-manager/VERSION
• lib/gost-run-iran.sh to /usr/local/lib/gost-manager/gost-run-iran.sh
• lib/gost-run-kharej.sh to /usr/local/lib/gost-manager/gost-run-kharej.sh
• the complete monitoring package to /usr/local/lib/gost-manager/monitoring
• gost-monitor, gost-monitor-collector, and gost-monitor-admin to /usr/local/sbin
• /etc/gost-manager/monitoring.env
• /etc/systemd/system/gost-monitor-collector.service
• monitoring history to /var/lib/gost-manager/metrics.sqlite3
• the central Upstream Watchdog runtime and admin launchers to /usr/local/sbin
• /etc/gost-manager/watchdog.conf, /etc/gost-manager/watchdog.d/, and /var/lib/gost-manager/watchdog/
• /etc/systemd/system/gost-upstream-watchdog.service

The monitoring collector is enabled and started on a fresh install. Upgrades preserve a valid operator-modified monitoring config, monitoring history, Watchdog configuration/history/manual override, and the collector's enabled/active state. They never rewrite existing profile check modes or perform a GOST traffic service action. Deterministic upgrade fixtures cover both v2.0.1 and v2.0.2 as previous versions. They preserve /etc/gost/, /etc/gost-manager/, /var/lib/gost-manager/, numbered Iran/Kharej units and drop-ins under /etc/systemd/system/, and /etc/sysctl.d/99-gost-stability.conf. Existing traffic service PIDs, restart counts, enabled state, and active state are not intentionally changed.

The installer copies only modules listed in packaging/monitoring-runtime-manifest.txt. Existing shared /usr/local/sbin and /etc/systemd/system metadata is preserved, as is existing /etc/gost ownership, mode, content, and file metadata. Private manager directories are enforced and their prior metadata is restored if a later installation phase fails.

Direct source execution also works:

sudo bash gost-manager.sh --version
sudo bash gost-manager.sh

Install or Update GOST

Choose:

1) Install / Update GOST

The manager downloads from official go-gost/gost GitHub Releases only. It ignores prereleases, detects amd64 or arm64, avoids amd64v3, downloads a checksum file when available, verifies SHA256 when possible, backs up an existing binary as /usr/local/bin/gost.bak.<timestamp>, installs /usr/local/bin/gost, and prints:

/usr/local/bin/gost -V

Kharej Tunnel Example

On the Kharej server, choose:

2) Create Kharej tunnel

Example inputs:

Kharej profile number [1]:
Profile label (optional): kharej-edge
SOCKS listen port: 28420
GOST username: maya
GOST password: [hidden and confirmed]
Allowed Iran IPv4/CIDRs: 198.51.100.10,198.51.100.11/32
Apply profile-scoped iptables firewall rules? yes

This creates:

/etc/gost/kharej-1.env
/etc/systemd/system/gost-kharej-1.service

The service runs a SOCKS5 listener on 0.0.0.0:28420.

Iran Tunnel Example: 2052

On the Iran server, choose:

3) Create Iran tunnel

Example inputs:

Iran profile number [1]:
Profile label (optional): iran-edge
Kharej IP: 203.0.113.20
Kharej SOCKS port: 28420
GOST username: maya
GOST password: [hidden matching value]
Port mappings: 2052:2052

Port mappings is required for every Iran tunnel. Empty values, invalid formats, invalid ports, and duplicate Iran listen ports are rejected before any files are written.

Traffic flow:

Iran :2052 -> gost-iran-1 -> Kharej :28420 SOCKS5 -> Kharej 127.0.0.1:2052

Iran Tunnel Example: 80/8080/8880

Use:

Port mappings: 80:80,8080:8080,8880:8880

Traffic flow:

Iran :80   -> Kharej 127.0.0.1:80
Iran :8080 -> Kharej 127.0.0.1:8080
Iran :8880 -> Kharej 127.0.0.1:8880

GOST listens directly on the public Iran ports. Nginx is not placed in the tunnel path.

Operations

Run:

sudo gost-manager

Use the menu:

1) Install / Update GOST
2) Create Kharej tunnel
3) Create Iran tunnel
4) Delete tunnel
5) Show status
6) Show logs
7) Restart tunnel
8) List active GOST services
9) Clean old/broken GOST configs
10) Monitoring
11) Server Stability
12) Upstream Watchdog
0) Exit

For delete, status, logs, and restart, the manager now shows a numbered tunnel selector. You no longer need to type iran or kharej manually.

Available GOST tunnels:

1) gost-iran-1.service      active/running    /etc/gost/iran-1.env
2) gost-kharej-1.service    active/running    /etc/gost/kharej-1.env

Select tunnel number:

Each numbered tunnel is independent. Deleting iran-2 does not affect iran-1; deleting kharej-2 does not affect kharej-1.

Option 8 first renders every discovered profile and then opens:

Direct Mode profiles
====================

1) List all profiles
2) Show profile detail
3) Edit a profile
4) Clone a profile
5) Restart selected profiles
6) Restart all profiles
0) Back

Iran and Kharej use independent positive-number spaces. Creation and clone suggest the first gap found across both env and unit files, so an orphaned file is never overwritten. PROFILE_LABEL is optional display metadata; the stable identity, filename, and service remain side-number. Existing unlabeled profiles remain valid.

Create, edit, and clone validate configured local ports across both sides and take one live ss snapshot before activating a new port. Edit preserves unknown well-formed env keys and existing credentials unless explicitly replaced, shows a redacted diff, and performs no write or restart for a no-op. Clone never changes its source. Selected restart accepts exact comma-separated IDs, deduplicates them, and never uses a wildcard service command.

Server Stability

Option 11 runs one automatic operational wizard. It reports current kernel values, installs the managed file /etc/sysctl.d/99-gost-stability.conf, applies it with sysctl --system, and verifies every recommended value. The managed settings cover file capacity, socket backlog, the local port range, SYN backlog, FIN timeout, TCP keepalive, and slow-start-after-idle. The wizard intentionally does not set net.ipv4.tcp_tw_reuse.

For each exact existing gost-iran-N.service or gost-kharej-N.service, it installs /etc/systemd/system/<service>.d/stability.conf with LimitNOFILE=1048576, TasksMax=infinity, OOMScoreAdjust=-500, Restart=always, and RestartSec=3. Unrelated services and the original units/env files are not changed. At most one systemctl daemon-reload is run when drop-ins change, and no GOST service is restarted. New process limits therefore apply after the operator's next normal service restart.

The wizard is idempotent: an already optimized host receives no unnecessary file replacement, sysctl apply, or daemon reload. Symlinked or conflicting unmanaged destinations are rejected rather than overwritten. Existing managed stability files are backed up before an update.

Local Monitoring

Option 10 opens the compact Monitoring Lite workflow:

1) Live resources
2) Last 10 minutes
3) Last 30 minutes
4) Last 1 hour
5) Services and tunnels
6) Collector status
7) Advanced tools
0) Back

The normal live view focuses on host, network, TCP connections, Direct Mode GOST services, tunnels, and collector health. Monitoring is local and optional, has no NGINX dependency, and never enters the traffic path. Existing snapshot/detail/event/export/maintenance/service-control commands remain available under Advanced tools. Monitoring command failures return to the manager menu and never trigger traffic service actions.

Conntrack monitoring is also optional. Hosts without both conntrack sysctl files report conntrack: unsupported; this does not increase source-error counters or degrade otherwise healthy observations. A partial, unreadable, or malformed conntrack source remains a real collection failure. The collector never loads a kernel module to change host capability.

Direct commands are also available:

systemctl status gost-monitor-collector.service
systemctl start gost-monitor-collector.service
systemctl stop gost-monitor-collector.service
systemctl restart gost-monitor-collector.service

gost-monitor snapshot
gost-monitor live
gost-monitor summary --window 10m
gost-monitor-admin status
gost-monitor-admin maintenance

The strict root-owned mode-0600 config contains only:

GOST_MONITOR_DB=/var/lib/gost-manager/metrics.sqlite3
GOST_ENV_DIR=/etc/gost
GOST_MONITOR_SAMPLE_INTERVAL=20
GOST_MONITOR_TCP_INTERVAL=60
GOST_MONITOR_SLOW_INTERVAL=120
GOST_MONITOR_MAINTENANCE_INTERVAL=1800
GOST_MONITOR_LOAD_SHEDDING=1

Bounds are sample 5..60 seconds; TCP 10..300 and not below sample; slow 30..900 and not below sample; maintenance 300..86400 and not below slow. The file is parsed as strict KEY=VALUE data and is never sourced or executed. Unknown/duplicate keys, relative paths, shell substitutions, unsafe quoting, and invalid cadence combinations are rejected before collection starts.

The generic parser used by library tests accepts safe absolute paths. The installed service has a narrower policy: GOST_MONITOR_DB must name a file below /var/lib/gost-manager and GOST_ENV_DIR must be /etc/gost or a descendant. Alternate names such as /var/lib/gost-manager/custom.sqlite3 and nested paths such as /var/lib/gost-manager/archive/current.sqlite3 are supported; /srv, /root, /tmp, prefix lookalikes, and symlink traversal are rejected. Inspect only the validated non-secret fields with:

gost-monitor-admin config --format json
gost-monitor-admin config --format value --field database_path

Existing config files are preserved byte-for-byte on upgrade. For an explicit operator change, Advanced tools offers the high-traffic preset. The equivalent CLI shows current/updated values, validates and backs up the mode-0600 file, writes atomically with fsync, rejects unsafe paths, and restarts only the collector when the flag is present:

gost-monitor-admin config
gost-monitor-admin apply-preset high-traffic --restart-collector

SQLite remains the dependency-free, restart-safe local history store. Monitoring Lite retains 6 hours of raw points, 24 hours of minute rollups, and 24 hours of structured events. At the new 20/60/120-second cadences, the deterministic six-service model produces 1,738,080 points/day, 434,520 retained raw rows, and 783,360 rollup rows. Its conservative total is about 0.312 GiB including auxiliary rows, indexes, reusable pages, WAL, and operational headroom; reserve at least 1 GiB. gost-monitor-admin maintenance runs bounded rollup/retention in one transaction and checkpoints after commit.

Fast cycles collect core CPU, memory, load, service state, and process identity. Full socket/network work runs every 60 seconds; FD, cgroup, filesystem, and other expensive work runs every 120 seconds. One full socket snapshot is shared per due cycle. If a collection misses its deadline, observable load shedding keeps Fast metrics running, defers heavy work, and restores it after three on-time cycles. Entry, overrun, and recovery events are transition-bounded.

The deterministic 1,000-user fixture validates monitoring parsing, attribution, storage, and scheduling overhead; it is not a network-capacity claim. Production throughput still depends on CPU, kernel, NIC, encryption, GOST, RTT, CDN, and the server provider.

The daemon, one-shot collector, and destructive history purge share the private advisory lock /run/gost-manager/collector.lock. A second collector or a direct purge while collection is active returns exit code 4. The manager asks before temporarily stopping an active collector for one-shot diagnostics and restores it after success, failure, or interrupt. History deletion requires the exact phrase DELETE MONITORING HISTORY, resolves and displays the configured database, checkpoints WAL, refuses a busy checkpoint, creates same-directory hard-link recovery anchors, performs one atomic canonical replacement, fsyncs durability boundaries, and restores the original DB and sidecars after an injected failure. It does not touch traffic or /etc/gost.

The collector service has bounded restart behavior, low CPU/I/O priority, private state permissions, and no Requires=, PartOf=, BindsTo=, stop, restart, or reload relationship with GOST tunnel services. Collector failure, corrupt history, maintenance failure, or monitoring removal cannot stop Direct Mode traffic.

Upstream Watchdog

Option 12 opens the central per-profile Iran Upstream Watchdog. Every profile starts in Disabled; operators can select Monitor Only or Auto Protect independently. Health checks can be ping or tcp; Ping remains the default for fresh and upgraded profiles. The exact defaults are a 2-second interval, 1-second probe timeout, 10 failures before stop, 10 successes before recovery, a 10-second hold, and 0-10 seconds of jitter. Auto Protect stops only its exact active Iran service and auto-starts only a service whose stop it previously verified and owned. Manual stops, manual overrides, and maintenance are never silently reversed.

One central daemon shares checks only when mode, Kharej IP, TCP port where applicable, and timeout all match. TCP mode strictly reads only KHAREJ_IP and TUNNEL_PORT; it never retains credential or mapping values. Local execution, resource, and invalid-target failures are reported as deduplicated probe_error transitions; they never count as upstream failures or cause a traffic action. Manual service reconciliation runs every 10 seconds, while each actual action uses a fresh exact-unit query and durable action intent. Installation and update enable that daemon but leave all profiles Disabled and never restart, stop, or start a GOST traffic service. A successful Ping proves host reachability. A successful TCP connect proves only that the configured port accepts a connection; neither proves SOCKS authentication or forwarding. Change one profile without restarting GOST using gost-watchdog-admin set-check-mode iran-N tcp, and roll back with the same command ending in ping. The change never clears manual override. See Upstream Watchdog v1 for configuration, rollout, maintenance, recovery ownership, limitations, and rollback. The operator-only GM-203 production runbook covers pinned upgrade, zero-traffic verification, controlled tests, soak, and rollback.

Safe Uninstall

Run sudo bash uninstall.sh. Every component defaults to No and is confirmed independently: manager CLI, monitoring components, Watchdog service/runtime/data, managed traffic services, /etc/gost credentials/backups, and the GOST binary. Watchdog configuration and history are preserved unless the operator confirms their explicit purge. A final plan is shown before changes.

Removing monitoring only leaves tunnel units, active traffic, runners, /etc/gost, the GOST binary, firewall state, and unrelated host services unchanged. History and config are separate choices. Monitoring code cannot be removed while its service remains; runners are retained while managed traffic units remain. If history/config are retained, a later sudo bash install.sh restores the monitoring code and validates/migrates the retained database.

Removal decisions are rechecked against actual post-action state. If any exact managed traffic unit survives, both runners, /etc/gost, and /usr/local/bin/gost are preserved even when deletion was selected. If the collector is active, enabled, or loaded despite a missing unit file, removal still attempts to stop/disable it; a failure preserves monitoring code, launchers, config, and history. History removal uses the configured DB captured before optional config deletion and never guesses the default path.

Linux systemd verification

tests/test-systemd-linux.sh uses the host's real systemd-analyze verify environment and temporary executable/config paths. tests/test-watchdog-linux.sh also runs a hardened transient Watchdog unit, local Ping/TCP and AF_UNIX checks, and a ten-profile process-rate benchmark without enabling Auto Protect for a real traffic service. The Ubuntu 22.04/24.04 workflow runs both validations.

If installer service-state rollback cannot be verified, it retains collision-resistant backup directories and prints exact rm, cp -a, systemctl daemon-reload, enable/disable, start/stop, and status commands for restoring the recorded collector state. Do not delete those backups until the printed status check succeeds.

Firewall Notes

The Kharej SOCKS5 listener must not be public. Enable the optional firewall rule so only the configured Iran IPv4 sources can reach the SOCKS port. New profiles use ALLOWED_IRAN_SOURCES with up to 64 canonical IPv4 /8 through /32 networks; plain addresses become /32. Legacy IRAN_IP profiles remain valid and are not rewritten during listing or upgrade.

The manager uses iptables comments:

gost-manager:kharej-<number>:allow
gost-manager:kharej-<number>:drop

Each canonical source receives one ACCEPT rule before the profile's final DROP rule. These comments let edit, rollback, and deletion mutate only the matching profile rules; unrelated rules and other profiles remain untouched.

Warning: iptables rules are not persistent by default. They may be lost after reboot unless saved with netfilter-persistent or your server firewall system.

Security Notes

• Real passwords belong only in /etc/gost/*.env.
• Password input is hidden and confirmed; list, detail, status, summaries, and failures never print credentials.
• Env files are installed with permission 600.
• Env replacement uses a private same-directory temporary file and atomic replacement; unit files remain 0644.
• /etc/gost is installed with permission 700.
• Do not commit real passwords, production IPs, tokens, or private credentials.
• The manager does not use eval.
• Keep the Kharej SOCKS port firewalled.

Troubleshooting

• If a local port is configured by another profile or occupied live, the manager prints a bounded profile/PID ownership summary and does not create files. Unknown ownership is treated as a conflict.
• If a systemd service fails, use menu option 5 for status and option 6 for logs.
• If a tunnel was partially removed, use menu option 9 to find managed orphan env files, service files, failed services, and old backups.
• If GOST install fails, verify outbound HTTPS access to github.com and api.github.com.