hashem

command module

v1.3.9 Latest Latest Go to latest Published: Sep 24, 2026 License: AGPL-3.0 Imports: 25 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/pdnczone/hashem

Links

Open Source Insights

README ¶

Hashem Tunnel

Advanced layered tunneling & multi-protocol reverse proxy infrastructure

English · فارسی

📖 Overview

Hashem Tunnel is a single-binary, Go-based management engine for building and operating network tunnels between servers — with a real-time Web UI, a Telegram bot, and an interactive TUI.

Its signature capability is the Stacked Architecture: an FRP reverse proxy carried inside a GRE transport layer, so forwarded traffic never touches a public interface and is invisible to outside scanners. Alongside the stack, Hashem manages plain GRE, FRP, GOST, and pooled direct carrier tunnels (TCP, UDP, KCP, QUIC, WSS) with live ping gauges, per-tunnel telemetry, and a boot-persistent restore layer.

🚀 Key Features

Stacked tunnels (GRE + FRP Reverse) — FRP traffic encapsulated inside a GRE transport for isolated, zero-leak routing. The backend runs a per-tunnel state machine (GRE_FAILED, FRP_FAILED, …) that stops at the exact broken layer.
Direct carriers — TCP, TCP Mux, TCP+Stealth, TCP+PCK, UDP, KCP+FEC, QUIC, WS/WSS (with mux): connection pooling, rate limiting, and health failover.
Real-time telemetry — SVG ping gauge (green ≤ 50 ms, amber ≤ 150 ms, red beyond), packet-loss bar, per-tunnel up/down speed and traffic totals.
Live Web UI — dark-mode panel with an interactive tunnel wizard, node picker, logs, metrics and maintenance screens; installable as a PWA.
Telegram bot — read-only and admin roles, tunnel notifications and remote control from chat.
Self-managing processes — FRP runs under a pidfile-reconciled supervisor with automatic restart and backoff; GRE tunnels survive reboots via a systemd restore unit.
Self-update with rollback — hashem update checks GitHub releases, verifies SHA256SUMS, and rolls back on failure.
Zero-leak by design — internal traffic bound to tunnel interfaces; no tokens or private keys exposed to the frontend.

🏗️ Architecture Options

1. GRE + FRP Stacked (recommended for filtered environments)

[Client / Private Network]
          │
      GRE Tunnel  (10.0.0.1/30 ── 10.0.0.2/30)
          │
          ▼
[FRP Reverse Proxy]  (bound strictly to the GRE inner interface)
          │
          ▼
[Destination Service]

2. Direct carriers (TCP / UDP / KCP / QUIC / WSS)

[Origin] ──── Pooled carrier session (multiplexed / TLS / WSS) ──── [Target]

Choosing a direction

Reverse (kharej dials Iran) — the usual choice; try this first. The Iran side exposes forwarded ports, kharej connects out.
Direct (Iran dials kharej) — when inbound connections to Iran do not get through (restrictive firewalls), the Iran server dials out instead.

Transport families

Family	Variants	Best for
TCP	TCP, TCP Mux, TCP+Stealth, TCP+PCK	Reliable default; Stealth for heavy filtering; PCK where TCP flows are reset (Linux, root)
UDP	UDP, KCP+FEC, QUIC	Lower latency; KCP for gaming; QUIC for lossy links
WebSocket	WS, WS Mux, WSS, WSS Mux	Camouflaged as web traffic; CDN friendly
Stacked / native	GRE+FRP, GRE, FRP, GOST	Zero-leak forwarding; plain GRE or FRP when the stack is not needed

⚙️ Installation

Requirements: Linux (amd64, arm64, 386, s390x, or arm v5/v6/v7) with root access. iproute2 and the frp binaries are fetched automatically if missing.

curl -fsSL https://raw.githubusercontent.com/pdnczone/hashem/main/install.sh | bash

The installer picks the right release asset for your machine, verifies its checksum, and starts the service. On the second server, install the same way and connect the two from either panel.

Keeping it up to date

hashem update          # check and install the latest release, with rollback

