virtual-net: initial (#4751)

pkg/config/v1/client.go

@@ -58,9 +58,14 @@ type ClientCommonConfig struct {
 	// set.
 	Start []string `json:"start,omitempty"`
 
-	Log       LogConfig             `json:"log,omitempty"`
-	WebServer WebServerConfig       `json:"webServer,omitempty"`
-	Transport ClientTransportConfig `json:"transport,omitempty"`
+	Log        LogConfig             `json:"log,omitempty"`
+	WebServer  WebServerConfig       `json:"webServer,omitempty"`
+	Transport  ClientTransportConfig `json:"transport,omitempty"`
+	VirtualNet VirtualNetConfig      `json:"virtualNet,omitempty"`
+
+	// FeatureGates specifies a set of feature gates to enable or disable.
+	// This can be used to enable alpha/beta features or disable default features.
+	FeatureGates map[string]bool `json:"featureGates,omitempty"`
 
 	// UDPPacketSize specifies the udp packet size
 	// By default, this value is 1500
@@ -204,3 +209,7 @@ type AuthOIDCClientConfig struct {
 	// this field will be transfer to map[string][]string in OIDC token generator.
 	AdditionalEndpointParams map[string]string `json:"additionalEndpointParams,omitempty"`
 }
+
+type VirtualNetConfig struct {
+	Address string `json:"address,omitempty"`
+}

pkg/config/v1/proxy_plugin.go

@@ -26,6 +26,32 @@ import (
 	"github.com/fatedier/frp/pkg/util/util"
 )
 
+const (
+	PluginHTTP2HTTPS       = "http2https"
+	PluginHTTPProxy        = "http_proxy"
+	PluginHTTPS2HTTP       = "https2http"
+	PluginHTTPS2HTTPS      = "https2https"
+	PluginHTTP2HTTP        = "http2http"
+	PluginSocks5           = "socks5"
+	PluginStaticFile       = "static_file"
+	PluginUnixDomainSocket = "unix_domain_socket"
+	PluginTLS2Raw          = "tls2raw"
+	PluginVirtualNet       = "virtual_net"
+)
+
+var clientPluginOptionsTypeMap = map[string]reflect.Type{
+	PluginHTTP2HTTPS:       reflect.TypeOf(HTTP2HTTPSPluginOptions{}),
+	PluginHTTPProxy:        reflect.TypeOf(HTTPProxyPluginOptions{}),
+	PluginHTTPS2HTTP:       reflect.TypeOf(HTTPS2HTTPPluginOptions{}),
+	PluginHTTPS2HTTPS:      reflect.TypeOf(HTTPS2HTTPSPluginOptions{}),
+	PluginHTTP2HTTP:        reflect.TypeOf(HTTP2HTTPPluginOptions{}),
+	PluginSocks5:           reflect.TypeOf(Socks5PluginOptions{}),
+	PluginStaticFile:       reflect.TypeOf(StaticFilePluginOptions{}),
+	PluginUnixDomainSocket: reflect.TypeOf(UnixDomainSocketPluginOptions{}),
+	PluginTLS2Raw:          reflect.TypeOf(TLS2RawPluginOptions{}),
+	PluginVirtualNet:       reflect.TypeOf(VirtualNetPluginOptions{}),
+}
+
 type ClientPluginOptions interface {
 	Complete()
 }
@@ -74,30 +100,6 @@ func (c *TypedClientPluginOptions) MarshalJSON() ([]byte, error) {
 	return json.Marshal(c.ClientPluginOptions)
 }
 
-const (
-	PluginHTTP2HTTPS       = "http2https"
-	PluginHTTPProxy        = "http_proxy"
-	PluginHTTPS2HTTP       = "https2http"
-	PluginHTTPS2HTTPS      = "https2https"
-	PluginHTTP2HTTP        = "http2http"
-	PluginSocks5           = "socks5"
-	PluginStaticFile       = "static_file"
-	PluginUnixDomainSocket = "unix_domain_socket"
-	PluginTLS2Raw          = "tls2raw"
-)
-
-var clientPluginOptionsTypeMap = map[string]reflect.Type{
-	PluginHTTP2HTTPS:       reflect.TypeOf(HTTP2HTTPSPluginOptions{}),
-	PluginHTTPProxy:        reflect.TypeOf(HTTPProxyPluginOptions{}),
-	PluginHTTPS2HTTP:       reflect.TypeOf(HTTPS2HTTPPluginOptions{}),
-	PluginHTTPS2HTTPS:      reflect.TypeOf(HTTPS2HTTPSPluginOptions{}),
-	PluginHTTP2HTTP:        reflect.TypeOf(HTTP2HTTPPluginOptions{}),
-	PluginSocks5:           reflect.TypeOf(Socks5PluginOptions{}),
-	PluginStaticFile:       reflect.TypeOf(StaticFilePluginOptions{}),
-	PluginUnixDomainSocket: reflect.TypeOf(UnixDomainSocketPluginOptions{}),
-	PluginTLS2Raw:          reflect.TypeOf(TLS2RawPluginOptions{}),
-}
-
 type HTTP2HTTPSPluginOptions struct {
 	Type              string           `json:"type,omitempty"`
 	LocalAddr         string           `json:"localAddr,omitempty"`
@@ -185,3 +187,9 @@ type TLS2RawPluginOptions struct {
 }
 
 func (o *TLS2RawPluginOptions) Complete() {}
+
+type VirtualNetPluginOptions struct {
+	Type string `json:"type,omitempty"`
+}
+
+func (o *VirtualNetPluginOptions) Complete() {}

pkg/config/v1/validation/client.go

@@ -23,6 +23,7 @@ import (
 	"github.com/samber/lo"
 
 	v1 "github.com/fatedier/frp/pkg/config/v1"
+	"github.com/fatedier/frp/pkg/featuregate"
 )
 
 func ValidateClientCommonConfig(c *v1.ClientCommonConfig) (Warning, error) {
@@ -30,6 +31,13 @@ func ValidateClientCommonConfig(c *v1.ClientCommonConfig) (Warning, error) {
 		warnings Warning
 		errs     error
 	)
+	// validate feature gates
+	if c.VirtualNet.Address != "" {
+		if !featuregate.Enabled(featuregate.VirtualNet) {
+			return warnings, fmt.Errorf("VirtualNet feature is not enabled; enable it by setting the appropriate feature gate flag")
+		}
+	}
+
 	if !slices.Contains(SupportedAuthMethods, c.Auth.Method) {
 		errs = AppendError(errs, fmt.Errorf("invalid auth method, optional values are %v", SupportedAuthMethods))
 	}

pkg/config/v1/visitor.go

@@ -44,6 +44,9 @@ type VisitorBaseConfig struct {
 	// It can be less than 0, it means don't bind to the port and only receive connections redirected from
 	// other visitors. (This is not supported for SUDP now)
 	BindPort int `json:"bindPort,omitempty"`
+
+	// Plugin specifies what plugin should be used.
+	Plugin TypedVisitorPluginOptions `json:"plugin,omitempty"`
 }
 
 func (c *VisitorBaseConfig) GetBaseConfig() *VisitorBaseConfig {

pkg/config/v1/visitor_plugin.go

@@ -0,0 +1,86 @@
+// Copyright 2025 The frp Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package v1
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"reflect"
+)
+
+const (
+	VisitorPluginVirtualNet = "virtual_net"
+)
+
+var visitorPluginOptionsTypeMap = map[string]reflect.Type{
+	VisitorPluginVirtualNet: reflect.TypeOf(VirtualNetVisitorPluginOptions{}),
+}
+
+type VisitorPluginOptions interface {
+	Complete()
+}
+
+type TypedVisitorPluginOptions struct {
+	Type string `json:"type"`
+	VisitorPluginOptions
+}
+
+func (c *TypedVisitorPluginOptions) UnmarshalJSON(b []byte) error {
+	if len(b) == 4 && string(b) == "null" {
+		return nil
+	}
+
+	typeStruct := struct {
+		Type string `json:"type"`
+	}{}
+	if err := json.Unmarshal(b, &typeStruct); err != nil {
+		return err
+	}
+
+	c.Type = typeStruct.Type
+	if c.Type == "" {
+		return errors.New("visitor plugin type is empty")
+	}
+
+	v, ok := visitorPluginOptionsTypeMap[typeStruct.Type]
+	if !ok {
+		return fmt.Errorf("unknown visitor plugin type: %s", typeStruct.Type)
+	}
+	options := reflect.New(v).Interface().(VisitorPluginOptions)
+
+	decoder := json.NewDecoder(bytes.NewBuffer(b))
+	if DisallowUnknownFields {
+		decoder.DisallowUnknownFields()
+	}
+
+	if err := decoder.Decode(options); err != nil {
+		return fmt.Errorf("unmarshal VisitorPluginOptions error: %v", err)
+	}
+	c.VisitorPluginOptions = options
+	return nil
+}
+
+func (c *TypedVisitorPluginOptions) MarshalJSON() ([]byte, error) {
+	return json.Marshal(c.VisitorPluginOptions)
+}
+
+type VirtualNetVisitorPluginOptions struct {
+	Type          string `json:"type"`
+	DestinationIP string `json:"destinationIP"`
+}
+
+func (o *VirtualNetVisitorPluginOptions) Complete() {}

pkg/featuregate/feature_gate.go

@@ -0,0 +1,219 @@
+// Copyright 2025 The frp Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package featuregate
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+	"sync"
+	"sync/atomic"
+)
+
+// Feature represents a feature gate name
+type Feature string
+
+// FeatureStage represents the maturity level of a feature
+type FeatureStage string
+
+const (
+	// Alpha means the feature is experimental and disabled by default
+	Alpha FeatureStage = "ALPHA"
+	// Beta means the feature is more stable but still might change and is disabled by default
+	Beta FeatureStage = "BETA"
+	// GA means the feature is generally available and enabled by default
+	GA FeatureStage = ""
+)
+
+// FeatureSpec describes a feature and its properties
+type FeatureSpec struct {
+	// Default is the default enablement state for the feature
+	Default bool
+	// LockToDefault indicates the feature cannot be changed from its default
+	LockToDefault bool
+	// Stage indicates the maturity level of the feature
+	Stage FeatureStage
+}
+
+// Define all available features here
+var (
+	VirtualNet = Feature("VirtualNet")
+)
+
+// defaultFeatures defines default features with their specifications
+var defaultFeatures = map[Feature]FeatureSpec{
+	// Actual features
+	VirtualNet: {Default: false, Stage: Alpha},
+}
+
+// FeatureGate indicates whether a given feature is enabled or not
+type FeatureGate interface {
+	// Enabled returns true if the key is enabled
+	Enabled(key Feature) bool
+	// KnownFeatures returns a slice of strings describing the known features
+	KnownFeatures() []string
+}
+
+// MutableFeatureGate allows for dynamic feature gate configuration
+type MutableFeatureGate interface {
+	FeatureGate
+
+	// SetFromMap sets feature gate values from a map[string]bool
+	SetFromMap(m map[string]bool) error
+	// Add adds features to the feature gate
+	Add(features map[Feature]FeatureSpec) error
+	// String returns a string representing the feature gate configuration
+	String() string
+}
+
+// featureGate implements the FeatureGate and MutableFeatureGate interfaces
+type featureGate struct {
+	// lock guards writes to known, enabled, and reads/writes of closed
+	lock sync.Mutex
+	// known holds a map[Feature]FeatureSpec
+	known atomic.Value
+	// enabled holds a map[Feature]bool
+	enabled atomic.Value
+	// closed is set to true once the feature gates are considered immutable
+	closed bool
+}
+
+// NewFeatureGate creates a new feature gate with the default features
+func NewFeatureGate() MutableFeatureGate {
+	known := map[Feature]FeatureSpec{}
+	for k, v := range defaultFeatures {
+		known[k] = v
+	}
+
+	f := &featureGate{}
+	f.known.Store(known)
+	f.enabled.Store(map[Feature]bool{})
+	return f
+}
+
+// SetFromMap sets feature gate values from a map[string]bool
+func (f *featureGate) SetFromMap(m map[string]bool) error {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+
+	// Copy existing state
+	known := map[Feature]FeatureSpec{}
+	for k, v := range f.known.Load().(map[Feature]FeatureSpec) {
+		known[k] = v
+	}
+	enabled := map[Feature]bool{}
+	for k, v := range f.enabled.Load().(map[Feature]bool) {
+		enabled[k] = v
+	}
+
+	// Apply the new settings
+	for k, v := range m {
+		k := Feature(k)
+		featureSpec, ok := known[k]
+		if !ok {
+			return fmt.Errorf("unrecognized feature gate: %s", k)
+		}
+		if featureSpec.LockToDefault && featureSpec.Default != v {
+			return fmt.Errorf("cannot set feature gate %v to %v, feature is locked to %v", k, v, featureSpec.Default)
+		}
+		enabled[k] = v
+	}
+
+	// Persist the changes
+	f.known.Store(known)
+	f.enabled.Store(enabled)
+	return nil
+}
+
+// Add adds features to the feature gate
+func (f *featureGate) Add(features map[Feature]FeatureSpec) error {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+
+	if f.closed {
+		return fmt.Errorf("cannot add feature gates after the feature gate is closed")
+	}
+
+	// Copy existing state
+	known := map[Feature]FeatureSpec{}
+	for k, v := range f.known.Load().(map[Feature]FeatureSpec) {
+		known[k] = v
+	}
+
+	// Add new features
+	for name, spec := range features {
+		if existingSpec, found := known[name]; found {
+			if existingSpec == spec {
+				continue
+			}
+			return fmt.Errorf("feature gate %q with different spec already exists: %v", name, existingSpec)
+		}
+		known[name] = spec
+	}
+
+	// Persist changes
+	f.known.Store(known)
+
+	return nil
+}
+
+// String returns a string containing all enabled feature gates, formatted as "key1=value1,key2=value2,..."
+func (f *featureGate) String() string {
+	pairs := []string{}
+	for k, v := range f.enabled.Load().(map[Feature]bool) {
+		pairs = append(pairs, fmt.Sprintf("%s=%t", k, v))
+	}
+	sort.Strings(pairs)
+	return strings.Join(pairs, ",")
+}
+
+// Enabled returns true if the key is enabled
+func (f *featureGate) Enabled(key Feature) bool {
+	if v, ok := f.enabled.Load().(map[Feature]bool)[key]; ok {
+		return v
+	}
+	if v, ok := f.known.Load().(map[Feature]FeatureSpec)[key]; ok {
+		return v.Default
+	}
+	return false
+}
+
+// KnownFeatures returns a slice of strings describing the FeatureGate's known features
+// GA features are hidden from the list
+func (f *featureGate) KnownFeatures() []string {
+	knownFeatures := f.known.Load().(map[Feature]FeatureSpec)
+	known := make([]string, 0, len(knownFeatures))
+	for k, v := range knownFeatures {
+		if v.Stage == GA {
+			continue
+		}
+		known = append(known, fmt.Sprintf("%s=true|false (%s - default=%t)", k, v.Stage, v.Default))
+	}
+	sort.Strings(known)
+	return known
+}
+
+// Default feature gates instance
+var DefaultFeatureGates = NewFeatureGate()
+
+// Enabled checks if a feature is enabled in the default feature gates
+func Enabled(name Feature) bool {
+	return DefaultFeatureGates.Enabled(name)
+}
+
+// SetFromMap sets feature gate values from a map in the default feature gates
+func SetFromMap(featureMap map[string]bool) error {
+	return DefaultFeatureGates.SetFromMap(featureMap)
+}

pkg/plugin/client/http2http.go

@@ -14,13 +14,11 @@
 
 //go:build !frps
 
-package plugin
+package client
 
 import (
 	"context"
-	"io"
 	stdlog "log"
-	"net"
 	"net/http"
 	"net/http/httputil"
 
@@ -42,7 +40,7 @@ type HTTP2HTTPPlugin struct {
 	s *http.Server
 }
 
-func NewHTTP2HTTPPlugin(options v1.ClientPluginOptions) (Plugin, error) {
+func NewHTTP2HTTPPlugin(_ PluginContext, options v1.ClientPluginOptions) (Plugin, error) {
 	opts := options.(*v1.HTTP2HTTPPluginOptions)
 
 	listener := NewProxyListener()
@@ -80,8 +78,8 @@ func NewHTTP2HTTPPlugin(options v1.ClientPluginOptions) (Plugin, error) {
 	return p, nil
 }
 
-func (p *HTTP2HTTPPlugin) Handle(_ context.Context, conn io.ReadWriteCloser, realConn net.Conn, _ *ExtraInfo) {
-	wrapConn := netpkg.WrapReadWriteCloserToConn(conn, realConn)
+func (p *HTTP2HTTPPlugin) Handle(_ context.Context, connInfo *ConnectionInfo) {
+	wrapConn := netpkg.WrapReadWriteCloserToConn(connInfo.Conn, connInfo.UnderlyingConn)
 	_ = p.l.PutConn(wrapConn)
 }
 

pkg/plugin/client/http2https.go

@@ -14,14 +14,12 @@
 
 //go:build !frps
 
-package plugin
+package client
 
 import (
 	"context"
 	"crypto/tls"
-	"io"
 	stdlog "log"
-	"net"
 	"net/http"
 	"net/http/httputil"
 
@@ -43,7 +41,7 @@ type HTTP2HTTPSPlugin struct {
 	s *http.Server
 }
 
-func NewHTTP2HTTPSPlugin(options v1.ClientPluginOptions) (Plugin, error) {
+func NewHTTP2HTTPSPlugin(_ PluginContext, options v1.ClientPluginOptions) (Plugin, error) {
 	opts := options.(*v1.HTTP2HTTPSPluginOptions)
 
 	listener := NewProxyListener()
@@ -89,8 +87,8 @@ func NewHTTP2HTTPSPlugin(options v1.ClientPluginOptions) (Plugin, error) {
 	return p, nil
 }
 
-func (p *HTTP2HTTPSPlugin) Handle(_ context.Context, conn io.ReadWriteCloser, realConn net.Conn, _ *ExtraInfo) {
-	wrapConn := netpkg.WrapReadWriteCloserToConn(conn, realConn)
+func (p *HTTP2HTTPSPlugin) Handle(_ context.Context, connInfo *ConnectionInfo) {
+	wrapConn := netpkg.WrapReadWriteCloserToConn(connInfo.Conn, connInfo.UnderlyingConn)
 	_ = p.l.PutConn(wrapConn)
 }
 

pkg/plugin/client/http_proxy.go

@@ -14,7 +14,7 @@
 
 //go:build !frps
 
-package plugin
+package client
 
 import (
 	"bufio"
@@ -45,7 +45,7 @@ type HTTPProxy struct {
 	s *http.Server
 }
 
-func NewHTTPProxyPlugin(options v1.ClientPluginOptions) (Plugin, error) {
+func NewHTTPProxyPlugin(_ PluginContext, options v1.ClientPluginOptions) (Plugin, error) {
 	opts := options.(*v1.HTTPProxyPluginOptions)
 	listener := NewProxyListener()
 
@@ -69,8 +69,8 @@ func (hp *HTTPProxy) Name() string {
 	return v1.PluginHTTPProxy
 }
 
-func (hp *HTTPProxy) Handle(_ context.Context, conn io.ReadWriteCloser, realConn net.Conn, _ *ExtraInfo) {
-	wrapConn := netpkg.WrapReadWriteCloserToConn(conn, realConn)
+func (hp *HTTPProxy) Handle(_ context.Context, connInfo *ConnectionInfo) {
+	wrapConn := netpkg.WrapReadWriteCloserToConn(connInfo.Conn, connInfo.UnderlyingConn)
 
 	sc, rd := libnet.NewSharedConn(wrapConn)
 	firstBytes := make([]byte, 7)

pkg/plugin/client/https2http.go

@@ -14,15 +14,13 @@
 
 //go:build !frps
 
-package plugin
+package client
 
 import (
 	"context"
 	"crypto/tls"
 	"fmt"
-	"io"
 	stdlog "log"
-	"net"
 	"net/http"
 	"net/http/httputil"
 	"time"
@@ -48,7 +46,7 @@ type HTTPS2HTTPPlugin struct {
 	s *http.Server
 }
 
-func NewHTTPS2HTTPPlugin(options v1.ClientPluginOptions) (Plugin, error) {
+func NewHTTPS2HTTPPlugin(_ PluginContext, options v1.ClientPluginOptions) (Plugin, error) {
 	opts := options.(*v1.HTTPS2HTTPPluginOptions)
 	listener := NewProxyListener()
 
@@ -106,10 +104,10 @@ func NewHTTPS2HTTPPlugin(options v1.ClientPluginOptions) (Plugin, error) {
 	return p, nil
 }
 
-func (p *HTTPS2HTTPPlugin) Handle(_ context.Context, conn io.ReadWriteCloser, realConn net.Conn, extra *ExtraInfo) {
-	wrapConn := netpkg.WrapReadWriteCloserToConn(conn, realConn)
-	if extra.SrcAddr != nil {
-		wrapConn.SetRemoteAddr(extra.SrcAddr)
+func (p *HTTPS2HTTPPlugin) Handle(_ context.Context, connInfo *ConnectionInfo) {
+	wrapConn := netpkg.WrapReadWriteCloserToConn(connInfo.Conn, connInfo.UnderlyingConn)
+	if connInfo.SrcAddr != nil {
+		wrapConn.SetRemoteAddr(connInfo.SrcAddr)
 	}
 	_ = p.l.PutConn(wrapConn)
 }

pkg/plugin/client/https2https.go

@@ -14,15 +14,13 @@
 
 //go:build !frps
 
-package plugin
+package client
 
 import (
 	"context"
 	"crypto/tls"
 	"fmt"
-	"io"
 	stdlog "log"
-	"net"
 	"net/http"
 	"net/http/httputil"
 	"time"
@@ -48,7 +46,7 @@ type HTTPS2HTTPSPlugin struct {
 	s *http.Server
 }
 
-func NewHTTPS2HTTPSPlugin(options v1.ClientPluginOptions) (Plugin, error) {
+func NewHTTPS2HTTPSPlugin(_ PluginContext, options v1.ClientPluginOptions) (Plugin, error) {
 	opts := options.(*v1.HTTPS2HTTPSPluginOptions)
 
 	listener := NewProxyListener()
@@ -112,10 +110,10 @@ func NewHTTPS2HTTPSPlugin(options v1.ClientPluginOptions) (Plugin, error) {
 	return p, nil
 }
 
-func (p *HTTPS2HTTPSPlugin) Handle(_ context.Context, conn io.ReadWriteCloser, realConn net.Conn, extra *ExtraInfo) {
-	wrapConn := netpkg.WrapReadWriteCloserToConn(conn, realConn)
-	if extra.SrcAddr != nil {
-		wrapConn.SetRemoteAddr(extra.SrcAddr)
+func (p *HTTPS2HTTPSPlugin) Handle(_ context.Context, connInfo *ConnectionInfo) {
+	wrapConn := netpkg.WrapReadWriteCloserToConn(connInfo.Conn, connInfo.UnderlyingConn)
+	if connInfo.SrcAddr != nil {
+		wrapConn.SetRemoteAddr(connInfo.SrcAddr)
 	}
 	_ = p.l.PutConn(wrapConn)
 }

pkg/plugin/client/plugin.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package plugin
+package client
 
 import (
 	"context"
@@ -25,13 +25,18 @@ import (
 	pp "github.com/pires/go-proxyproto"
 
 	v1 "github.com/fatedier/frp/pkg/config/v1"
+	"github.com/fatedier/frp/pkg/vnet"
 )
 
+type PluginContext struct {
+	Name           string
+	VnetController *vnet.Controller
+}
+
 // Creators is used for create plugins to handle connections.
 var creators = make(map[string]CreatorFn)
 
-// params has prefix "plugin_"
-type CreatorFn func(options v1.ClientPluginOptions) (Plugin, error)
+type CreatorFn func(pluginCtx PluginContext, options v1.ClientPluginOptions) (Plugin, error)
 
 func Register(name string, fn CreatorFn) {
 	if _, exist := creators[name]; exist {
@@ -40,16 +45,19 @@ func Register(name string, fn CreatorFn) {
 	creators[name] = fn
 }
 
-func Create(name string, options v1.ClientPluginOptions) (p Plugin, err error) {
-	if fn, ok := creators[name]; ok {
-		p, err = fn(options)
+func Create(pluginName string, pluginCtx PluginContext, options v1.ClientPluginOptions) (p Plugin, err error) {
+	if fn, ok := creators[pluginName]; ok {
+		p, err = fn(pluginCtx, options)
 	} else {
-		err = fmt.Errorf("plugin [%s] is not registered", name)
+		err = fmt.Errorf("plugin [%s] is not registered", pluginName)
 	}
 	return
 }
 
-type ExtraInfo struct {
+type ConnectionInfo struct {
+	Conn           io.ReadWriteCloser
+	UnderlyingConn net.Conn
+
 	ProxyProtocolHeader *pp.Header
 	SrcAddr             net.Addr
 	DstAddr             net.Addr
@@ -58,7 +66,7 @@ type ExtraInfo struct {
 type Plugin interface {
 	Name() string
 
-	Handle(ctx context.Context, conn io.ReadWriteCloser, realConn net.Conn, extra *ExtraInfo)
+	Handle(ctx context.Context, connInfo *ConnectionInfo)
 	Close() error
 }
 

pkg/plugin/client/socks5.go

@@ -14,13 +14,12 @@
 
 //go:build !frps
 
-package plugin
+package client
 
 import (
 	"context"
 	"io"
 	"log"
-	"net"
 
 	gosocks5 "github.com/armon/go-socks5"
 
@@ -36,7 +35,7 @@ type Socks5Plugin struct {
 	Server *gosocks5.Server
 }
 
-func NewSocks5Plugin(options v1.ClientPluginOptions) (p Plugin, err error) {
+func NewSocks5Plugin(_ PluginContext, options v1.ClientPluginOptions) (p Plugin, err error) {
 	opts := options.(*v1.Socks5PluginOptions)
 
 	cfg := &gosocks5.Config{
@@ -51,9 +50,9 @@ func NewSocks5Plugin(options v1.ClientPluginOptions) (p Plugin, err error) {
 	return
 }
 
-func (sp *Socks5Plugin) Handle(_ context.Context, conn io.ReadWriteCloser, realConn net.Conn, _ *ExtraInfo) {
-	defer conn.Close()
-	wrapConn := netpkg.WrapReadWriteCloserToConn(conn, realConn)
+func (sp *Socks5Plugin) Handle(_ context.Context, connInfo *ConnectionInfo) {
+	defer connInfo.Conn.Close()
+	wrapConn := netpkg.WrapReadWriteCloserToConn(connInfo.Conn, connInfo.UnderlyingConn)
 	_ = sp.Server.ServeConn(wrapConn)
 }
 

pkg/plugin/client/static_file.go

@@ -14,12 +14,10 @@
 
 //go:build !frps
 
-package plugin
+package client
 
 import (
 	"context"
-	"io"
-	"net"
 	"net/http"
 	"time"
 
@@ -40,7 +38,7 @@ type StaticFilePlugin struct {
 	s *http.Server
 }
 
-func NewStaticFilePlugin(options v1.ClientPluginOptions) (Plugin, error) {
+func NewStaticFilePlugin(_ PluginContext, options v1.ClientPluginOptions) (Plugin, error) {
 	opts := options.(*v1.StaticFilePluginOptions)
 
 	listener := NewProxyListener()
@@ -70,8 +68,8 @@ func NewStaticFilePlugin(options v1.ClientPluginOptions) (Plugin, error) {
 	return sp, nil
 }
 
-func (sp *StaticFilePlugin) Handle(_ context.Context, conn io.ReadWriteCloser, realConn net.Conn, _ *ExtraInfo) {
-	wrapConn := netpkg.WrapReadWriteCloserToConn(conn, realConn)
+func (sp *StaticFilePlugin) Handle(_ context.Context, connInfo *ConnectionInfo) {
+	wrapConn := netpkg.WrapReadWriteCloserToConn(connInfo.Conn, connInfo.UnderlyingConn)
 	_ = sp.l.PutConn(wrapConn)
 }
 

pkg/plugin/client/tls2raw.go

@@ -14,12 +14,11 @@
 
 //go:build !frps
 
-package plugin
+package client
 
 import (
 	"context"
 	"crypto/tls"
-	"io"
 	"net"
 
 	libio "github.com/fatedier/golib/io"
@@ -40,7 +39,7 @@ type TLS2RawPlugin struct {
 	tlsConfig *tls.Config
 }
 
-func NewTLS2RawPlugin(options v1.ClientPluginOptions) (Plugin, error) {
+func NewTLS2RawPlugin(_ PluginContext, options v1.ClientPluginOptions) (Plugin, error) {
 	opts := options.(*v1.TLS2RawPluginOptions)
 
 	p := &TLS2RawPlugin{
@@ -55,10 +54,10 @@ func NewTLS2RawPlugin(options v1.ClientPluginOptions) (Plugin, error) {
 	return p, nil
 }
 
-func (p *TLS2RawPlugin) Handle(ctx context.Context, conn io.ReadWriteCloser, realConn net.Conn, _ *ExtraInfo) {
+func (p *TLS2RawPlugin) Handle(ctx context.Context, connInfo *ConnectionInfo) {
 	xl := xlog.FromContextSafe(ctx)
 
-	wrapConn := netpkg.WrapReadWriteCloserToConn(conn, realConn)
+	wrapConn := netpkg.WrapReadWriteCloserToConn(connInfo.Conn, connInfo.UnderlyingConn)
 	tlsConn := tls.Server(wrapConn, p.tlsConfig)
 
 	if err := tlsConn.Handshake(); err != nil {

pkg/plugin/client/unix_domain_socket.go

@@ -14,11 +14,10 @@
 
 //go:build !frps
 
-package plugin
+package client
 
 import (
 	"context"
-	"io"
 	"net"
 
 	libio "github.com/fatedier/golib/io"
@@ -35,7 +34,7 @@ type UnixDomainSocketPlugin struct {
 	UnixAddr *net.UnixAddr
 }
 
-func NewUnixDomainSocketPlugin(options v1.ClientPluginOptions) (p Plugin, err error) {
+func NewUnixDomainSocketPlugin(_ PluginContext, options v1.ClientPluginOptions) (p Plugin, err error) {
 	opts := options.(*v1.UnixDomainSocketPluginOptions)
 
 	unixAddr, errRet := net.ResolveUnixAddr("unix", opts.UnixPath)
@@ -50,20 +49,20 @@ func NewUnixDomainSocketPlugin(options v1.ClientPluginOptions) (p Plugin, err er
 	return
 }
 
-func (uds *UnixDomainSocketPlugin) Handle(ctx context.Context, conn io.ReadWriteCloser, _ net.Conn, extra *ExtraInfo) {
+func (uds *UnixDomainSocketPlugin) Handle(ctx context.Context, connInfo *ConnectionInfo) {
 	xl := xlog.FromContextSafe(ctx)
 	localConn, err := net.DialUnix("unix", nil, uds.UnixAddr)
 	if err != nil {
 		xl.Warnf("dial to uds %s error: %v", uds.UnixAddr, err)
 		return
 	}
-	if extra.ProxyProtocolHeader != nil {
-		if _, err := extra.ProxyProtocolHeader.WriteTo(localConn); err != nil {
+	if connInfo.ProxyProtocolHeader != nil {
+		if _, err := connInfo.ProxyProtocolHeader.WriteTo(localConn); err != nil {
 			return
 		}
 	}
 
-	libio.Join(localConn, conn)
+	libio.Join(localConn, connInfo.Conn)
 }
 
 func (uds *UnixDomainSocketPlugin) Name() string {

pkg/plugin/client/virtual_net.go

@@ -0,0 +1,71 @@
+// Copyright 2025 The frp Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build !frps
+
+package client
+
+import (
+	"context"
+
+	v1 "github.com/fatedier/frp/pkg/config/v1"
+	"github.com/fatedier/frp/pkg/util/xlog"
+)
+
+func init() {
+	Register(v1.PluginVirtualNet, NewVirtualNetPlugin)
+}
+
+type VirtualNetPlugin struct {
+	pluginCtx PluginContext
+	opts      *v1.VirtualNetPluginOptions
+}
+
+func NewVirtualNetPlugin(pluginCtx PluginContext, options v1.ClientPluginOptions) (Plugin, error) {
+	opts := options.(*v1.VirtualNetPluginOptions)
+
+	p := &VirtualNetPlugin{
+		pluginCtx: pluginCtx,
+		opts:      opts,
+	}
+	return p, nil
+}
+
+func (p *VirtualNetPlugin) Handle(ctx context.Context, connInfo *ConnectionInfo) {
+	xl := xlog.FromContextSafe(ctx)
+
+	// Verify if virtual network controller is available
+	if p.pluginCtx.VnetController == nil {
+		return
+	}
+
+	// Register the connection with the controller
+	routeName := p.pluginCtx.Name
+	err := p.pluginCtx.VnetController.RegisterServerConn(ctx, routeName, connInfo.Conn)
+	if err != nil {
+		xl.Errorf("virtual net failed to register server connection: %v", err)
+		return
+	}
+}
+
+func (p *VirtualNetPlugin) Name() string {
+	return v1.PluginVirtualNet
+}
+
+func (p *VirtualNetPlugin) Close() error {
+	if p.pluginCtx.VnetController != nil {
+		p.pluginCtx.VnetController.UnregisterServerConn(p.pluginCtx.Name)
+	}
+	return nil
+}

pkg/plugin/server/http.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package plugin
+package server
 
 import (
 	"bytes"

pkg/plugin/server/manager.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package plugin
+package server
 
 import (
 	"context"

pkg/plugin/server/plugin.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package plugin
+package server
 
 import (
 	"context"

pkg/plugin/server/tracer.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package plugin
+package server
 
 import (
 	"context"

pkg/plugin/server/types.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package plugin
+package server
 
 import (
 	"github.com/fatedier/frp/pkg/msg"

pkg/plugin/visitor/plugin.go

@@ -0,0 +1,58 @@
+// Copyright 2025 The frp Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package visitor
+
+import (
+	"context"
+	"fmt"
+	"net"
+
+	v1 "github.com/fatedier/frp/pkg/config/v1"
+	"github.com/fatedier/frp/pkg/vnet"
+)
+
+type PluginContext struct {
+	Name           string
+	Ctx            context.Context
+	VnetController *vnet.Controller
+	HandleConn     func(net.Conn)
+}
+
+// Creators is used for create plugins to handle connections.
+var creators = make(map[string]CreatorFn)
+
+type CreatorFn func(pluginCtx PluginContext, options v1.VisitorPluginOptions) (Plugin, error)
+
+func Register(name string, fn CreatorFn) {
+	if _, exist := creators[name]; exist {
+		panic(fmt.Sprintf("plugin [%s] is already registered", name))
+	}
+	creators[name] = fn
+}
+
+func Create(pluginName string, pluginCtx PluginContext, options v1.VisitorPluginOptions) (p Plugin, err error) {
+	if fn, ok := creators[pluginName]; ok {
+		p, err = fn(pluginCtx, options)
+	} else {
+		err = fmt.Errorf("plugin [%s] is not registered", pluginName)
+	}
+	return
+}
+
+type Plugin interface {
+	Name() string
+	Start()
+	Close() error
+}

pkg/plugin/visitor/virtual_net.go

@@ -0,0 +1,232 @@
+// Copyright 2025 The frp Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build !frps
+
+package visitor
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net"
+	"sync"
+	"time"
+
+	v1 "github.com/fatedier/frp/pkg/config/v1"
+	netutil "github.com/fatedier/frp/pkg/util/net"
+	"github.com/fatedier/frp/pkg/util/xlog"
+)
+
+func init() {
+	Register(v1.VisitorPluginVirtualNet, NewVirtualNetPlugin)
+}
+
+type VirtualNetPlugin struct {
+	pluginCtx PluginContext
+
+	routes []net.IPNet
+
+	mu             sync.Mutex
+	controllerConn net.Conn
+	closeSignal    chan struct{}
+
+	ctx    context.Context
+	cancel context.CancelFunc
+}
+
+func NewVirtualNetPlugin(pluginCtx PluginContext, options v1.VisitorPluginOptions) (Plugin, error) {
+	opts := options.(*v1.VirtualNetVisitorPluginOptions)
+
+	p := &VirtualNetPlugin{
+		pluginCtx: pluginCtx,
+		routes:    make([]net.IPNet, 0),
+	}
+
+	p.ctx, p.cancel = context.WithCancel(pluginCtx.Ctx)
+
+	if opts.DestinationIP == "" {
+		return nil, errors.New("destinationIP is required")
+	}
+
+	// Parse DestinationIP as a single IP and create a host route
+	ip := net.ParseIP(opts.DestinationIP)
+	if ip == nil {
+		return nil, fmt.Errorf("invalid destination IP address [%s]", opts.DestinationIP)
+	}
+
+	var mask net.IPMask
+	if ip.To4() != nil {
+		mask = net.CIDRMask(32, 32) // /32 for IPv4
+	} else {
+		mask = net.CIDRMask(128, 128) // /128 for IPv6
+	}
+	p.routes = append(p.routes, net.IPNet{IP: ip, Mask: mask})
+
+	return p, nil
+}
+
+func (p *VirtualNetPlugin) Name() string {
+	return v1.VisitorPluginVirtualNet
+}
+
+func (p *VirtualNetPlugin) Start() {
+	xl := xlog.FromContextSafe(p.pluginCtx.Ctx)
+	if p.pluginCtx.VnetController == nil {
+		return
+	}
+
+	routeStr := "unknown"
+	if len(p.routes) > 0 {
+		routeStr = p.routes[0].String()
+	}
+	xl.Infof("Starting VirtualNetPlugin for visitor [%s], attempting to register routes for %s", p.pluginCtx.Name, routeStr)
+
+	go p.run()
+}
+
+func (p *VirtualNetPlugin) run() {
+	xl := xlog.FromContextSafe(p.ctx)
+	reconnectDelay := 10 * time.Second
+
+	for {
+		// Create a signal channel for this connection attempt
+		currentCloseSignal := make(chan struct{})
+
+		// Store the signal channel under lock
+		p.mu.Lock()
+		p.closeSignal = currentCloseSignal
+		p.mu.Unlock()
+
+		select {
+		case <-p.ctx.Done():
+			xl.Infof("VirtualNetPlugin run loop for visitor [%s] stopping (context cancelled before pipe creation).", p.pluginCtx.Name)
+			// Ensure controllerConn from previous loop is cleaned up if necessary
+			p.cleanupControllerConn(xl)
+			return
+		default:
+		}
+
+		controllerConn, pluginConn := net.Pipe()
+
+		// Store controllerConn under lock for cleanup purposes
+		p.mu.Lock()
+		p.controllerConn = controllerConn
+		p.mu.Unlock()
+
+		// Wrap pluginConn using CloseNotifyConn
+		pluginNotifyConn := netutil.WrapCloseNotifyConn(pluginConn, func() {
+			close(currentCloseSignal) // Signal the run loop
+		})
+
+		xl.Infof("Attempting to register client route for visitor [%s]", p.pluginCtx.Name)
+		err := p.pluginCtx.VnetController.RegisterClientRoute(p.ctx, p.pluginCtx.Name, p.routes, controllerConn)
+		if err != nil {
+			xl.Errorf("Failed to register client route for visitor [%s]: %v. Retrying after %v", p.pluginCtx.Name, err, reconnectDelay)
+			p.cleanupPipePair(xl, controllerConn, pluginConn) // Close both ends on registration failure
+
+			// Wait before retrying registration, unless context is cancelled
+			select {
+			case <-time.After(reconnectDelay):
+				continue // Retry the loop
+			case <-p.ctx.Done():
+				xl.Infof("VirtualNetPlugin registration retry wait interrupted for visitor [%s]", p.pluginCtx.Name)
+				return // Exit loop if context is cancelled during wait
+			}
+		}
+
+		xl.Infof("Successfully registered client route for visitor [%s]. Starting connection handler with CloseNotifyConn.", p.pluginCtx.Name)
+
+		// Pass the CloseNotifyConn to HandleConn.
+		// HandleConn is responsible for calling Close() on pluginNotifyConn.
+		p.pluginCtx.HandleConn(pluginNotifyConn)
+
+		// Wait for either the plugin context to be cancelled or the wrapper's Close() to be called via the signal channel.
+		select {
+		case <-p.ctx.Done():
+			xl.Infof("VirtualNetPlugin run loop stopping for visitor [%s] (context cancelled while waiting).", p.pluginCtx.Name)
+			// Context cancelled, ensure controller side is closed if HandleConn didn't close its side yet.
+			p.cleanupControllerConn(xl)
+			return
+		case <-currentCloseSignal:
+			xl.Infof("Detected connection closed via CloseNotifyConn for visitor [%s].", p.pluginCtx.Name)
+			// HandleConn closed the plugin side (pluginNotifyConn). The closeFn was called, closing currentCloseSignal.
+			// We still need to close the controller side.
+			p.cleanupControllerConn(xl)
+
+			// Add a delay before attempting to reconnect, respecting context cancellation.
+			xl.Infof("Waiting %v before attempting reconnection for visitor [%s]...", reconnectDelay, p.pluginCtx.Name)
+			select {
+			case <-time.After(reconnectDelay):
+				// Delay completed, loop will continue.
+			case <-p.ctx.Done():
+				xl.Infof("VirtualNetPlugin reconnection delay interrupted for visitor [%s]", p.pluginCtx.Name)
+				return // Exit loop if context is cancelled during wait
+			}
+			// Loop will continue to reconnect.
+		}
+
+		// Loop will restart, context check at the beginning of the loop is sufficient.
+		xl.Infof("Re-establishing virtual connection for visitor [%s]...", p.pluginCtx.Name)
+	}
+}
+
+// cleanupControllerConn closes the current controllerConn (if it exists) under lock.
+func (p *VirtualNetPlugin) cleanupControllerConn(xl *xlog.Logger) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	if p.controllerConn != nil {
+		xl.Debugf("Cleaning up controllerConn for visitor [%s]", p.pluginCtx.Name)
+		p.controllerConn.Close()
+		p.controllerConn = nil
+	}
+	// Also clear the closeSignal reference for the completed/cancelled connection attempt
+	p.closeSignal = nil
+}
+
+// cleanupPipePair closes both ends of a pipe, used typically when registration fails.
+func (p *VirtualNetPlugin) cleanupPipePair(xl *xlog.Logger, controllerConn, pluginConn net.Conn) {
+	xl.Debugf("Cleaning up pipe pair for visitor [%s] after registration failure", p.pluginCtx.Name)
+	controllerConn.Close()
+	pluginConn.Close()
+	p.mu.Lock()
+	p.controllerConn = nil // Ensure field is nil if it was briefly set
+	p.closeSignal = nil    // Ensure field is nil if it was briefly set
+	p.mu.Unlock()
+}
+
+// Close initiates the plugin shutdown.
+func (p *VirtualNetPlugin) Close() error {
+	xl := xlog.FromContextSafe(p.pluginCtx.Ctx) // Use base context for close logging
+	xl.Infof("Closing VirtualNetPlugin for visitor [%s]", p.pluginCtx.Name)
+
+	// 1. Signal the run loop goroutine to stop via context cancellation.
+	p.cancel()
+
+	// 2. Unregister the route from the controller.
+	// This might implicitly cause the VnetController to close its end of the pipe (controllerConn).
+	if p.pluginCtx.VnetController != nil {
+		p.pluginCtx.VnetController.UnregisterClientRoute(p.pluginCtx.Name)
+		xl.Infof("Unregistered client route for visitor [%s]", p.pluginCtx.Name)
+	} else {
+		xl.Warnf("VnetController is nil during close for visitor [%s], cannot unregister route", p.pluginCtx.Name)
+	}
+
+	// 3. Explicitly close the controller side of the pipe managed by this plugin.
+	// This ensures the pipe is broken even if the run loop is stuck or HandleConn hasn't closed its end.
+	p.cleanupControllerConn(xl)
+	xl.Infof("Finished cleaning up connections during close for visitor [%s]", p.pluginCtx.Name)
+
+	return nil
+}

pkg/util/version/version.go

@@ -14,7 +14,7 @@
 
 package version
 
-var version = "0.61.2"
+var version = "0.62.0"
 
 func Full() string {
 	return version

pkg/vnet/controller.go

@@ -0,0 +1,360 @@
+// Copyright 2025 The frp Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package vnet
+
+import (
+	"context"
+	"encoding/base64"
+	"fmt"
+	"io"
+	"net"
+	"sync"
+
+	"github.com/fatedier/golib/pool"
+	"github.com/songgao/water/waterutil"
+	"golang.org/x/net/ipv4"
+	"golang.org/x/net/ipv6"
+
+	v1 "github.com/fatedier/frp/pkg/config/v1"
+	"github.com/fatedier/frp/pkg/util/log"
+	"github.com/fatedier/frp/pkg/util/xlog"
+)
+
+const (
+	maxPacketSize = 1420
+)
+
+type Controller struct {
+	addr string
+
+	tun          io.ReadWriteCloser
+	clientRouter *clientRouter // Route based on destination IP (client mode)
+	serverRouter *serverRouter // Route based on source IP (server mode)
+}
+
+func NewController(cfg v1.VirtualNetConfig) *Controller {
+	return &Controller{
+		addr:         cfg.Address,
+		clientRouter: newClientRouter(),
+		serverRouter: newServerRouter(),
+	}
+}
+
+func (c *Controller) Init() error {
+	tunDevice, err := OpenTun(context.Background(), c.addr)
+	if err != nil {
+		return err
+	}
+	c.tun = tunDevice
+	return nil
+}
+
+func (c *Controller) Run() error {
+	conn := c.tun
+
+	for {
+		buf := pool.GetBuf(maxPacketSize)
+		n, err := conn.Read(buf)
+		if err != nil {
+			pool.PutBuf(buf)
+			log.Warnf("vnet read from tun error: %v", err)
+			return err
+		}
+
+		c.handlePacket(buf[:n])
+		pool.PutBuf(buf)
+	}
+}
+
+// handlePacket processes a single packet. The caller is responsible for managing the buffer.
+func (c *Controller) handlePacket(buf []byte) {
+	log.Tracef("vnet read from tun [%d]: %s", len(buf), base64.StdEncoding.EncodeToString(buf))
+
+	var src, dst net.IP
+	switch {
+	case waterutil.IsIPv4(buf):
+		header, err := ipv4.ParseHeader(buf)
+		if err != nil {
+			log.Warnf("parse ipv4 header error:", err)
+			return
+		}
+		src = header.Src
+		dst = header.Dst
+		log.Tracef("%s >> %s %d/%-4d %-4x %d",
+			header.Src, header.Dst,
+			header.Len, header.TotalLen, header.ID, header.Flags)
+	case waterutil.IsIPv6(buf):
+		header, err := ipv6.ParseHeader(buf)
+		if err != nil {
+			log.Warnf("parse ipv6 header error:", err)
+			return
+		}
+		src = header.Src
+		dst = header.Dst
+		log.Tracef("%s >> %s %d %d",
+			header.Src, header.Dst,
+			header.PayloadLen, header.TrafficClass)
+	default:
+		log.Tracef("unknown packet, discarded(%d)", len(buf))
+		return
+	}
+
+	targetConn, err := c.clientRouter.findConn(dst)
+	if err == nil {
+		if err := WriteMessage(targetConn, buf); err != nil {
+			log.Warnf("write to client target conn error: %v", err)
+		}
+		return
+	}
+
+	targetConn, err = c.serverRouter.findConnBySrc(dst)
+	if err == nil {
+		if err := WriteMessage(targetConn, buf); err != nil {
+			log.Warnf("write to server target conn error: %v", err)
+		}
+		return
+	}
+
+	log.Tracef("no route found for packet from %s to %s", src, dst)
+}
+
+func (c *Controller) Stop() error {
+	return c.tun.Close()
+}
+
+// Client connection read loop
+func (c *Controller) readLoopClient(ctx context.Context, conn io.ReadWriteCloser) {
+	xl := xlog.FromContextSafe(ctx)
+	for {
+		data, err := ReadMessage(conn)
+		if err != nil {
+			xl.Warnf("client read error: %v", err)
+			return
+		}
+
+		if len(data) == 0 {
+			continue
+		}
+
+		switch {
+		case waterutil.IsIPv4(data):
+			header, err := ipv4.ParseHeader(data)
+			if err != nil {
+				xl.Warnf("parse ipv4 header error: %v", err)
+				continue
+			}
+			xl.Tracef("%s >> %s %d/%-4d %-4x %d",
+				header.Src, header.Dst,
+				header.Len, header.TotalLen, header.ID, header.Flags)
+		case waterutil.IsIPv6(data):
+			header, err := ipv6.ParseHeader(data)
+			if err != nil {
+				xl.Warnf("parse ipv6 header error: %v", err)
+				continue
+			}
+			xl.Tracef("%s >> %s %d %d",
+				header.Src, header.Dst,
+				header.PayloadLen, header.TrafficClass)
+		default:
+			xl.Tracef("unknown packet, discarded(%d)", len(data))
+			continue
+		}
+
+		xl.Tracef("vnet write to tun (client) [%d]: %s", len(data), base64.StdEncoding.EncodeToString(data))
+		_, err = c.tun.Write(data)
+		if err != nil {
+			xl.Warnf("client write tun error: %v", err)
+		}
+	}
+}
+
+// Server connection read loop
+func (c *Controller) readLoopServer(ctx context.Context, conn io.ReadWriteCloser) {
+	xl := xlog.FromContextSafe(ctx)
+	for {
+		data, err := ReadMessage(conn)
+		if err != nil {
+			xl.Warnf("server read error: %v", err)
+			return
+		}
+
+		if len(data) == 0 {
+			continue
+		}
+
+		// Register source IP to connection mapping
+		if waterutil.IsIPv4(data) || waterutil.IsIPv6(data) {
+			var src net.IP
+			if waterutil.IsIPv4(data) {
+				header, err := ipv4.ParseHeader(data)
+				if err == nil {
+					src = header.Src
+					c.serverRouter.registerSrcIP(src, conn)
+				}
+			} else {
+				header, err := ipv6.ParseHeader(data)
+				if err == nil {
+					src = header.Src
+					c.serverRouter.registerSrcIP(src, conn)
+				}
+			}
+		}
+
+		xl.Tracef("vnet write to tun (server) [%d]: %s", len(data), base64.StdEncoding.EncodeToString(data))
+		_, err = c.tun.Write(data)
+		if err != nil {
+			xl.Warnf("server write tun error: %v", err)
+		}
+	}
+}
+
+// RegisterClientRoute Register client route (based on destination IP CIDR)
+func (c *Controller) RegisterClientRoute(ctx context.Context, name string, routes []net.IPNet, conn io.ReadWriteCloser) error {
+	if err := c.clientRouter.addRoute(name, routes, conn); err != nil {
+		return err
+	}
+	go c.readLoopClient(ctx, conn)
+	return nil
+}
+
+// RegisterServerConn Register server connection (dynamically associates with source IPs)
+func (c *Controller) RegisterServerConn(ctx context.Context, name string, conn io.ReadWriteCloser) error {
+	if err := c.serverRouter.addConn(name, conn); err != nil {
+		return err
+	}
+	go c.readLoopServer(ctx, conn)
+	return nil
+}
+
+// UnregisterServerConn Remove server connection from routing table
+func (c *Controller) UnregisterServerConn(name string) {
+	c.serverRouter.delConn(name)
+}
+
+// UnregisterClientRoute Remove client route from routing table
+func (c *Controller) UnregisterClientRoute(name string) {
+	c.clientRouter.delRoute(name)
+}
+
+// ParseRoutes Convert route strings to IPNet objects
+func ParseRoutes(routeStrings []string) ([]net.IPNet, error) {
+	routes := make([]net.IPNet, 0, len(routeStrings))
+	for _, r := range routeStrings {
+		_, ipNet, err := net.ParseCIDR(r)
+		if err != nil {
+			return nil, fmt.Errorf("parse route %s error: %v", r, err)
+		}
+		routes = append(routes, *ipNet)
+	}
+	return routes, nil
+}
+
+// Client router (based on destination IP routing)
+type clientRouter struct {
+	routes map[string]*routeElement
+	mu     sync.RWMutex
+}
+
+func newClientRouter() *clientRouter {
+	return &clientRouter{
+		routes: make(map[string]*routeElement),
+	}
+}
+
+func (r *clientRouter) addRoute(name string, routes []net.IPNet, conn io.ReadWriteCloser) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.routes[name] = &routeElement{
+		name:   name,
+		routes: routes,
+		conn:   conn,
+	}
+	return nil
+}
+
+func (r *clientRouter) findConn(dst net.IP) (io.Writer, error) {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	for _, re := range r.routes {
+		for _, route := range re.routes {
+			if route.Contains(dst) {
+				return re.conn, nil
+			}
+		}
+	}
+	return nil, fmt.Errorf("no route found for destination %s", dst)
+}
+
+func (r *clientRouter) delRoute(name string) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	delete(r.routes, name)
+}
+
+// Server router (based on source IP routing)
+type serverRouter struct {
+	namedConns map[string]io.ReadWriteCloser // Name to connection mapping
+	srcIPConns map[string]io.Writer          // Source IP string to connection mapping
+	mu         sync.RWMutex
+}
+
+func newServerRouter() *serverRouter {
+	return &serverRouter{
+		namedConns: make(map[string]io.ReadWriteCloser),
+		srcIPConns: make(map[string]io.Writer),
+	}
+}
+
+func (r *serverRouter) addConn(name string, conn io.ReadWriteCloser) error {
+	r.mu.Lock()
+	original, ok := r.namedConns[name]
+	r.namedConns[name] = conn
+	r.mu.Unlock()
+	if ok {
+		// Close the original connection if it exists
+		_ = original.Close()
+	}
+	return nil
+}
+
+func (r *serverRouter) findConnBySrc(src net.IP) (io.Writer, error) {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	conn, exists := r.srcIPConns[src.String()]
+	if !exists {
+		return nil, fmt.Errorf("no route found for source %s", src)
+	}
+	return conn, nil
+}
+
+func (r *serverRouter) registerSrcIP(src net.IP, conn io.Writer) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.srcIPConns[src.String()] = conn
+}
+
+func (r *serverRouter) delConn(name string) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	delete(r.namedConns, name)
+	// Note: We don't delete mappings from srcIPConns because we don't know which source IPs are associated with this connection
+	// This might cause dangling references, but they will be overwritten on new connections or restart
+}
+
+type routeElement struct {
+	name   string
+	routes []net.IPNet
+	conn   io.ReadWriteCloser
+}

pkg/vnet/message.go

@@ -0,0 +1,81 @@
+// Copyright 2025 The frp Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package vnet
+
+import (
+	"encoding/binary"
+	"fmt"
+	"io"
+)
+
+// Maximum message size
+const (
+	maxMessageSize = 1024 * 1024 // 1MB
+)
+
+// Format: [length(4 bytes)][data(length bytes)]
+
+// ReadMessage reads a framed message from the reader
+func ReadMessage(r io.Reader) ([]byte, error) {
+	// Read length (4 bytes)
+	var length uint32
+	err := binary.Read(r, binary.LittleEndian, &length)
+	if err != nil {
+		return nil, fmt.Errorf("read message length error: %v", err)
+	}
+
+	// Check length to prevent DoS
+	if length == 0 {
+		return nil, fmt.Errorf("message length is 0")
+	}
+	if length > maxMessageSize {
+		return nil, fmt.Errorf("message too large: %d > %d", length, maxMessageSize)
+	}
+
+	// Read message data
+	data := make([]byte, length)
+	_, err = io.ReadFull(r, data)
+	if err != nil {
+		return nil, fmt.Errorf("read message data error: %v", err)
+	}
+
+	return data, nil
+}
+
+// WriteMessage writes a framed message to the writer
+func WriteMessage(w io.Writer, data []byte) error {
+	// Get data length
+	length := uint32(len(data))
+	if length == 0 {
+		return fmt.Errorf("message data length is 0")
+	}
+	if length > maxMessageSize {
+		return fmt.Errorf("message too large: %d > %d", length, maxMessageSize)
+	}
+
+	// Write length
+	err := binary.Write(w, binary.LittleEndian, length)
+	if err != nil {
+		return fmt.Errorf("write message length error: %v", err)
+	}
+
+	// Write message data
+	_, err = w.Write(data)
+	if err != nil {
+		return fmt.Errorf("write message data error: %v", err)
+	}
+
+	return nil
+}

pkg/vnet/tun.go

@@ -0,0 +1,77 @@
+// Copyright 2025 The frp Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package vnet
+
+import (
+	"context"
+	"io"
+
+	"github.com/fatedier/golib/pool"
+	"golang.zx2c4.com/wireguard/tun"
+)
+
+const (
+	offset = 16
+)
+
+type TunDevice interface {
+	io.ReadWriteCloser
+}
+
+func OpenTun(ctx context.Context, addr string) (TunDevice, error) {
+	td, err := openTun(ctx, addr)
+	if err != nil {
+		return nil, err
+	}
+	return &tunDeviceWrapper{dev: td}, nil
+}
+
+type tunDeviceWrapper struct {
+	dev tun.Device
+}
+
+func (d *tunDeviceWrapper) Read(p []byte) (int, error) {
+	buf := pool.GetBuf(len(p) + offset)
+	defer pool.PutBuf(buf)
+
+	sz := make([]int, 1)
+
+	n, err := d.dev.Read([][]byte{buf}, sz, offset)
+	if err != nil {
+		return 0, err
+	}
+	if n == 0 {
+		return 0, io.EOF
+	}
+
+	dataSize := sz[0]
+	if dataSize > len(p) {
+		dataSize = len(p)
+	}
+	copy(p, buf[offset:offset+dataSize])
+	return dataSize, nil
+}
+
+func (d *tunDeviceWrapper) Write(p []byte) (int, error) {
+	buf := pool.GetBuf(len(p) + offset)
+	defer pool.PutBuf(buf)
+
+	copy(buf[offset:], p)
+	return d.dev.Write([][]byte{buf}, offset)
+}
+
+func (d *tunDeviceWrapper) Close() error {
+	return d.dev.Close()
+}

pkg/vnet/tun_darwin.go

@@ -0,0 +1,85 @@
+// Copyright 2025 The frp Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package vnet
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"os/exec"
+
+	"golang.zx2c4.com/wireguard/tun"
+)
+
+const (
+	defaultTunName = "utun"
+	defaultMTU     = 1420
+)
+
+func openTun(_ context.Context, addr string) (tun.Device, error) {
+	dev, err := tun.CreateTUN(defaultTunName, defaultMTU)
+	if err != nil {
+		return nil, err
+	}
+
+	name, err := dev.Name()
+	if err != nil {
+		return nil, err
+	}
+
+	ip, ipNet, err := net.ParseCIDR(addr)
+	if err != nil {
+		return nil, err
+	}
+
+	// Calculate a peer IP for the point-to-point tunnel
+	peerIP := generatePeerIP(ip)
+
+	// Configure the interface with proper point-to-point addressing
+	if err = exec.Command("ifconfig", name, "inet", ip.String(), peerIP.String(), "mtu", fmt.Sprint(defaultMTU), "up").Run(); err != nil {
+		return nil, err
+	}
+
+	// Add default route for the tunnel subnet
+	routes := []net.IPNet{*ipNet}
+	if err = addRoutes(name, routes); err != nil {
+		return nil, err
+	}
+	return dev, nil
+}
+
+// generatePeerIP creates a peer IP for the point-to-point tunnel
+// by incrementing the last octet of the IP
+func generatePeerIP(ip net.IP) net.IP {
+	// Make a copy to avoid modifying the original
+	peerIP := make(net.IP, len(ip))
+	copy(peerIP, ip)
+
+	// Increment the last octet
+	peerIP[len(peerIP)-1]++
+
+	return peerIP
+}
+
+// addRoutes configures system routes for the TUN interface
+func addRoutes(ifName string, routes []net.IPNet) error {
+	for _, route := range routes {
+		routeStr := route.String()
+		if err := exec.Command("route", "add", "-net", routeStr, "-interface", ifName).Run(); err != nil {
+			return err
+		}
+	}
+	return nil
+}

pkg/vnet/tun_linux.go

@@ -0,0 +1,84 @@
+// Copyright 2025 The frp Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package vnet
+
+import (
+	"context"
+	"fmt"
+	"net"
+
+	"github.com/vishvananda/netlink"
+	"golang.zx2c4.com/wireguard/tun"
+)
+
+const (
+	defaultTunName = "utun"
+	defaultMTU     = 1420
+)
+
+func openTun(_ context.Context, addr string) (tun.Device, error) {
+	dev, err := tun.CreateTUN(defaultTunName, defaultMTU)
+	if err != nil {
+		return nil, err
+	}
+
+	name, err := dev.Name()
+	if err != nil {
+		return nil, err
+	}
+
+	ifn, err := net.InterfaceByName(name)
+	if err != nil {
+		return nil, err
+	}
+
+	link, err := netlink.LinkByName(name)
+	if err != nil {
+		return nil, err
+	}
+
+	ip, cidr, err := net.ParseCIDR(addr)
+	if err != nil {
+		return nil, err
+	}
+	if err := netlink.AddrAdd(link, &netlink.Addr{
+		IPNet: &net.IPNet{
+			IP:   ip,
+			Mask: cidr.Mask,
+		},
+	}); err != nil {
+		return nil, err
+	}
+
+	if err := netlink.LinkSetUp(link); err != nil {
+		return nil, err
+	}
+
+	if err = addRoutes(ifn, cidr); err != nil {
+		return nil, err
+	}
+	return dev, nil
+}
+
+func addRoutes(ifn *net.Interface, cidr *net.IPNet) error {
+	r := netlink.Route{
+		Dst:       cidr,
+		LinkIndex: ifn.Index,
+	}
+	if err := netlink.RouteReplace(&r); err != nil {
+		return fmt.Errorf("add route to %v error: %v", r.Dst, err)
+	}
+	return nil
+}

pkg/vnet/tun_unsupported.go

@@ -0,0 +1,27 @@
+// Copyright 2025 The frp Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build !darwin && !linux
+
+package vnet
+
+import (
+	"context"
+	"fmt"
+	"runtime"
+)
+
+func openTun(ctx context.Context) (TunDevice, error) {
+	return nil, fmt.Errorf("virtual net is not supported on this platform (%s/%s)", runtime.GOOS, runtime.GOARCH)
+}