vproxy

Intro

VProxy is a zero-dependency loadbalancer and sdn virtual switch. The project only requires Java 22 to run.

Clone it, compile it, then everything is ready for running.

Features

TCP Loadbalancer with TLS termination
HTTP/1.x and HTTP/2 Loadbalancer with Host header consideration
Other tcp based protocol loadbalancer, such as grpc, dubbo
Socks5 server
DNS server and customizable A|AAAA records
Kubernetes integration
Many other standalone extended apps, such as WebSocksProxyAgent and WebSocksProxyServer
SDN virtual switch with full TCP/IP stack support

Make

use pre-built releases

See the release page.

#### For linux

Use the latest vproxy-linux binary file in release page.

Or

Use the jlink built runtime here.

#### For macos

Use the latest vproxy-macos binary file in release page.

#### For windows

Java runtime can be found here.

#### For musl

Use the jlink built runtime here.

build prerequisites

Run:

shell
make init

to initiate submodules and some other init work.

jar package

./gradlew clean shadowjar
java -jar build/libs/vproxy.jar -Deploy=HelloWorld

jlink

make jlink
./build/image/bin/vproxy -Deploy=HelloWorld

docker

# make docker
docker run -it --rm vproxyio/vproxy -Deploy=HelloWorld

graal native-image

make image
./vproxy -Deploy=HelloWorld

native fds impl

Only macos(bsd)/linux supported.

make vfdposix
java -Dvfd=posix -Djava.library.path=./base/src/main/c -jar build/libs/vproxy.jar -Deploy=HelloWorld

And there’s a special version for windows to support Tap devices: -Dvfd=windows, however the normal fds and event loop are still based on jdk selector channel.

make vfdwindows
java -Dvfd=windows -Djava.library.path=./base/src/main/c -jar build/libs/vproxy.jar -Deploy=HelloWorld

Windows TAP depends on OpenVPN TAP Driver. MacOS TAP depends on tuntaposx.

MacOS TUN, Linux TAP and TUN has no extra dependencies.

xdp

It’s recommended to run a kernel with minimum version 5.10 (or at least 5.4) in order to use xdp support in the switch module.
If using a lower version, you cannot share the same umem with different xdp interfaces.

To build the xdp support, you will need these packages: apt-get install -y linux-headers-$(uname -r) build-essential libelf-dev clang llvm, then:

make vpxdp

Or compile it inside a docker container on a non-Linux platform:

make vpxdp-linux

test

Run test cases:

./gradlew runTest

Run test cases in docker:

make dockertest

Test vswitch, docker network plugin, vpctl, k8s controller:

shell
# requires virtualbox installed

cd ./misc/auto-setup/
./auto-setup.sh
./auto-verify.sh

vproxy provides some ui tools.

shell
./gradlew ui:jar
java -cp ./ui/build/libs/vproxy-ui.jar $mainClassName

Current available ui tools:

1. io.vproxy.ui.calculator.CalculatorMain: an IPv4 network calculator

Aim

Zero dependency: all dependencies are implemented in vproxy subprojects.
Simple: keep code simple and clear.
Modifiable when running: no need to reload for configuration update.
Fast: performance is one of our main priorities.
TCP Loadbalancer: we now support TCP and TCP based protocols, also allow your own protocols.
Kubernetes: integrate vproxy resources into k8s.
SDN: modifying and forwarding packets with flows and routes.

How to use

use as a library

gradle

groovy
implementation group: 'io.vproxy', name: 'vproxy-adaptor-netty', version: '1.0.0-BETA-12'
// all available artifacts: dep, base, adaptor-netty, adaptor-vertx

maven

xml
<dependency>
    <groupId>io.vproxy</groupId>
    <artifactId>vproxy-adaptor-netty</artifactId>
    <version>1.0.0-BETA-12</version>
</dependency>
<!-- all available artifacts: dep, base, adaptor-netty, adaptor-vertx -->

module-info.java

java
requires io.vproxy.dep;
requires io.vproxy.base;
requires io.vproxy.adaptor.netty;
requires io.vproxy.adaptor.vertx;

netty

java
var acceptelg = new VProxyEventLoopGroup();
var elg = new VProxyEventLoopGroup(4);
var bootstrap = new ServerBootstrap();
bootstrap
    .channel(VProxyInetServerSocketChannel.class)
    .childHandler(new ChannelInitializer<>() {
        @Override
        protected void initChannel(Channel ch) {
            ChannelPipeline p = ch.pipeline();
            p.addLast(new HttpServerCodec());
            p.addLast(new HttpHelloWorldServerHandler());
        }
    });
bootstrap.group(acceptelg, elg);
bootstrap.bind(hostname, port).sync();

use vproxy with kubernetes

Add crd, launch vproxy and controller

kubectl apply -f https://github.com/vproxy-tools/vpctl/blob/master/misc/crd.yaml
kubectl apply -f https://github.com/vproxy-tools/vpctl/blob/master/misc/k8s-vproxy.yaml

Launch the example app

kubectl apply -f https://github.com/vproxy-tools/vpctl/blob/master/misc/cr-example.yaml

Detailed info can be found here.

vpctl

A command line client application is provided to manipulate the vproxy instance. You may see more info in vpctl repo.

This tool is fully tested and simple to use. Some examples are provided in the tool repo for reference.

Simple mode

You can start a simple loadbalancer in one command:

java -Deploy=Simple -jar vproxy.jar \  
                bind {port} \
                backend {host1:port1,host2:port2} \
                [ssl {path of cert1,cert2} {path of key}] \
                [protocol {...}] \

Use help to view the parameters.

Standard mode

Use help to view the launching parameters.

After launching, you may use help, man, man ${action}, man ${resource}, man ${resource} ${action} to check the command manual. Also you can use System: help to check the system commands.

After launching vproxy, you may use System: to run some system commands, You may create http-controllers and resp-controllers. Then you can operate the vproxy instance using curl or redis-cli. You may also operate the vproxy instance directly using standard input (stdin).

See command.md and api doc for more info.

Doc

how-to-use.md: How to use config file and controllers.
api.yaml: api doc for http-controller in swagger format.
lb-example.md: An example about running a loadbalancer.
architecture.md: Something about the architecture.
extended-app.md: The usage of extended applications.
websocks.md: The WebSocks Protocol.
vproxy-kcp-tunnel.md: The KCP Tunnel Protocol.
using-application-layer-protocols.md: About how to use (customized) application layer protocols.
vpws-direct-relay.md: How to use direct-relay in vpws-agent.

Products

VProxy Soft Switch (vpss): A soft router (switch) for your home.

Contribute

Currently only I myself is working on this project. I would be very happy if you want to join :)

Thanks to those who had committed PR, see CONTRIB.

The CDN acceleration and security protection of this project are sponsored by Tencent EdgeOne.
本项目 CDN 加速及安全防护由 Tencent EdgeOne 赞助