{"id":20406809,"url":"https://github.com/wkgcass/vproxy","last_synced_at":"2025-04-04T22:01:14.288Z","repository":{"id":48857559,"uuid":"166255932","full_name":"wkgcass/vproxy","owner":"wkgcass","description":"1) proxy: LB,DNS,Socks. 2) k8s: CRD and Controllers. 3) sdn: TCP/IP Stack + Flow Tables.","archived":false,"fork":false,"pushed_at":"2025-03-23T17:24:21.000Z","size":9118,"stargazers_count":159,"open_issues_count":6,"forks_count":40,"subscribers_count":13,"default_branch":"dev","last_synced_at":"2025-03-28T21:00:41.803Z","etag":null,"topics":["kubernetes","loadbalancer","panama","sdn"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wkgcass.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-17T16:14:58.000Z","updated_at":"2025-03-28T06:07:37.000Z","dependencies_parsed_at":"2023-10-26T23:22:10.968Z","dependency_job_id":"2c66686d-f2a6-446c-836a-398e17615e2e","html_url":"https://github.com/wkgcass/vproxy","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wkgcass%2Fvproxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wkgcass%2Fvproxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wkgcass%2Fvproxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wkgcass%2Fvproxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wkgcass","download_url":"https://codeload.github.com/wkgcass/vproxy/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247256093,"owners_count":20909240,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kubernetes","loadbalancer","panama","sdn"],"created_at":"2024-11-15T05:19:27.714Z","updated_at":"2025-04-04T22:01:14.087Z","avatar_url":"https://github.com/wkgcass.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vproxy\n\n[![Build Status](https://github.com/wkgcass/vproxy/actions/workflows/ci.yaml/badge.svg?branch=dev)](https://github.com/wkgcass/vproxy/actions/workflows/ci.yaml)\n\n[中文文档](https://github.com/wkgcass/vproxy/blob/master/README_ZH.md)\n\n## Intro\n\nVProxy is a zero-dependency loadbalancer and sdn virtual switch. The project only requires Java 21 to run.\n\nClone it, compile it, then everything is ready for running.\n\n## Features\n\n1. TCP Loadbalancer with TLS termination\n2. HTTP/1.x and HTTP/2 Loadbalancer with `Host` header consideration\n3. Other tcp based protocol loadbalancer, such as grpc, dubbo\n4. Socks5 server\n5. DNS server and customizable A|AAAA records\n6. Kubernetes integration\n7. Many other standalone extended apps, such as `WebSocksProxyAgent` and `WebSocksProxyServer`\n8. SDN virtual switch with full TCP/IP stack support\n\n## Make\n\n\u003cdetails\u003e\u003csummary\u003euse pre-built releases\u003c/summary\u003e\n\n\u003cbr\u003e\n\nSee the [release page](https://github.com/wkgcass/vproxy/releases).\n\n#### For linux\n\nUse the latest `vproxy-linux` binary file in release page.\n\nOr\n\nUse the jlink built runtime [here](https://github.com/wkgcass/vproxy/releases/download/1.0.0-BETA-12/vproxy-runtime-linux.tar.gz).\n\n#### For macos\n\nUse the latest `vproxy-macos` binary file in release page.\n\n#### For windows\n\nJava runtime can be found [here](https://adoptium.net/releases.html?variant=openjdk17\u0026jvmVariant=hotspot).\n\n#### For musl\n\nUse the jlink built runtime [here](https://github.com/wkgcass/vproxy/releases/download/1.0.0-BETA-12/vproxy-runtime-musl.tar.gz).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003ebuild prerequisites\u003c/summary\u003e\n\nRun:  \n```shell\nmake init\n```  \nto initiate submodules and some other init work. \n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003ejar package\u003c/summary\u003e\n\n\u003cbr\u003e\n\n```\n./gradlew clean jar\njava -jar build/libs/vproxy.jar -Deploy=HelloWorld\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003ejlink\u003c/summary\u003e\n\n\u003cbr\u003e\n\n```\nmake jlink\n./build/image/bin/vproxy -Deploy=HelloWorld\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003edocker\u003c/summary\u003e\n\n\u003cbr\u003e\n\n```\n# make docker\ndocker run -it --rm vproxyio/vproxy -Deploy=HelloWorld\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003egraal native-image\u003c/summary\u003e\n\n\u003cbr\u003e\n\n```\nmake image\n./vproxy -Deploy=HelloWorld\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003enative fds impl\u003c/summary\u003e\n\n\u003cbr\u003e\n\nOnly macos(bsd)/linux supported.\n\n```\nmake vfdposix\njava -Dvfd=posix -Djava.library.path=./base/src/main/c -jar build/libs/vproxy.jar -Deploy=HelloWorld\n```\n\nAnd 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.\n\n```\nmake vfdwindows\njava -Dvfd=windows -Djava.library.path=./base/src/main/c -jar build/libs/vproxy.jar -Deploy=HelloWorld\n```\n\nWindows TAP depends on OpenVPN TAP Driver. MacOS TAP depends on tuntaposx.\n\nMacOS TUN, Linux TAP and TUN has no extra dependencies.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003exdp\u003c/summary\u003e\n\n\u003cbr\u003e\n\nIt'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.  \nIf using a lower version, you cannot share the same umem with different xdp interfaces.\n\nTo build the xdp support, you will need these packages: `apt-get install -y linux-headers-$(uname -r) build-essential libelf-dev clang llvm`, then:\n\n```\nmake vpxdp\n```\n\nOr compile it inside a docker container on a non-Linux platform:\n\n```\nmake vpxdp-linux\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003etest\u003c/summary\u003e\n\n\u003cbr\u003e\n\nRun test cases:\n\n```\n./gradlew runTest\n```\n\nRun test cases in docker:\n\n```\nmake dockertest\n```\n\nTest vswitch, docker network plugin, vpctl, k8s controller:\n\n```shell\n# requires virtualbox installed\n\ncd ./misc/auto-setup/\n./auto-setup.sh\n./auto-verify.sh\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eui\u003c/summary\u003e\n\n\u003cbr\u003e\n\nvproxy provides some ui tools.\n\n```shell\n./gradlew ui:jar\njava -cp ./ui/build/libs/vproxy-ui.jar $mainClassName\n```\n\nCurrent available ui tools:\n\n1. `io.vproxy.ui.calculator.CalculatorMain`: an IPv4 network calculator\n\n\u003c/details\u003e\n\n## Aim\n\n* Zero dependency: all dependencies are implemented in vproxy subprojects.\n* Simple: keep code simple and clear.\n* Modifiable when running: no need to reload for configuration update.\n* Fast: performance is one of our main priorities.\n* TCP Loadbalancer: we now support TCP and TCP based protocols, also allow your own protocols.\n* Kubernetes: integrate vproxy resources into k8s.\n* SDN: modifying and forwarding packets with flows and routes.\n\n## How to use\n\n\u003cdetails\u003e\u003csummary\u003euse as a library\u003c/summary\u003e\n\n\u003cbr\u003e\n\n**gradle**\n\n```groovy\nimplementation group: 'io.vproxy', name: 'vproxy-adaptor-netty', version: '1.0.0-BETA-12'\n// all available artifacts: dep, base, adaptor-netty, adaptor-vertx\n```\n\n**maven**\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.vproxy\u003c/groupId\u003e\n    \u003cartifactId\u003evproxy-adaptor-netty\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.0-BETA-12\u003c/version\u003e\n\u003c/dependency\u003e\n\u003c!-- all available artifacts: dep, base, adaptor-netty, adaptor-vertx --\u003e\n```\n\n**module-info.java**\n\n```java\nrequires io.vproxy.dep;\nrequires io.vproxy.base;\nrequires io.vproxy.adaptor.netty;\nrequires io.vproxy.adaptor.vertx;\n```\n\n**netty**\n\n```java\nvar acceptelg = new VProxyEventLoopGroup();\nvar elg = new VProxyEventLoopGroup(4);\nvar bootstrap = new ServerBootstrap();\nbootstrap\n    .channel(VProxyInetServerSocketChannel.class)\n    .childHandler(new ChannelInitializer\u003c\u003e() {\n        @Override\n        protected void initChannel(Channel ch) {\n            ChannelPipeline p = ch.pipeline();\n            p.addLast(new HttpServerCodec());\n            p.addLast(new HttpHelloWorldServerHandler());\n        }\n    });\nbootstrap.group(acceptelg, elg);\nbootstrap.bind(hostname, port).sync();\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003euse vproxy with kubernetes\u003c/summary\u003e\n\n\u003cbr\u003e\n\nAdd crd, launch vproxy and controller\n\n```\nkubectl apply -f https://github.com/vproxy-tools/vpctl/blob/master/misc/crd.yaml\nkubectl apply -f https://github.com/vproxy-tools/vpctl/blob/master/misc/k8s-vproxy.yaml\n```\n\nLaunch the example app\n\n```\nkubectl apply -f https://github.com/vproxy-tools/vpctl/blob/master/misc/cr-example.yaml\n```\n\nDetailed info can be found [here](https://github.com/vproxy-tools/vpctl/blob/master/README.md).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003evpctl\u003c/summary\u003e\n\n\u003cbr\u003e\n\nA command line client application is provided to manipulate the vproxy instance. You may see more info in [vpctl repo](https://github.com/vproxy-tools/vpctl).\n\nThis tool is fully tested and simple to use. Some examples are provided in the tool repo for reference.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eSimple mode\u003c/summary\u003e\n\n\u003cbr\u003e\n\nYou can start a simple loadbalancer in one command:\n\n```\njava -Deploy=Simple -jar vproxy.jar \\  \n                bind {port} \\\n                backend {host1:port1,host2:port2} \\\n                [ssl {path of cert1,cert2} {path of key}] \\\n                [protocol {...}] \\\n```\n\nUse `help` to view the parameters.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eStandard mode\u003c/summary\u003e\n\n\u003cbr\u003e\n\nUse `help` to view the launching parameters.\n\nAfter 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.\n\nAfter launching vproxy, you may use `System:` to run some system commands, You may create `http-controller`s and `resp-controller`s. Then you can operate the vproxy instance using `curl` or `redis-cli`. You may also operate the vproxy instance directly using standard input (stdin).\n\nSee [command.md](https://github.com/wkgcass/vproxy/blob/master/doc/command.md) and [api doc](https://github.com/wkgcass/vproxy/blob/master/doc/api.yaml) for more info.\n\n\u003c/details\u003e\n\n## Doc\n\n* [how-to-use.md](https://github.com/wkgcass/vproxy/blob/master/doc/how-to-use.md): How to use config file and controllers.\n* [api.yaml](https://github.com/wkgcass/vproxy/blob/dev/doc/api.yaml): api doc for http-controller in swagger format.\n* [lb-example.md](https://github.com/wkgcass/vproxy/blob/master/doc/lb-example.md): An example about running a loadbalancer.\n* [architecture.md](https://github.com/wkgcass/vproxy/blob/master/doc/architecture.md): Something about the architecture.\n* [extended-app.md](https://github.com/wkgcass/vproxy/blob/master/doc/extended-app.md): The usage of extended applications.\n* [websocks.md](https://github.com/wkgcass/vproxy/blob/master/doc/websocks.md): The WebSocks Protocol.\n* [vproxy-kcp-tunnel.md](https://github.com/wkgcass/vproxy/blob/master/doc/vproxy-kcp-tunnel.md): The KCP Tunnel Protocol.\n* [using-application-layer-protocols.md](https://github.com/wkgcass/vproxy/blob/master/doc/using-application-layer-protocols.md): About how to use (customized) application layer protocols.\n* [vpws-direct-relay.md](https://github.com/wkgcass/vproxy/blob/master/doc_zh/vpws-direct-relay.md): How to use `direct-relay` in `vpws-agent`.\n\n## Products\n\n* [VProxy Soft Switch (vpss)](https://github.com/vproxy-tools/vpss): A soft router (switch) for your home.\n\n## Contribute\n\nCurrently only `I` myself is working on this project. I would be very happy if you want to join :)\n\nThanks to those who had committed PR, see [CONTRIB](https://github.com/wkgcass/vproxy/blob/master/CONTRIB.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwkgcass%2Fvproxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwkgcass%2Fvproxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwkgcass%2Fvproxy/lists"}