SOCKS4a and SOCKS5 (RFC 1928; RFC 1929) handling for ocaml clients and servers
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Build status SOCKS 4a / SOCKS 5 library for OCaml clients and servers

This library implements functions for parsing and generating SOCKS 4A and SOCKS 5 requests and responses.

A Lwt helper module is provided to ease integration in Lwt applications. Unfortunately this module does not work with MirageOS.


  • This is not a "SOCKS5 compliant" implementation since the RFC requires that compliant implementation MUST support GSSAPI, which this library does not.
  • The Lwt helper module does not handle BIND or UDP-associate.
  • The Lwt helper module does not implement client functionality. Eckhart Köppen has a fork that seems to implement this. A pull request to integrate this would be nice.


To avoid always linking against Lwt/Async/MirageOS and introducing huge unneeded dependencies, this repository contains multiple OPAM packages:

  • socks
  • socks-lwt

A Makefile is provided for your convenience:

ocaml-socks$ make lib-lwt
ocaml-socks$ make docs
ocaml-socks$ make all
ocaml-socks$ make clean

Generating the documentation

This module is documented using mli docstrings. After installing the topkg-care OPAM package you can compile the documentation to HTML for viewing in your browser like this:

ocaml-socks$ make docs
# No parallelism done
Generated API doc in /home/user/ocaml/socks/_build/doc/api.docdir/

ocaml-socks$ firefox /home/user/ocaml/socks/_build/doc/api.docdir/index.html

Running a SOCKS server from utop

To run a SOCKS server listening on (IPv4 localhost) port 1080 that accepts connections from IPv4/IPv6 localhost and connects to IPv4/IPv6/Domain-name ATYPs, you can use the easy_establish_server function:

let s = Socks_lwt.easy_establish_server () ;; s ;;

The documentation for Socks_lwt has more details on creating filters for connecting clients.


The protocol description is included in this repository in the files