1SOCKET_WRAPPER(1) SOCKET_WRAPPER(1)
2
6 socket_wrapper - A library passing all socket communications through
7 unix sockets.
8
10 LD_PRELOAD=libsocket_wrapper.so SOCKET_WRAPPER_DIR=/tmp/tmp.bQRELqDrhM
11 SOCKET_WRAPPER_DEFAULT_IFACE=10 ./myapplication
12
14 socket_wrapper aims to help client/server software development teams
15 willing to gain full functional test coverage. It makes possible to run
16 several instances of the full software stack on the same machine and
17 perform locally functional testing of complex network configurations.
18 • Redirects all network communication to happen over Unix sockets.
20 • Support for IPv4 and IPv6 socket and addressing emulation.
22 • Ability to capture network traffic in pcap format.
24 • Passing IP sockets (up to 6) via SCM_RIGHTS is supported, but pcap
26 support only works reliable if the socket is used by a single
27 process at a time.
28
30 SOCKET_WRAPPER_DIR
31 The user defines a directory where to put all the unix sockets
32 using the environment variable
33 "SOCKET_WRAPPER_DIR=/path/to/socket_dir". When a server opens a
34 port or a client wants to connect, socket_wrapper will translate IP
35 addresses to a special socket_wrapper name and look for the
36 relevant Unix socket in the SOCKET_WRAPPER_DIR.
37 SOCKET_WRAPPER_IPV4_NETWORK
39 By default the loopback IPv4 network "127.0.0.0/8" and the
40 "127.0.0.x" can be used. In order to make more realistic testing
41 possible it is possible to use the "10.0.0.0/8" IPv4 network
42 instead. But note within "10.0.0.0/8" only "10.53.57.<ID>" can be
43 used, but the broadcast address is "10.255.255.255". The following
44 two value are allowed: SOCKET_WRAPPER_IPV4_NETWORK="127.0.0.0" (the
45 default) and SOCKET_WRAPPER_IPV4_NETWORK="10.53.57.0".
46 SOCKET_WRAPPER_DEFAULT_IFACE
48 Additionally, the default interface to be used by an application is
49 defined with "SOCKET_WRAPPER_DEFAULT_IFACE=<ID>" where the valid
50 range for <ID> starts with 1 (the default) and ends with 64. This
51 is analogous to use the IPv4 addresses
52 "127.0.0.<ID>"/"10.53.57.<ID>" or IPv6 addresses
53 "fd00::5357:5f<IDx>" (where <IDx> is a hexadecimal presentation of
54 <ID>). You should always set the default interface. If you listen
55 on INADDR_ANY then it will use the default interface to listen on.
56 SOCKET_WRAPPER_PCAP_FILE
58 When debugging, it is often interesting to investigate the network
59 traffic between the client and server within your application. If
60 you define SOCKET_WRAPPER_PCAP_FILE=/path/to/file.pcap,
61 socket_wrapper will dump all your network traffic to the specified
62 file. After the test has been finished you’re able to open the file
63 for example with Wireshark.
64 SOCKET_WRAPPER_MTU
66 With this variable you can change the MTU size. However we do not
67 recomment to do that as the default size of 1500 byte is best for
68 formatting PCAP files.
69 The minimum value you can set is 512 and the maximum 32768.
71 SOCKET_WRAPPER_MAX_SOCKETS
73 This variable can be used to set the maximum number of sockets to
74 be used by an application.
75 The default value is set to 65535 and the maximum 256000.
77 SOCKET_WRAPPER_DEBUGLEVEL
79 If you need to see what is going on in socket_wrapper itself or try
80 to find a bug, you can enable logging support in socket_wrapper if
81 you built it with debug symbols.
82 • 0 = ERROR
84 • 1 = WARNING
86 • 2 = DEBUG
88 • 3 = TRACE
90 SOCKET_WRAPPER_DISABLE_DEEPBIND
92 This allows you to disable deep binding in socket_wrapper. This is
93 useful for running valgrind tools or sanitizers like (address,
94 undefined, thread).
95 SOCKET_WRAPPER_DIR_ALLOW_ORIG
97 SOCKET_WRAPPER_DIR is resolved by socket_wrapper using realpath(3).
98 Given that Unix sockets are constructed relative to this directory,
99 the resulting path can sometimes be too long to allow valid socket
100 paths to be constructed due to length restrictions. Setting this
101 variable (to any value) allows socket_wrapper to fall back to the
102 original value of SOCKET_WRAPPER_DIR if realpath(3) makes it too
103 long to be usable.
104
106 # Open a console and create a directory for the unix sockets.
107 $ mktemp -d
108 /tmp/tmp.bQRELqDrhM
109 # Then start nc to listen for network traffic using the temporary directory.
111 $ LD_PRELOAD=libsocket_wrapper.so \
112 SOCKET_WRAPPER_DIR=/tmp/tmp.bQRELqDrhM \
113 SOCKET_WRAPPER_DEFAULT_IFACE=10 nc -v -l 127.0.0.10 7
114 # (If nc, listens on 0.0.0.0 then listener will be open on 127.0.0.10 because
116 # it is the default interface)
117 # Now open another console and start 'nc' as a client to connect to the server:
119 $ LD_PRELOAD=libsocket_wrapper.so \
120 SOCKET_WRAPPER_DIR=/tmp/tmp.bQRELqDrhM \
121 SOCKET_WRAPPER_DEFAULT_IFACE=100 nc -v 127.0.0.10 7
122 # (The client will use the address 127.0.0.100 when connecting to the server)
124 # Now you can type 'Hello!' which will be sent to the server and should appear
125 # in the console output of the server.
126
128 Socket wrapper advanced helpers.
129 Applications with the need to alter their behaviour when socket wrapper
131 is active, can link use these functions.
132 By default it’s required for applications to use any of these functions
134 as libsocket_wrapper.so is injected at runtime via LD_PRELOAD.
135 Applications using these functions should link against
137 libsocket_wrapper_noop.so by using -lsocket_wrapper_noop, or implement
138 their own noop stubs.
139 #include <socket_wrapper.h>
141 bool socket_wrapper_enabled(void);
143 • This returns true when socket wrapper is actively in use.
145 void socket_wrapper_indicate_no_inet_fd(int fd);
147 • This allows socket_wrapper aware applications to indicate that the
149 given fd does not belong to an inet socket.
150 • socket_wrapper may not be able to intercept the __close_nocancel()
152 syscall made from within libc.so. As result it’s possible that the
153 in memory meta date of socket_wrapper references stale file
154 descriptors, which are already reused for unrelated kernel objects,
155 e.g. files, directories, ...
156 • Socket wrapper already intercepts a lot of unrelated functions like
158 eventfd(), timerfd_create(), ... in order to remove stale meta data
159 for the returned fd, but it will never be able to handle all
160 possible syscalls.
161 • socket_wrapper_indicate_no_inet_fd() gives applications a way to do
163 the same, explicitly without waiting for new syscalls to be added
164 to libsocket_wrapper.so.
165 • This is a no-op if socket_wrapper is not in use or if the there is
167 no in memory meta data for the given fd.
168
170 Project web site: https://cwrap.org
171
173 Samba Team
174 2021-02-24 SOCKET_WRAPPER(1)