🔐 Web Panel Credentials

The panel ships with username admin and a randomly generated password printed during installation.

hashem user                     # view current credentials
hashem user admin MyPass123     # set username and password
hashem password NewPass456      # set password only
hashem                          # interactive menu → Web Panel

Server token: if no tunnel token is configured, the engine falls back to a well-known default and logs a warning on every start. Always set a real token before exposing a server.

🛡️ Security Notes

Put the Web UI behind HTTPS (Nginx/Caddy reverse proxy) in production.
The engine never exposes tokens or private keys to the frontend; credentials set via hashem user are stored server-side only.
GRE tunnel state is kernel state — Hashem installs a hashem-gre-restore systemd unit so your fleet comes back after a reboot.

📦 Release Assets

Every release publishes archives for 7 Linux architectures — amd64, arm64, 386, s390x, armv5, armv6, armv7 — plus a SHA256SUMS manifest that both the installer and the self-updater verify.

📜 License

Licensed under the GNU AGPL-3.0. Forked and heavily modified from an earlier open-source tunneling project backpack; substantial new engineering (stacked architecture, Web UI, telemetry, process supervision, Telegram bot) by the maintainers.

Documentation ¶

There is no documentation for this package.

Source Files ¶

View all Source files

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
config
internal
alerthist Package alerthist keeps a small on-disk record of what the alert watcher has fired: the conditions active right now and the most recent messages.	Package alerthist keeps a small on-disk record of what the alert watcher has fired: the conditions active right now and the most recent messages.
app Package app holds shared constants and paths used across the Hashem Tunnel management layer (menu, manage, telegram, schedule, optimize).	Package app holds shared constants and paths used across the Hashem Tunnel management layer (menu, manage, telegram, schedule, optimize).
client
client/transport
debugserver Package debugserver hosts the opt-in profiling endpoint.	Package debugserver hosts the opt-in profiling endpoint.
deps Package deps manages the system-level dependencies for Hashem, ensuring that required tools like iproute2 (for GRE) and FRP binaries are automatically installed without requiring manual intervention from the user.	Package deps manages the system-level dependencies for Hashem, ensuring that required tools like iproute2 (for GRE) and FRP binaries are automatically installed without requiring manual intervention from the user.
e2e/testpanel command Command testpanel runs one real Hashem panel for the black-box e2e suite.	Command testpanel runs one real Hashem panel for the black-box e2e suite.
geo Package geo resolves an IP address to a country, city and network operator.	Package geo resolves an IP address to a country, city and network operator.
grefrp
localproxy Package localproxy runs a built-in proxy on the tunnel's exit side, so a node can be its own backend: instead of forwarding to a separate service (xray, a panel, …) that has to be installed and kept running, the tunnel forwards to a proxy this binary serves itself.	Package localproxy runs a built-in proxy on the tunnel's exit side, so a node can be its own backend: instead of forwarding to a separate service (xray, a panel, …) that has to be installed and kept running, the tunnel forwards to a proxy this binary serves itself.
manage
menu Package menu implements the interactive hashem CLI shown when the binary is run without a config file.	Package menu implements the interactive hashem CLI shown when the binary is run without a config file.
metrics Package metrics records what a running tunnel is actually doing — how much it carried, how much had to be sent twice, and how much was repaired by error correction — and leaves a snapshot on disk for the CLI to read.	Package metrics records what a running tunnel is actually doing — how much it carried, how much had to be sent twice, and how much was repaired by error correction — and leaves a snapshot on disk for the CLI to read.
monitor Package monitor runs everything that has to keep working whether or not anybody is looking: the watchdog that restarts dropped tunnels, the Telegram bot, and the alerts.	Package monitor runs everything that has to keep working whether or not anybody is looking: the watchdog that restarts dropped tunnels, the Telegram bot, and the alerts.
node Package node lets one panel configure tunnels on servers it manages.	Package node lets one panel configure tunnels on servers it manages.
optimize Package optimize applies kernel/network tuning for high-throughput, low-latency tunnels.	Package optimize applies kernel/network tuning for high-throughput, low-latency tunnels.
schedule Package schedule manages recurring hashem jobs via the system crontab (auto-refresh of tunnels and periodic Telegram reports).	Package schedule manages recurring hashem jobs via the system crontab (auto-refresh of tunnels and periodic Telegram reports).
server
server/transport
snispoof
socks Package socks implements a minimal SOCKS5 CONNECT proxy (server + client) with username/password auth and no third-party dependencies.	Package socks implements a minimal SOCKS5 CONNECT proxy (server + client) with username/password auth and no third-party dependencies.
spooftest Package spooftest discovers which forged source IPs actually traverse the network, in each direction, so an operator can pick spoof addresses that work rather than guessing.	Package spooftest discovers which forged source IPs actually traverse the network, in each direction, so an operator can pick spoof addresses that work rather than guessing.
sysstat Package sysstat reads the handful of machine-level numbers that both the web panel and the Telegram bot report on: processor, memory, swap, disk, load and uptime.	Package sysstat reads the handful of machine-level numbers that both the web panel and the Telegram bot report on: processor, memory, swap, disk, load and uptime.
telegram Package telegram sends periodic tunnel status reports to a Telegram admin and runs an interactive bot with Status / Web UI / Support buttons.	Package telegram sends periodic tunnel status reports to a Telegram admin and runs an interactive bot with Status / Web UI / Support buttons.
testport Package testport hands out loopback ports for tests to bind.	Package testport hands out loopback ports for tests to bind.
tui Package tui provides small terminal helpers (colors, prompts, banners) used by the interactive hashem menu.	Package tui provides small terminal helpers (colors, prompts, banners) used by the interactive hashem menu.
tunhist Package tunhist keeps the long view of every tunnel: traffic and up/down state, sampled on a timer and kept for a month.	Package tunhist keeps the long view of every tunnel: traffic and up/down state, sampled on a timer and kept for a month.
tunnel/direct Package direct forwards ports with the tunnel dialled the other way round.	Package direct forwards ports with the tunnel dialled the other way round.
tunnel/fullport Package fullport forwards every port a machine receives to the other end of the tunnel.	Package fullport forwards every port a machine receives to the other end of the tunnel.
tunnel/l3 Package l3 carries whole IP packets between two hosts.	Package l3 carries whole IP packets between two hosts.
tunnel/limits Package limits caps what one tunnel may use.	Package limits caps what one tunnel may use.
tunnel/mssclamp Package mssclamp caps the TCP segment size of connections crossing a tunnel interface.	Package mssclamp caps the TCP segment size of connections crossing a tunnel interface.
tunnel/portmap Package portmap parses the forwarded-port syntax the tunnels share.	Package portmap parses the forwarded-port syntax the tunnels share.
tunnelprovider Package tunnelprovider defines a common interface for managing different tunnel types (GRE, FRP, etc.) as first-class extensions alongside the existing Hashem engine tunnels.	Package tunnelprovider defines a common interface for managing different tunnel types (GRE, FRP, etc.) as first-class extensions alongside the existing Hashem engine tunnels.
tunnelprovider/frp
tunnelprovider/gost Package gost implements the GOST direct tunnel provider for Hashem Tunnel.	Package gost implements the GOST direct tunnel provider for Hashem Tunnel.
tunnelprovider/gre
tunnelstack
utils
utils/acceptloop Package acceptloop keeps a failing accept loop from burning a core.	Package acceptloop keeps a failing accept loop from burning a core.
utils/handlers
utils/network
web
webui Package webui serves an authenticated, dark-themed web dashboard on port 7777 showing live system metrics, tunnels and their logs.	Package webui serves an authenticated, dark-themed web dashboard on port 7777 showing live system metrics, tunnels and their logs.
tools
releasekey command Command releasekey generates the Ed25519 pair that release signatures use.	Command releasekey generates the Ed25519 pair that release signatures use.
signsums command Command signsums signs a release's SHA256SUMS, for the release workflow.	Command signsums signs a release's SHA256SUMS, for the release workflow.