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 authentication or 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

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

• libev
• Lua
• c-ares
• miniz