vmflow

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 5, 2026 License: MIT Imports: 5 Imported by: 0

README

vmflow

vmflow is a small Go L4 forwarding runtime. It can run as a standalone daemon or be embedded into a larger control plane.

Docs CI Go Reference

Documentation: Website · 中文说明 · HTTP API · Docs source

What it does

  • TCP, UDP, and tcp+udp port forwarding
  • Rule lifecycle management: start, stop, restart, and full snapshot apply
  • Config-driven daemon with hot reload
  • Local admin API for health, rules, stats, precheck, reload, and metrics
  • Bearer-token auth with viewer/admin roles
  • Structured logs in text or JSON format
  • Prometheus-compatible /metrics
  • Rule precheck for loops, duplicate ports, and unavailable listeners
  • Embeddable Go runtime for products that need in-process forwarding
  • Terminal dashboard via vmflow tui

Quick start

Install the latest prebuilt binary (Linux/macOS):

curl -fsSL https://raw.githubusercontent.com/cloudapp3/vmflow/main/install.sh | bash

Install globally to /usr/local/bin:

curl -fsSL https://raw.githubusercontent.com/cloudapp3/vmflow/main/install.sh | sudo bash -s -- --dir /usr/local/bin

Install a specific release tag:

curl -fsSL https://raw.githubusercontent.com/cloudapp3/vmflow/main/install.sh | bash -s -- --version v0.1.0

The installer downloads GitHub Release archives, verifies checksums.txt with SHA-256 by default, and auto-detects an install directory (/usr/local/bin → ~/.local/bin → ~/bin) when --dir is omitted. You can override the install directory with --dir PATH or VMFLOW_INSTALL_DIR, and skip checksum verification with --skip-verify if needed. For private releases or higher GitHub API limits, set GITHUB_TOKEN or GH_TOKEN.

Or build from source:

go build -trimpath -o vmflow ./cmd/vmflow

Start the daemon in one terminal:

./vmflow daemon -config ./examples/config.yaml

Query it from another terminal:

./vmflow ctl health
./vmflow ctl rules
./vmflow ctl stats
./vmflow ctl metrics
./vmflow ctl precheck

Open the terminal UI:

./vmflow tui

Show build metadata:

./vmflow version
./vmflow version -json

Configuration

See examples/config.yaml:

version: 1
admin_listen_addr: 127.0.0.1:19090

log:
  level: info
  format: text

auth:
  enabled: false
  tokens:
    - name: admin
      token: change-me
      role: admin

rules:
  - rule_id: ssh-forward
    name: ssh-forward
    protocol: tcp
    listen_addr: 0.0.0.0
    listen_port: 2201
    target_addr: 127.0.0.1
    target_port: 22
    enabled: true

Security note: keep the admin API on 127.0.0.1 by default. If you expose it outside localhost, enable bearer-token auth and use an admin token for mutating endpoints.

Commands

