{"id":50999072,"url":"https://github.com/hexian000/neosocksd","last_synced_at":"2026-06-20T12:34:43.033Z","repository":{"id":160755759,"uuid":"619004418","full_name":"hexian000/neosocksd","owner":"hexian000","description":"A fast, lightweight proxy server with a Lua-powered rules engine.","archived":false,"fork":false,"pushed_at":"2026-06-07T07:06:11.000Z","size":3855,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-06-07T09:09:47.642Z","etag":null,"topics":["forwarder","internet-gateway","lua","proxy-server","socks-protocol","transparent-proxy"],"latest_commit_sha":null,"homepage":"","language":"C","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/hexian000.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-03-26T01:09:52.000Z","updated_at":"2026-06-07T07:06:15.000Z","dependencies_parsed_at":"2023-09-24T07:14:02.459Z","dependency_job_id":"d5369c54-e6cd-4e0f-b496-d89f13d0081a","html_url":"https://github.com/hexian000/neosocksd","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/hexian000/neosocksd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexian000%2Fneosocksd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexian000%2Fneosocksd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexian000%2Fneosocksd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexian000%2Fneosocksd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hexian000","download_url":"https://codeload.github.com/hexian000/neosocksd/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexian000%2Fneosocksd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34570538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["forwarder","internet-gateway","lua","proxy-server","socks-protocol","transparent-proxy"],"created_at":"2026-06-20T12:34:38.876Z","updated_at":"2026-06-20T12:34:43.028Z","avatar_url":"https://github.com/hexian000.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# neosocksd\n\n[![MIT License](https://img.shields.io/github/license/hexian000/neosocksd)](https://github.com/hexian000/neosocksd/blob/master/LICENSE)\n[![Build](https://github.com/hexian000/neosocksd/actions/workflows/build.yml/badge.svg)](https://github.com/hexian000/neosocksd/actions/workflows/build.yml)\n[![Downloads](https://img.shields.io/github/downloads/hexian000/neosocksd/total.svg)](https://github.com/hexian000/neosocksd/releases)\n[![Release](https://img.shields.io/github/release/hexian000/neosocksd.svg?style=flat)](https://github.com/hexian000/neosocksd/releases)\n\nA 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.\n\nStatus: **Stable**\n\n- [Features](#features)\n- [Usage](#usage)\n  - [Protocol Modes](#protocol-modes)\n  - [Proxy Chains](#proxy-chains)\n  - [Lua Ruleset](#lua-ruleset)\n  - [Observability](#observability)\n- [Distributed Virtual Network](#distributed-virtual-network)\n- [Installation](#installation)\n  - [Runtime Dependencies](#runtime-dependencies)\n  - [Building from Source](#building-from-source)\n    - [Dependencies](#dependencies)\n    - [Building with CMake](#building-with-cmake)\n- [Credits](#credits)\n\n\n## Features\n\n- 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)).\n- Transparent proxy: Linux [TPROXY](https://docs.kernel.org/networking/tproxy.html).\n- 10+ Gbps per x86 core on Linux with `--pipe` (measured in 2024).\n- ~600 KiB executable on most platforms\\*. See [Runtime Dependencies](#runtime-dependencies).\n- Lua scripting on the control plane with extensive RPC support.\n- RESTful API for live monitoring and hot-reloading Lua modules without restarts.\n- Full IPv6 support; horizontal scalability.\n- Standards-compliant: ISO C11 and POSIX.1-2008.\n- No built-in encryption — pair with external tools for transport security. Supports basic authentication (plaintext credentials) only.\n\n*\\* Dynamically linked builds depend on libev and c-ares; see [Runtime Dependencies](#runtime-dependencies). Statically linked executables may be larger due to bundled dependencies.*\n\n\n## Usage\n\n### Protocol Modes\n\n```sh\n./neosocksd -l 0.0.0.0:1080  # SOCKS server\n./neosocksd -4 -l 0.0.0.0:1080  # Prefer IPv4 in DNS resolution\n./neosocksd -4 -l 0.0.0.0:1080 -i eth0  # Bind outbound to eth0\n./neosocksd -l 0.0.0.0:1080 --http 0.0.0.0:8080  # SOCKS and HTTP server\n\n# Transparent proxy (requires root)\nsudo ./neosocksd --tproxy -l 0.0.0.0:50080 --api 127.0.1.1:9080 -r tproxy.lua \\\n    --max-startups 60:30:100 --max-sessions 0 -u nobody: -d\n\n# Hardened load balancer (requires root)\nsudo ./neosocksd --pipe -d -u nobody: --max-sessions 10000 --max-startups 60:30:100 \\\n    -t 15 -l :80 -f : -r lb.lua --api 127.0.1.1:9080\n```\n\nFor all flags and options, run `./neosocksd --help`.\n\n### Proxy Chains\n\nForward through an upstream chain and expose a different inbound protocol:\n\n```sh\n./neosocksd -l 0.0.0.0:12345 -f 192.168.2.2:12345 \\\n    -x \"socks5://user:pass@192.168.1.1:1080,http://192.168.2.1:8080\"\n\n./neosocksd -l 127.0.0.1:1080 --http 0.0.0.0:8080 -x socks4a://203.0.113.1:1080\n```\n\n### Lua Ruleset\n\nBinary releases include `neosocksd.noarch.tar.gz` with `libruleset.lua`, `agent.lua`, and the `example/` scripts. Deploy `neosocksd` alongside `libruleset.lua`.\n\n```sh\n# Simple rule table\n./neosocksd -d -l [::]:1080 --api 127.0.1.1:9080 -r ruleset_simple.lua\n\n# Full ruleset with tracing\n./neosocksd -l 0.0.0.0:1080 --api 127.0.1.1:9080 \\\n    -r ruleset.lua --traceback --loglevel 6\n\n# Gzip-compressed Lua files\n./neosocksd -l 0.0.0.0:1080 -r ruleset.lua.gz\n./neosocksd -c config.lua.gz -r ruleset.lua.gz\n```\n\n`-c` and `-r` are unified: a single `-c config.lua` can configure the server\n*and* install the ruleset — the config script just sets `_G.ruleset` (or returns\na `ruleset` field). `-r` remains as a shorthand for a ruleset-only file.\n\n```sh\n# One file does both: configure the server and set up the ruleset\n./neosocksd -c config.lua\n```\n\nThe ruleset routes each request, then actively forwards it with `await.forward`\nand learns whether the upstream connected — see\n[await.forward](https://github.com/hexian000/neosocksd/wiki/API-Reference#awaitforward)\nfor failover and retries.\n\nHot-reload without restart:\n\n```sh\n# Replace the active ruleset\ncurl \"http://127.0.1.1:9080/ruleset/update?chunkname=%40ruleset.lua\" \\\n    --data-binary @ruleset.lua\n\n# Replace a module\ncurl \"http://127.0.1.1:9080/ruleset/update?module=libruleset\u0026chunkname=%40libruleset.lua\" \\\n    --data-binary @libruleset.lua\n\n# Execute arbitrary code\ncurl \"http://127.0.1.1:9080/ruleset/invoke\" -d \"_G.some_switch = true\"\n\n# Push a gzip-compressed chunk\ncurl \"http://127.0.1.1:9080/ruleset/invoke\" \\\n    -H \"Content-Encoding: gzip\" --data-binary @biglist.lua.gz\n```\n\nProvided scripts:\n\n| Script                                                     | Description                                                                               |\n| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------- |\n| [libruleset.lua](libruleset.lua)                           | Ruleset framework and RPC utilities                                                       |\n| [agent.lua](agent.lua)                                     | RPC-based peer discovery and relay                                                        |\n| [example/ruleset_simple.lua](example/ruleset_simple.lua)   | Minimal ruleset with domain and IP rule tables                                            |\n| [example/ruleset.lua](example/ruleset.lua)                 | Full ruleset: `agent.lua` integration, schedule-based logic, RPC; doubles as `-c` config  |\n| [example/ruleset_egress.lua](example/ruleset_egress.lua)   | Egress: blocks private addresses, maintains external IP/domain biglist, direct outbound   |\n| [example/ruleset_ingress.lua](example/ruleset_ingress.lua) | Ingress: client auth, biglist routing, upstream proxy fallback, RPC biglist sync          |\n| [example/lb.lua](example/lb.lua)                           | IWRR (interleaved weighted round robin) load balancer with runtime weight updates via RPC |\n| [example/config.lua](example/config.lua)                   | Comprehensive boot configuration for `-c`: server options and optional ruleset            |\n\nReferences: [neosocksd API Reference](https://github.com/hexian000/neosocksd/wiki/API-Reference) · [Lua 5.4 Manual](https://www.lua.org/manual/5.4/manual.html)\n\n### Observability\n\n```sh\n# Stateless snapshot\nwatch curl -s http://127.0.1.1:9080/stats\n\n# Stateful: invokes the ruleset stats function if defined\nwatch curl -sX POST http://127.0.1.1:9080/stats\n```\n\nSee [neosocksd API Reference](https://github.com/hexian000/neosocksd/wiki/API-Reference#restful-api) for the full API.\n\n\n## Distributed Virtual Network\n\n`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.\n\nSet up on each node:\n\n1. Start neosocksd with the API enabled.\n2. Load `libruleset.lua` and `agent.lua`.\n3. The agent maintains peer state and relay paths automatically.\n4. Access remote targets through the local SOCKS/HTTP endpoint.\n\n\n## Installation\n\n### Runtime Dependencies\n\n**Statically linked setup**: Download a `-static` build from the [Releases](https://github.com/hexian000/neosocksd/releases) section — no additional runtime dependencies are needed.\n\n**Dynamically linked setup**: Install the following runtime dependencies.\n\n```sh\n# Debian / Ubuntu\nsudo apt install libev4 libc-ares2\n# Alpine Linux\napk add libev c-ares\n# OpenWrt\nopkg install libev libcares\n```\n\n*Note: Lua is always linked statically.*\n\n\n### Building from Source\n\n#### Dependencies\n\n| Name   | Version   | Required | Feature                      |\n| ------ | --------- | -------- | ---------------------------- |\n| libev  | \u003e= 4.31   | yes      |                              |\n| Lua    | \u003e= 5.3    | no       | ruleset                      |\n| c-ares | \u003e= 1.16.0 | no       | asynchronous name resolution |\n\n```sh\n# Debian / Ubuntu\nsudo apt install libev-dev liblua5.4-dev libc-ares-dev\n# Alpine Linux\napk add libev-dev lua5.4-dev c-ares-dev\n```\n\n#### Building with CMake\n\n```sh\ngit clone https://github.com/hexian000/neosocksd.git\nmkdir -p neosocksd-build \u0026\u0026 cd neosocksd-build\ncmake -DCMAKE_BUILD_TYPE=\"Release\" \\\n    ../neosocksd\ncmake --build . --parallel\n```\n\nSee [m.sh](m.sh) for cross-compilation support.\n\n\n## Credits\n\nThanks to:\n- [libev](http://software.schmorp.de/pkg/libev.html)\n- [Lua](https://www.lua.org/)\n- [c-ares](https://c-ares.org/)\n- [miniz](https://github.com/richgel999/miniz)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexian000%2Fneosocksd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhexian000%2Fneosocksd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexian000%2Fneosocksd/lists"}