Skip to content

Latest commit

 

History

History
157 lines (116 loc) · 5.57 KB

README.md

File metadata and controls

157 lines (116 loc) · 5.57 KB

neosocksd

MIT License Build Lint Release

A lightweight SOCKS4 / SOCKS4A / SOCKS5 / HTTP proxy server that can run Lua script as ruleset.

Features

  • Plain old protocols with no built-in support for authentication or encryption.
  • Only TCP CONNECT requests are supported.
  • Top class processor efficiency, minimized memory usage and code size.
  • Lua scripts powered rule set.
  • Routing connections by rule and even building an autonomous proxy mesh.
  • Horizontally scalable.
  • RESTful API for monitoring and updating rules online.
  • IPv6 supported (SOCKS4A / SOCKS5 / HTTP).
  • Embedded systems friendly.
  • Conforming to: ISO C11, POSIX.1-2008.

Ruleset example: ruleset.lua

Usage

Basic Usage

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

# Forward connection over proxy chain
# Tip: forwarding in SOCKS5 requires 1 more roundtrip than SOCKS4A/HTTP, so is generally 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 -l 0.0.0.0:80 -f 127.0.0.1:8080 -t 15 \
    --proto-timeout --max-startups 60:30:100 --max-sessions 10000

See ./neosocksd -h for details.

Scripting Usage

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

Depending on how complex your customizations are, check out:

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

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

# For debugging ruleset script
./neosocksd -l 0.0.0.0:1080 --api 127.0.1.1:9080 -r ruleset.lua --traceback -v

# 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 -d

Update ruleset on remote instance without restarting:

curl -vx socks5h://192.168.1.1:1080 \
    http://neosocksd.lan/ruleset/update \
    --data-binary @ruleset.lua

The example host name neosocksd.lan is defined in ruleset.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 ruleset 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
# 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 ruleset
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: