doc/socket_wrapper.1

   1 '\" t
   2 .\"     Title: socket_wrapper
   3 .\"    Author: Samba Team
   4 .\" Generator: Asciidoctor 2.0.10
   5 .\"      Date: 2021-02-24
   6 .\"    Manual: \ \&
   7 .\"    Source: \ \&
   8 .\"  Language: English
   9 .\"
  10 .TH "SOCKET_WRAPPER" "1" "2021-02-24" "\ \&" "\ \&"
  11 .ie \n(.g .ds Aq \(aq
  12 .el       .ds Aq '
  13 .ss \n[.ss] 0
  14 .nh
  15 .ad l
  16 .de URL
  17 \fI\\$2\fP <\\$1>\\$3
  18 ..
  19 .als MTO URL
  20 .if \n[.g] \{\
  21 .  mso www.tmac
  22 .  am URL
  23 .    ad l
  24 .  .
  25 .  am MTO
  26 .    ad l
  27 .  .
  28 .  LINKSTYLE blue R < >
  29 .\}
  30 .SH "NAME"
  31 socket_wrapper \- A library passing all socket communications through unix sockets.
  32 .SH "SYNOPSIS"
  33 .sp
  34 LD_PRELOAD=libsocket_wrapper.so SOCKET_WRAPPER_DIR=/tmp/tmp.bQRELqDrhM SOCKET_WRAPPER_DEFAULT_IFACE=10 \fB./myapplication\fP
  35 .SH "DESCRIPTION"
  36 .sp
  37 socket_wrapper aims to help client/server software development teams willing to
  38 gain full functional test coverage. It makes possible to run several instances
  39 of the full software stack on the same machine and perform locally functional
  40 testing of complex network configurations.
  41 .sp
  42 .RS 4
  43 .ie n \{\
  44 \h'-04'\(bu\h'+03'\c
  45 .\}
  46 .el \{\
  47 .  sp -1
  48 .  IP \(bu 2.3
  49 .\}
  50 Redirects all network communication to happen over Unix sockets.
  51 .RE
  52 .sp
  53 .RS 4
  54 .ie n \{\
  55 \h'-04'\(bu\h'+03'\c
  56 .\}
  57 .el \{\
  58 .  sp -1
  59 .  IP \(bu 2.3
  60 .\}
  61 Support for IPv4 and IPv6 socket and addressing emulation.
  62 .RE
  63 .sp
  64 .RS 4
  65 .ie n \{\
  66 \h'-04'\(bu\h'+03'\c
  67 .\}
  68 .el \{\
  69 .  sp -1
  70 .  IP \(bu 2.3
  71 .\}
  72 Ability to capture network traffic in pcap format.
  73 .RE
  74 .sp
  75 .RS 4
  76 .ie n \{\
  77 \h'-04'\(bu\h'+03'\c
  78 .\}
  79 .el \{\
  80 .  sp -1
  81 .  IP \(bu 2.3
  82 .\}
  83 Passing IP sockets (up to 6) via SCM_RIGHTS is supported,
  84 but pcap support only works reliable if the socket is used
  85 by a single process at a time.
  86 .RE
  87 .SH "ENVIRONMENT VARIABLES"
  88 .sp
  89 \fBSOCKET_WRAPPER_DIR\fP
  90 .RS 4
  91 The user defines a directory where to put all the unix sockets using the
  92 environment variable "SOCKET_WRAPPER_DIR=/path/to/socket_dir". When a server
  93 opens a port or a client wants to connect, socket_wrapper will translate IP
  94 addresses to a special socket_wrapper name and look for the relevant Unix
  95 socket in the SOCKET_WRAPPER_DIR.
  96 .RE
  97 .sp
  98 \fBSOCKET_WRAPPER_IPV4_NETWORK\fP
  99 .RS 4
 100 By default the loopback IPv4 network "127.0.0.0/8" and the
 101 "127.0.0.x" can be used. In order to make more realistic testing
 102 possible it is possible to use the "10.0.0.0/8" IPv4 network instead.
 103 But note within "10.0.0.0/8" only "10.53.57.<ID>" can be used,
 104 but the broadcast address is "10.255.255.255".
 105 The following two value are allowed:
 106 SOCKET_WRAPPER_IPV4_NETWORK="127.0.0.0" (the default) and
 107 SOCKET_WRAPPER_IPV4_NETWORK="10.53.57.0".
 108 .RE
 109 .sp
 110 \fBSOCKET_WRAPPER_DEFAULT_IFACE\fP
 111 .RS 4
 112 Additionally, the default interface to be used by an application is defined with
 113 "SOCKET_WRAPPER_DEFAULT_IFACE=<ID>" where the valid range for <ID> starts with 1
 114 (the default) and ends with 64. This is analogous to use the IPv4 addresses
 115 "127.0.0.<ID>"/"10.53.57.<ID>" or IPv6 addresses "fd00::5357:5f<IDx>" (where
 116 <IDx> is a hexadecimal presentation of <ID>). You should always set the default
 117 interface. If you listen on INADDR_ANY then it will use the default interface to
 118 listen on.
 119 .RE
 120 .sp
 121 \fBSOCKET_WRAPPER_PCAP_FILE\fP
 122 .RS 4
 123 When debugging, it is often interesting to investigate the network traffic
 124 between the client and server within your application. If you define
 125 SOCKET_WRAPPER_PCAP_FILE=/path/to/file.pcap, socket_wrapper will dump all your
 126 network traffic to the specified file. After the test has been finished you\(cqre
 127 able to open the file for example with Wireshark.
 128 .RE
 129 .sp
 130 \fBSOCKET_WRAPPER_MTU\fP
 131 .RS 4
 132 With this variable you can change the MTU size. However we do not recomment to
 133 do that as the default size of 1500 byte is best for formatting PCAP files.
 134 .RE
 135 .sp
 136 The minimum value you can set is 512 and the maximum 32768.
 137 .sp
 138 \fBSOCKET_WRAPPER_MAX_SOCKETS\fP
 139 .RS 4
 140 This variable can be used to set the maximum number of sockets to be used by
 141 an application.
 142 .RE
 143 .sp
 144 The default value is set to 65535 and the maximum 256000.
 145 .sp
 146 \fBSOCKET_WRAPPER_DEBUGLEVEL\fP
 147 .RS 4
 148 If you need to see what is going on in socket_wrapper itself or try to find a
 149 bug, you can enable logging support in socket_wrapper if you built it with
 150 debug symbols.
 151 .sp
 152 .RS 4
 153 .ie n \{\
 154 \h'-04'\(bu\h'+03'\c
 155 .\}
 156 .el \{\
 157 .  sp -1
 158 .  IP \(bu 2.3
 159 .\}
 160 0 = ERROR
 161 .RE
 162 .sp
 163 .RS 4
 164 .ie n \{\
 165 \h'-04'\(bu\h'+03'\c
 166 .\}
 167 .el \{\
 168 .  sp -1
 169 .  IP \(bu 2.3
 170 .\}
 171 1 = WARNING
 172 .RE
 173 .sp
 174 .RS 4
 175 .ie n \{\
 176 \h'-04'\(bu\h'+03'\c
 177 .\}
 178 .el \{\
 179 .  sp -1
 180 .  IP \(bu 2.3
 181 .\}
 182 2 = DEBUG
 183 .RE
 184 .sp
 185 .RS 4
 186 .ie n \{\
 187 \h'-04'\(bu\h'+03'\c
 188 .\}
 189 .el \{\
 190 .  sp -1
 191 .  IP \(bu 2.3
 192 .\}
 193 3 = TRACE
 194 .RE
 195 .RE
 196 .sp
 197 \fBSOCKET_WRAPPER_DISABLE_DEEPBIND\fP
 198 .RS 4
 199 This allows you to disable deep binding in socket_wrapper. This is useful for
 200 running valgrind tools or sanitizers like (address, undefined, thread).
 201 .RE
 202 .sp
 203 \fBSOCKET_WRAPPER_DIR_ALLOW_ORIG\fP
 204 .RS 4
 205 SOCKET_WRAPPER_DIR is resolved by socket_wrapper using realpath(3).
 206 Given that Unix sockets are constructed relative to this directory,
 207 the resulting path can sometimes be too long to allow valid socket
 208 paths to be constructed due to length restrictions.  Setting this
 209 variable (to any value) allows socket_wrapper to fall back to the
 210 original value of SOCKET_WRAPPER_DIR if realpath(3) makes it too long
 211 to be usable.
 212 .RE
 213 .SH "EXAMPLE"
 214 .sp
 215 .if n .RS 4
 216 .nf
 217 # Open a console and create a directory for the unix sockets.
 218 $ mktemp \-d
 219 /tmp/tmp.bQRELqDrhM
 220 .fi
 221 .if n .RE
 222 .sp
 223 .if n .RS 4
 224 .nf
 225 # Then start nc to listen for network traffic using the temporary directory.
 226 $ LD_PRELOAD=libsocket_wrapper.so \(rs
 227   SOCKET_WRAPPER_DIR=/tmp/tmp.bQRELqDrhM \(rs
 228   SOCKET_WRAPPER_DEFAULT_IFACE=10 nc \-v \-l 127.0.0.10 7
 229 .fi
 230 .if n .RE
 231 .sp
 232 .if n .RS 4
 233 .nf
 234 # (If nc, listens on 0.0.0.0 then listener will be open on 127.0.0.10 because
 235 #  it is the default interface)
 236 .fi
 237 .if n .RE
 238 .sp
 239 .if n .RS 4
 240 .nf
 241 # Now open another console and start \(aqnc\(aq as a client to connect to the server:
 242 $ LD_PRELOAD=libsocket_wrapper.so \(rs
 243   SOCKET_WRAPPER_DIR=/tmp/tmp.bQRELqDrhM \(rs
 244   SOCKET_WRAPPER_DEFAULT_IFACE=100 nc \-v 127.0.0.10 7
 245 .fi
 246 .if n .RE
 247 .sp
 248 .if n .RS 4
 249 .nf
 250 # (The client will use the address 127.0.0.100 when connecting to the server)
 251 # Now you can type \(aqHello!\(aq which will be sent to the server and should appear
 252 # in the console output of the server.
 253 .fi
 254 .if n .RE
 255 .SH "PUBLIC FUNCTIONS"
 256 .sp
 257 Socket wrapper advanced helpers.
 258 .sp
 259 Applications with the need to alter their behaviour when
 260 socket wrapper is active, can link use these functions.
 261 .sp
 262 By default it\(cqs required for applications to use any of these
 263 functions as libsocket_wrapper.so is injected at runtime via
 264 LD_PRELOAD.
 265 .sp
 266 Applications using these functions should link against
 267 libsocket_wrapper_noop.so by using \-lsocket_wrapper_noop,
 268 or implement their own noop stubs.
 269 .sp
 270 #include <socket_wrapper.h>
 271 .sp
 272 bool socket_wrapper_enabled(void);
 273 .sp
 274 .RS 4
 275 .ie n \{\
 276 \h'-04'\(bu\h'+03'\c
 277 .\}
 278 .el \{\
 279 .  sp -1
 280 .  IP \(bu 2.3
 281 .\}
 282 This returns true when socket wrapper is actively in use.
 283 .RE
 284 .sp
 285 void socket_wrapper_indicate_no_inet_fd(int fd);
 286 .sp
 287 .RS 4
 288 .ie n \{\
 289 \h'-04'\(bu\h'+03'\c
 290 .\}
 291 .el \{\
 292 .  sp -1
 293 .  IP \(bu 2.3
 294 .\}
 295 This allows socket_wrapper aware applications to
 296 indicate that the given fd does not belong to
 297 an inet socket.
 298 .RE
 299 .sp
 300 .RS 4
 301 .ie n \{\
 302 \h'-04'\(bu\h'+03'\c
 303 .\}
 304 .el \{\
 305 .  sp -1
 306 .  IP \(bu 2.3
 307 .\}
 308 socket_wrapper may not be able to intercept the __close_nocancel()
 309 syscall made from within libc.so. As result it\(cqs possible
 310 that the in memory meta date of socket_wrapper references
 311 stale file descriptors, which are already reused for unrelated
 312 kernel objects, e.g. files, directories, ...
 313 .RE
 314 .sp
 315 .RS 4
 316 .ie n \{\
 317 \h'-04'\(bu\h'+03'\c
 318 .\}
 319 .el \{\
 320 .  sp -1
 321 .  IP \(bu 2.3
 322 .\}
 323 Socket wrapper already intercepts a lot of unrelated
 324 functions like eventfd(), timerfd_create(), ... in order
 325 to remove stale meta data for the returned fd, but
 326 it will never be able to handle all possible syscalls.
 327 .RE
 328 .sp
 329 .RS 4
 330 .ie n \{\
 331 \h'-04'\(bu\h'+03'\c
 332 .\}
 333 .el \{\
 334 .  sp -1
 335 .  IP \(bu 2.3
 336 .\}
 337 socket_wrapper_indicate_no_inet_fd() gives applications a way
 338 to do the same, explicitly without waiting for new syscalls to
 339 be added to libsocket_wrapper.so.
 340 .RE
 341 .sp
 342 .RS 4
 343 .ie n \{\
 344 \h'-04'\(bu\h'+03'\c
 345 .\}
 346 .el \{\
 347 .  sp -1
 348 .  IP \(bu 2.3
 349 .\}
 350 This is a no\-op if socket_wrapper is not in use or
 351 if the there is no in memory meta data for the given fd.
 352 .RE
 353 .SH "RESOURCES"
 354 .sp
 355 \fBProject web site:\fP \c
 356 .URL "https://cwrap.org" "" ""
 357 .SH "AUTHOR"
 358 .sp
 359 Samba Team