neosocksd

A lightweight unencrypted proxy server that can run Lua script as rule set.

Introduction
Features
Usage
- Command Line Arguments
- Scripting
Observability
Runtime Dependencies
Building from Source
- Dependencies
- Building with CMake
Credits

Introduction

neosocksd is an unencrypted proxy server that allows highly customized rule sets in Lua.

If a proxy rule table is all you need, see the self explaining ruleset_simple.lua.

For advanced scripting usage, see scripting.

Features

SOCKS4 / SOCKS4A / SOCKS5 / HTTP with no built-in support for encryption.
Transparent proxy. (Linux only)
Only TCP CONNECT requests are supported.
Lua scripts powered rule set.
Routing connections by rule and even building an autonomous proxy mesh.
RESTful API for monitoring and updating rules online.
IPv6 supported (SOCKS4A / SOCKS5 / HTTP).
Horizontally scalable.
Flexible and versatile: can be used for Internet gateway, RPC proxy, etc.
Embedded systems friendly.
Conforming to: ISO C11, POSIX.1-2008.

Usage

Command Line Arguments

./neosocksd -l 0.0.0.0:1080               # Just a SOCKS server
./neosocksd -4 -l 0.0.0.0:1080            # Prefer IPv4 in name resolution
./neosocksd -4 -l 0.0.0.0:1080 -i eth0    # And bind outbound connections to eth0
./neosocksd --http -l 0.0.0.0:8080        # HTTP CONNECT server

# High-performance dynamic TCP load balancer
./neosocksd --pipe -d -u nobody:nogroup -l 0.0.0.0:30001 \
    -f 10.0.0.1:30001 --api 127.0.1.1:9080 -r lb.lua

# Forward connection over proxy chain
# Tip: forwarding in SOCKS5 needs 1 more roundtrip than SOCKS4A/HTTP, so is usually not a good idea.
./neosocksd -l 0.0.0.0:12345 -f 192.168.2.2:12345 -x "socks4a://192.168.1.1:1080,http://192.168.2.1:8118"

# Convert proxy protocol to SOCKS4A
./neosocksd -l 127.0.0.1:1080 -x socks4a://203.0.113.1:1080 -d
./neosocksd --http -l 127.0.0.1:8118 -x socks4a://203.0.113.1:1080 -d

# Start a hardened non-forking TCP port forwarder in the background
sudo ./neosocksd -d -u nobody:nogroup -l 0.0.0.0:80 -f 127.0.0.1:8080 -t 15 \
    --proto-timeout --max-startups 60:30:100 --max-sessions 10000

# Start a rule set powered SOCKS4 / SOCKS4A / SOCKS5 server
./neosocksd -l [::]:1080 --api 127.0.1.1:9080 -r ruleset_simple.lua -d

See ./neosocksd -h for more details.

Scripting

First, deploy neosocksd with ruleset.lua and libruleset.lua. (For binary releases, check neosocksd.noarch.tar.gz)

ruleset.lua is a demo script.
libruleset.lua provides rule table facilities.
Developer manual: neosocksd API Reference, Lua 5.4 Reference Manual (external)

Use the following command to start the server with the Lua scripts in current directory:

# Print rule set logs and error traceback
./neosocksd -l 0.0.0.0:1080 --api 127.0.1.1:9080 -r ruleset.lua --traceback --loglevel 6

# Start a transparent proxy to route TCP traffic by ruleset
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:nogroup -d

Use the following command to update rule set on remote instance without restarting:

# Reload rule set
curl -v http://127.0.1.1:9080/ruleset/update \
    --data-binary @ruleset.lua

# Reload Lua module
curl -v http://127.0.1.1:9080/ruleset/update?module=libruleset \
    --data-binary @libruleset.lua

# Run any script on the server
curl -v http://127.0.1.1:9080/ruleset/invoke \
    -d "_G.some_switch = true"
curl -v http://127.0.1.1:9080/ruleset/invoke \
    --data-binary @patch.lua

Observability

The builtin RESTful API server can be used for monitoring service status.

# stateless
watch curl -s http://127.0.1.1:9080/stats
# stateful, will call rule set stats function if available
watch curl -sX POST http://127.0.1.1:9080/stats

See neosocksd API Reference for more details.

Runtime Dependencies

If you downloaded a *-static build in the Releases section, you don't have to install the dependencies below.

# Debian & Ubuntu
sudo apt install libev4 libc-ares2
# Alpine Linux
apk add libev c-ares
# OpenWRT
opkg install libev libcares

Lua is statically linked by default.

Building from Source

Dependencies

Name	Version	Required	Feature
libev	>= 4.31	yes
Lua	>= 5.3	no	rule set
c-ares	>= 1.16.0	no	asynchronous name resolves

# 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

git clone https://github.com/hexian000/neosocksd.git
mkdir "neosocksd-build"
cmake -DCMAKE_BUILD_TYPE="Release" \
    -S "neosocksd" \
    -B "neosocksd-build"
cmake --build "neosocksd-build" --parallel

See m.sh for more information about cross compiling support.

Credits

Thanks to: