The socket_wrapper library

socket_wrapper is a library passing all socket communications through unix sockets.

Clone with git ยท Report a bug


socket_wrapper aims to help client/server software development teams willing to gain full functional test coverage. It makes possible to run several instances of the full software stack on the same machine and perform locally functional testing of complex network configurations.

  • Redirects all network communication to happen over unix sockets.
  • Support for IPv4 and IPv6 socket and addressing emulation.
  • Ablility to capture network traffic in pcap format.

Detailed descriptions

The idea and the first incarnation of socket_wrapper has been written by Jelmer Vernooij in 2005. It made it possible to run the Samba torture suite against smbd in 'make test'. Since then socket_wrapper has evolved significantly.

How does it work? The user defines a directory where to put all the unix sockets using the envionment variable "SOCKET_WRAPPER_DIR=/path/to/socket_dir". When a server opens a port or a client wants to connect, socket_wrapper will translate IP addresses to a special socket_wrapper name and look for the relevant unix socket in the SOCKET_WRAPPER_DIR.

Additionally, the default interface to be used by an application is defined with "SOCKET_WRAPPER_DEFAULT_IFACE=<ID>" where <ID> is between 2 and 40. We limited the address space for performance reasons in the case of broadcasts. This is analogous to use the IPv4 addresses "127.0.0.<ID>" or IPv6 addresses "fd00::5357:5f<IDx>" (where <IDx> is a hexadecimal presentation of <ID>). You should always set the default interface. If you listen on INADDR_ANY then it will use the default interface to listen on.

When debugging,it is often interesting to investigate the network traffic between the client and server within your application. If you define SOCKET_WRAPPER_PCAP_FILE=/path/to/file.pcap, socket_wrapper will dump all your network traffic to the specified file. After the test has been finished you're able to open the file for example with Wireshark


# Open a console and create a directory for the unix sockets.
$ mktemp -d

# Then start nc to listen for network traffic using the temporary directory.

# (If nc, listens on then listener will be open on cause it is the default interface)

# Now open another console and start 'nc' as a client to connect to the server:

# (The client will use the address when connecting to the server)
# Now you can type 'Hello!' which will be sent to the server and should appear in the console output of the server.