vmflow daemon        -config ./examples/config.yaml [-admin-listen 127.0.0.1:19090]
vmflow ctl           [-addr http://127.0.0.1:19090] [-token TOKEN] <health|rules|stats|metrics|precheck|reload>
vmflow tui           [-addr http://127.0.0.1:19090] [-token TOKEN]
vmflow version       [-json]

Aliases are available: daemon=d, ctl=c, tui=t, and version=v.

Admin API

Documented in docs/API.md. Main endpoints:

  • GET /healthz
  • GET /v1/rules
  • GET /v1/stats
  • GET|POST /v1/precheck
  • POST /v1/reload
  • GET /metrics

Embedding vmflow

Use the top-level package when vmflow is embedded into another Go service:

rt := vmflow.New()
defer rt.Close()

result := rt.Apply(rules) // []engine.Rule
stats := rt.SnapshotAll()

The embedding application owns persistence, auth, UI, audit logs, and business rules. vmflow owns only in-process forwarding, rule lifecycle, and real-time counters. See docs/EMBEDDING.md.

Development

make fmt
make test
make vet
make smoke
make build

Some tests bind local ports. If your sandbox blocks sockets, run them in an environment that permits local listeners.

Release

Tagged releases are built by GoReleaser through GitHub Actions:

git tag -a v0.1.0 -m "v0.1.0"
git push origin v0.1.0

The release workflow publishes cross-platform archives, .deb / .rpm packages, and checksums.txt. Linux/macOS users can also install with install.sh.

Project layout

  • engine/ — protocol forwarding engine and in-memory stats
  • config/ — YAML config loading and validation
  • controlapi/ — local control API, auth, reload, precheck, metrics wiring
  • metrics/ — Prometheus text exposition helpers
  • precheck/ — static checks before applying rules
  • tui/ — terminal dashboard client
  • cmd/vmflow/ — primary all-in-one binary
  • examples/ — runnable and embeddable examples
  • docs/ — architecture, API, embedding, roadmap, and changelog

License

MIT

Documentation

Overview

Package vmflow provides an embeddable L4 forwarding runtime for TCP and UDP rules. It can be used directly by larger Go control planes or through the standalone vmflow daemon and CLI.

Index

Constants

This section is empty.

Variables

View Source 
var ErrRuntimeClosed = errors.New("vmflow runtime closed")

ErrRuntimeClosed is returned when callers try to mutate a closed Runtime.

Functions

This section is empty.

Types

type CertProvider 

type CertProvider = engine.CertProvider

CertProvider is the certificate provider interface used by HTTPS rules. It is an alias of engine.CertProvider so embedders can depend on the top-level vmflow package without importing engine for certificate wiring.

type Options 

type Options struct {
	// Collector can be supplied when the host application wants to share or wrap
	// the vmflow in-memory traffic counters. If nil, a new collector is created.
	Collector *engine.Collector

	// CertProvider enables HTTPS rules. Leave nil when the embedded application
	// only uses TCP, UDP, tcp+udp, or HTTP proxy rules.
	CertProvider CertProvider
}

Options controls construction of an embedded Runtime.

type Runtime 

type Runtime struct {
	// contains filtered or unexported fields
}

Runtime is a small embeddable facade over the forwarding engine.

Use Runtime when vmflow is embedded into a larger control plane such as vmpulse. The larger application remains responsible for configuration, persistence, authentication, and business logic; Runtime owns only the in-process forwarding manager and real-time counters.

func New 

func New() *Runtime

New creates a runtime with default options.

func NewRuntime 

func NewRuntime(opts Options) *Runtime

NewRuntime creates a new embeddable forwarding runtime.

func (*Runtime) Apply 

func (r *Runtime) Apply(rules []engine.Rule) engine.ApplyResult

Apply applies a full replacement snapshot. This is the usual mode for an embedded control plane that calculates desired state from its own database.

func (*Runtime) ApplySnapshot 

func (r *Runtime) ApplySnapshot(rules []engine.Rule, opts engine.ApplySnapshotOptions) engine.ApplyResult

ApplySnapshot applies rules with explicit options.

func (*Runtime) Close 

func (r *Runtime) Close() error

Close stops all rules and marks the runtime as closed.

func (*Runtime) Collector 

func (r *Runtime) Collector() *engine.Collector

Collector returns the underlying in-memory collector.

func (*Runtime) Manager 

func (r *Runtime) Manager() *engine.Manager

Manager returns the underlying engine manager for advanced use cases. Prefer the facade methods on Runtime when possible.

func (*Runtime) RemoveRule 

func (r *Runtime) RemoveRule(ruleID string)

RemoveRule stops a single rule and removes its counters.

func (*Runtime) RestartRule 

func (r *Runtime) RestartRule(rule engine.Rule) error

RestartRule restarts or starts a single rule.

func (*Runtime) RunningCount 

func (r *Runtime) RunningCount() int

RunningCount returns the number of currently running rules.

func (*Runtime) RunningRules 

func (r *Runtime) RunningRules() []engine.Rule

RunningRules returns the currently running rules sorted by rule_id.

func (*Runtime) Shutdown 

func (r *Runtime) Shutdown(ctx context.Context) error

Shutdown stops the runtime. The current implementation stops synchronously; the context is accepted to keep the embedding API forward-compatible with future graceful drain support.

func (*Runtime) Snapshot 

func (r *Runtime) Snapshot(ruleID string) engine.TrafficSnapshot

Snapshot returns one rule's in-memory traffic snapshot.

func (*Runtime) SnapshotAll 

func (r *Runtime) SnapshotAll() []engine.TrafficSnapshot

SnapshotAll returns all in-memory traffic snapshots sorted by rule_id.

func (*Runtime) StartRule 

func (r *Runtime) StartRule(rule engine.Rule) error

StartRule starts a single rule without replacing other rules.

func (*Runtime) StopAll 

func (r *Runtime) StopAll()

StopAll stops all running rules and keeps the runtime reusable.

func (*Runtime) StopRule 

func (r *Runtime) StopRule(ruleID string)

StopRule stops a single rule and keeps its counters.

Source Files

View all Source files

Directories

Path Synopsis
cmd
relayctl command
relayd command
relaytui command
vmflow command
examples
embedding command
internal
logging

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.