vproxy

中文文档

Intro

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

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

Features

1. TCP Loadbalancer with TLS termination
2. HTTP/1.x and HTTP/2 Loadbalancer with Host header consideration
3. Other tcp based protocol loadbalancer, such as grpc, dubbo
4. Socks5 server
5. DNS server and customizable A|AAAA records
6. Kubernetes integration
7. Many other standalone extended apps, such as WebSocksProxyAgent and WebSocksProxyServer
8. 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:

make init

to initiate submodules and some other init work.

jar package

./gradlew clean jar
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:

# requires virtualbox installed

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

ui

vproxy provides some ui tools.

./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

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

maven

<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

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

netty

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.