https://github.com/hexian000/neosocksd
A fast, lightweight proxy server with a Lua-powered rules engine.
https://github.com/hexian000/neosocksd
forwarder internet-gateway lua proxy-server socks-protocol transparent-proxy
Last synced: 2 days ago
JSON representation
A fast, lightweight proxy server with a Lua-powered rules engine.
- Host: GitHub
- URL: https://github.com/hexian000/neosocksd
- Owner: hexian000
- License: mit
- Created: 2023-03-26T01:09:52.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2026-06-07T07:06:11.000Z (15 days ago)
- Last Synced: 2026-06-07T09:09:47.642Z (15 days ago)
- Topics: forwarder, internet-gateway, lua, proxy-server, socks-protocol, transparent-proxy
- Language: C
- Homepage:
- Size: 3.68 MB
- Stars: 10
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# neosocksd
[](https://github.com/hexian000/neosocksd/blob/master/LICENSE)
[](https://github.com/hexian000/neosocksd/actions/workflows/build.yml)
[](https://github.com/hexian000/neosocksd/releases)
[](https://github.com/hexian000/neosocksd/releases)
A fast, lightweight TCP proxy server written in C with a Lua-powered routing engine. Ships with `agent.lua`, an optional module for building an autonomous overlay network across multiple LANs.
Status: **Stable**
- [Features](#features)
- [Usage](#usage)
- [Protocol Modes](#protocol-modes)
- [Proxy Chains](#proxy-chains)
- [Lua Ruleset](#lua-ruleset)
- [Observability](#observability)
- [Distributed Virtual Network](#distributed-virtual-network)
- [Installation](#installation)
- [Runtime Dependencies](#runtime-dependencies)
- [Building from Source](#building-from-source)
- [Dependencies](#dependencies)
- [Building with CMake](#building-with-cmake)
- [Credits](#credits)
## Features
- Protocols: [SOCKS4](https://www.openssh.com/txt/socks4.protocol)/[SOCKS4A](https://www.openssh.com/txt/socks4a.protocol) (Ying-Da Lee / NEC), SOCKS5 ([RFC 1928](https://datatracker.ietf.org/doc/html/rfc1928), with [RFC 1929](https://datatracker.ietf.org/doc/html/rfc1929) auth), HTTP CONNECT ([RFC 9110 §9.3.6](https://datatracker.ietf.org/doc/html/rfc9110#section-9.3.6)).
- Transparent proxy: Linux [TPROXY](https://docs.kernel.org/networking/tproxy.html).
- 10+ Gbps per x86 core on Linux with `--pipe` (measured in 2024).
- ~600 KiB executable on most platforms\*. See [Runtime Dependencies](#runtime-dependencies).
- Lua scripting on the control plane with extensive RPC support.
- RESTful API for live monitoring and hot-reloading Lua modules without restarts.
- Full IPv6 support; horizontal scalability.
- Standards-compliant: ISO C11 and POSIX.1-2008.
- No built-in encryption — pair with external tools for transport security. Supports basic authentication (plaintext credentials) only.
*\* Dynamically linked builds depend on libev and c-ares; see [Runtime Dependencies](#runtime-dependencies). Statically linked executables may be larger due to bundled dependencies.*
## Usage
### Protocol Modes
```sh
./neosocksd -l 0.0.0.0:1080 # SOCKS server
./neosocksd -4 -l 0.0.0.0:1080 # Prefer IPv4 in DNS resolution
./neosocksd -4 -l 0.0.0.0:1080 -i eth0 # Bind outbound to eth0
./neosocksd -l 0.0.0.0:1080 --http 0.0.0.0:8080 # SOCKS and HTTP server
# Transparent proxy (requires root)
sudo ./neosocksd --tproxy -l 0.0.0.0:50080 --api 127.0.1.1:9080 -r tproxy.lua \
--max-startups 60:30:100 --max-sessions 0 -u nobody: -d
# Hardened load balancer (requires root)
sudo ./neosocksd --pipe -d -u nobody: --max-sessions 10000 --max-startups 60:30:100 \
-t 15 -l :80 -f : -r lb.lua --api 127.0.1.1:9080
```
For all flags and options, run `./neosocksd --help`.
### Proxy Chains
Forward through an upstream chain and expose a different inbound protocol:
```sh
./neosocksd -l 0.0.0.0:12345 -f 192.168.2.2:12345 \
-x "socks5://user:pass@192.168.1.1:1080,http://192.168.2.1:8080"
./neosocksd -l 127.0.0.1:1080 --http 0.0.0.0:8080 -x socks4a://203.0.113.1:1080
```
### Lua Ruleset
Binary releases include `neosocksd.noarch.tar.gz` with `libruleset.lua`, `agent.lua`, and the `example/` scripts. Deploy `neosocksd` alongside `libruleset.lua`.
```sh
# Simple rule table
./neosocksd -d -l [::]:1080 --api 127.0.1.1:9080 -r ruleset_simple.lua
# Full ruleset with tracing
./neosocksd -l 0.0.0.0:1080 --api 127.0.1.1:9080 \
-r ruleset.lua --traceback --loglevel 6
# Gzip-compressed Lua files
./neosocksd -l 0.0.0.0:1080 -r ruleset.lua.gz
./neosocksd -c config.lua.gz -r ruleset.lua.gz
```
`-c` and `-r` are unified: a single `-c config.lua` can configure the server
*and* install the ruleset — the config script just sets `_G.ruleset` (or returns
a `ruleset` field). `-r` remains as a shorthand for a ruleset-only file.
```sh
# One file does both: configure the server and set up the ruleset
./neosocksd -c config.lua
```
The ruleset routes each request, then actively forwards it with `await.forward`
and learns whether the upstream connected — see
[await.forward](https://github.com/hexian000/neosocksd/wiki/API-Reference#awaitforward)
for failover and retries.
Hot-reload without restart:
```sh
# Replace the active ruleset
curl "http://127.0.1.1:9080/ruleset/update?chunkname=%40ruleset.lua" \
--data-binary @ruleset.lua
# Replace a module
curl "http://127.0.1.1:9080/ruleset/update?module=libruleset&chunkname=%40libruleset.lua" \
--data-binary @libruleset.lua
# Execute arbitrary code
curl "http://127.0.1.1:9080/ruleset/invoke" -d "_G.some_switch = true"
# Push a gzip-compressed chunk
curl "http://127.0.1.1:9080/ruleset/invoke" \
-H "Content-Encoding: gzip" --data-binary @biglist.lua.gz
```
Provided scripts:
| Script | Description |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| [libruleset.lua](libruleset.lua) | Ruleset framework and RPC utilities |
| [agent.lua](agent.lua) | RPC-based peer discovery and relay |
| [example/ruleset_simple.lua](example/ruleset_simple.lua) | Minimal ruleset with domain and IP rule tables |
| [example/ruleset.lua](example/ruleset.lua) | Full ruleset: `agent.lua` integration, schedule-based logic, RPC; doubles as `-c` config |
| [example/ruleset_egress.lua](example/ruleset_egress.lua) | Egress: blocks private addresses, maintains external IP/domain biglist, direct outbound |
| [example/ruleset_ingress.lua](example/ruleset_ingress.lua) | Ingress: client auth, biglist routing, upstream proxy fallback, RPC biglist sync |
| [example/lb.lua](example/lb.lua) | IWRR (interleaved weighted round robin) load balancer with runtime weight updates via RPC |
| [example/config.lua](example/config.lua) | Comprehensive boot configuration for `-c`: server options and optional ruleset |
References: [neosocksd API Reference](https://github.com/hexian000/neosocksd/wiki/API-Reference) · [Lua 5.4 Manual](https://www.lua.org/manual/5.4/manual.html)
### Observability
```sh
# Stateless snapshot
watch curl -s http://127.0.1.1:9080/stats
# Stateful: invokes the ruleset stats function if defined
watch curl -sX POST http://127.0.1.1:9080/stats
```
See [neosocksd API Reference](https://github.com/hexian000/neosocksd/wiki/API-Reference#restful-api) for the full API.
## Distributed Virtual Network
`agent.lua` builds an autonomous overlay across multiple LANs: peers discover each other via RPC, traffic is relayed across nodes, and remote resources are reachable through the local proxy endpoint.
Set up on each node:
1. Start neosocksd with the API enabled.
2. Load `libruleset.lua` and `agent.lua`.
3. The agent maintains peer state and relay paths automatically.
4. Access remote targets through the local SOCKS/HTTP endpoint.
## Installation
### Runtime Dependencies
**Statically linked setup**: Download a `-static` build from the [Releases](https://github.com/hexian000/neosocksd/releases) section — no additional runtime dependencies are needed.
**Dynamically linked setup**: Install the following runtime dependencies.
```sh
# Debian / Ubuntu
sudo apt install libev4 libc-ares2
# Alpine Linux
apk add libev c-ares
# OpenWrt
opkg install libev libcares
```
*Note: Lua is always linked statically.*
### Building from Source
#### Dependencies
| Name | Version | Required | Feature |
| ------ | --------- | -------- | ---------------------------- |
| libev | >= 4.31 | yes | |
| Lua | >= 5.3 | no | ruleset |
| c-ares | >= 1.16.0 | no | asynchronous name resolution |
```sh
# Debian / Ubuntu
sudo apt install libev-dev liblua5.4-dev libc-ares-dev
# Alpine Linux
apk add libev-dev lua5.4-dev c-ares-dev
```
#### Building with CMake
```sh
git clone https://github.com/hexian000/neosocksd.git
mkdir -p neosocksd-build && cd neosocksd-build
cmake -DCMAKE_BUILD_TYPE="Release" \
../neosocksd
cmake --build . --parallel
```
See [m.sh](m.sh) for cross-compilation support.
## Credits
Thanks to:
- [libev](http://software.schmorp.de/pkg/libev.html)
- [Lua](https://www.lua.org/)
- [c-ares](https://c-ares.org/)
- [miniz](https://github.com/richgel999/miniz)