2 .\" Title: socket_wrapper
4 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
10 .TH "SOCKET_WRAPPER" "1" "2021\-02\-01" "\ \&" "\ \&"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
25 .\" disable justification (adjust text to left margin only)
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
31 socket_wrapper \- A library passing all socket communications through unix sockets\&.
34 LD_PRELOAD=libsocket_wrapper\&.so SOCKET_WRAPPER_DIR=/tmp/tmp\&.bQRELqDrhM SOCKET_WRAPPER_DEFAULT_IFACE=10 \fB\&./myapplication\fR
37 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\&.
47 Redirects all network communication to happen over Unix sockets\&.
58 Support for IPv4 and IPv6 socket and addressing emulation\&.
69 Ability to capture network traffic in pcap format\&.
80 Passing IP sockets (up to 6) via SCM_RIGHTS is supported, but pcap support only works reliable if the socket is used by a single process at a time\&.
82 .SH "ENVIRONMENT VARIABLES"
84 \fBSOCKET_WRAPPER_DIR\fR
86 The user defines a directory where to put all the unix sockets using the environment 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\&.
89 \fBSOCKET_WRAPPER_IPV4_NETWORK\fR
91 By default the loopback IPv4 network "127\&.0\&.0\&.0/8" and the "127\&.0\&.0\&.x" can be used\&. In order to make more realistic testing possible it is possible to use the "10\&.0\&.0\&.0/8" IPv4 network instead\&. But note within "10\&.0\&.0\&.0/8" only "10\&.53\&.57\&.<ID>" can be used, but the broadcast address is "10\&.255\&.255\&.255"\&. The following two value are allowed: SOCKET_WRAPPER_IPV4_NETWORK="127\&.0\&.0\&.0" (the default) and SOCKET_WRAPPER_IPV4_NETWORK="10\&.53\&.57\&.0"\&.
94 \fBSOCKET_WRAPPER_DEFAULT_IFACE\fR
96 Additionally, the default interface to be used by an application is defined with "SOCKET_WRAPPER_DEFAULT_IFACE=<ID>" where the valid range for <ID> starts with 1 (the default) and ends with 64\&. This is analogous to use the IPv4 addresses "127\&.0\&.0\&.<ID>"/"10\&.53\&.57\&.<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\&.
99 \fBSOCKET_WRAPPER_PCAP_FILE\fR
101 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\(cqre able to open the file for example with Wireshark\&.
104 \fBSOCKET_WRAPPER_MTU\fR
106 With this variable you can change the MTU size\&. However we do not recomment to do that as the default size of 1500 byte is best for formatting PCAP files\&.
109 The minimum value you can set is 512 and the maximum 32768\&.
111 \fBSOCKET_WRAPPER_MAX_SOCKETS\fR
113 This variable can be used to set the maximum number of sockets to be used by an application\&.
116 The default value is set to 65535 and the maximum 256000\&.
118 \fBSOCKET_WRAPPER_DEBUGLEVEL\fR
120 If you need to see what is going on in socket_wrapper itself or try to find a bug, you can enable logging support in socket_wrapper if you built it with debug symbols\&.
167 \fBSOCKET_WRAPPER_DISABLE_DEEPBIND\fR
169 This allows you to disable deep binding in socket_wrapper\&. This is useful for running valgrind tools or sanitizers like (address, undefined, thread)\&.
172 \fBSOCKET_WRAPPER_DIR_ALLOW_ORIG\fR
174 SOCKET_WRAPPER_DIR is resolved by socket_wrapper using realpath(3)\&. Given that Unix sockets are constructed relative to this directory, the resulting path can sometimes be too long to allow valid socket paths to be constructed due to length restrictions\&. Setting this variable (to any value) allows socket_wrapper to fall back to the original value of SOCKET_WRAPPER_DIR if realpath(3) makes it too long to be usable\&.
182 # Open a console and create a directory for the unix sockets\&.
184 /tmp/tmp\&.bQRELqDrhM
194 # Then start nc to listen for network traffic using the temporary directory\&.
195 $ LD_PRELOAD=libsocket_wrapper\&.so \e
196 SOCKET_WRAPPER_DIR=/tmp/tmp\&.bQRELqDrhM \e
197 SOCKET_WRAPPER_DEFAULT_IFACE=10 nc \-v \-l 127\&.0\&.0\&.10 7
207 # (If nc, listens on 0\&.0\&.0\&.0 then listener will be open on 127\&.0\&.0\&.10 because
208 # it is the default interface)
218 # Now open another console and start \*(Aqnc\*(Aq as a client to connect to the server:
219 $ LD_PRELOAD=libsocket_wrapper\&.so \e
220 SOCKET_WRAPPER_DIR=/tmp/tmp\&.bQRELqDrhM \e
221 SOCKET_WRAPPER_DEFAULT_IFACE=100 nc \-v 127\&.0\&.0\&.10 7
231 # (The client will use the address 127\&.0\&.0\&.100 when connecting to the server)
232 # Now you can type \*(AqHello!\*(Aq which will be sent to the server and should appear
233 # in the console output of the server\&.