SOCKS4, SOCKS4a and SOCKS5 protocols implementation in Erlang/OTP.
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
src socks5: return proper errors in unsupported ATYP case May 31, 2018
test Add tests for handler crash May 27, 2018
.gitignore Move to rebar3 Apr 28, 2016
.travis.yml Run test on travis only for 19.3 and 20.3 OTP versions Apr 16, 2018
LICENSE Initial commit Sep 30, 2013 Update feature section in README May 26, 2018
rebar.config Remove lager May 26, 2018
rebar.lock Remove lager May 26, 2018
tunnerl.config Rework handler behaviour May 26, 2018


Build Status

SOCKS4, SOCKS4a and SOCKS5 protocols implementation in Erlang/OTP.


  • SOCKS: A protocol for TCP proxy across firewalls: socks4
    • connect command only
  • SOCKS 4A: A Simple Extension to SOCKS 4 Protocol: socks4a
  • SOCKS Protocol Version 5: RFC1928
    • connect command only
    • Username/Password Authentication for SOCKS V5 RFC1929
    • ATYPs: IPv4, IPv6 and domain


  1. Add tunnerl to your list of dependencies in rebar.config:
{deps, [
    {tunnerl, "1.0.0"}
  1. Ensure tunnerl is started before your application:
{applications, [tunnerl]}.
  1. Configure it to use custom handler::
{tunnerl, [
    {protocols, [socks4, socks5]},
    {handler, myapp_handler},
    {acceptors, 10},
    {ip, {0, 0, 0, 0}},
    {port, 1080}
  1. Implement myapp_handler:

%% This simple handler module accepts username authentication and
%% allows user with password "pass" do connect command.
%% Also, is accepts all connections on Socks4 for "root".


auth_methods() -> [username].

auth(#{username := <<"user">>, 
       password := <<"pass">>}) -> 
auth(_) -> rejected.

handle_command(#{protocol := socks4, 
                 command := connect,
                 username := <<"root">>}) ->
handle_command(#{protocol := socks5, 
                 command := connect,
                 username := <<"user">>}) ->
handle_command(_) -> 



$ git clone
$ cd tunnerl
$ rebar3 compile

Run tunnerl with simple predefined configuration with socks4/socks5 and no authentication

$ rebar3 shell --name socks@ --config tunnerl.config --apps tunnerl

There is a bunch of common tests which can be running:

$ rebar3 ct

Note that IPv6 tests might not been working on your local machine.