doc/socket_wrapper.1.adoc

   1 socket_wrapper(1)
   2 =================
   3 :revdate: 2021-02-01
   4 :author: Samba Team
   5 :doctype: manpage
   6
   7 NAME
   8 ----
   9
  10 socket_wrapper - A library passing all socket communications through unix sockets.
  11
  12 SYNOPSIS
  13 --------
  14
  15 LD_PRELOAD=libsocket_wrapper.so SOCKET_WRAPPER_DIR=/tmp/tmp.bQRELqDrhM SOCKET_WRAPPER_DEFAULT_IFACE=10 *./myapplication*
  16
  17 DESCRIPTION
  18 -----------
  19
  20 socket_wrapper aims to help client/server software development teams willing to
  21 gain full functional test coverage. It makes possible to run several instances
  22 of the full software stack on the same machine and perform locally functional
  23 testing of complex network configurations.
  24
  25 - Redirects all network communication to happen over Unix sockets.
  26 - Support for IPv4 and IPv6 socket and addressing emulation.
  27 - Ability to capture network traffic in pcap format.
  28 - Passing IP sockets (up to 6) via SCM_RIGHTS is supported,
  29   but pcap support only works reliable if the socket is used
  30   by a single process at a time.
  31
  32 ENVIRONMENT VARIABLES
  33 ---------------------
  34
  35 *SOCKET_WRAPPER_DIR*::
  36
  37 The user defines a directory where to put all the unix sockets using the
  38 environment variable "SOCKET_WRAPPER_DIR=/path/to/socket_dir". When a server
  39 opens a port or a client wants to connect, socket_wrapper will translate IP
  40 addresses to a special socket_wrapper name and look for the relevant Unix
  41 socket in the SOCKET_WRAPPER_DIR.
  42
  43 *SOCKET_WRAPPER_IPV4_NETWORK*::
  44
  45 By default the loopback IPv4 network "127.0.0.0/8" and the
  46 "127.0.0.x" can be used. In order to make more realistic testing
  47 possible it is possible to use the "10.0.0.0/8" IPv4 network instead.
  48 But note within "10.0.0.0/8" only "10.53.57.<ID>" can be used,
  49 but the broadcast address is "10.255.255.255".
  50 The following two value are allowed:
  51 SOCKET_WRAPPER_IPV4_NETWORK="127.0.0.0" (the default) and
  52 SOCKET_WRAPPER_IPV4_NETWORK="10.53.57.0".
  53
  54 *SOCKET_WRAPPER_DEFAULT_IFACE*::
  55
  56 Additionally, the default interface to be used by an application is defined with
  57 "SOCKET_WRAPPER_DEFAULT_IFACE=<ID>" where the valid range for <ID> starts with 1
  58 (the default) and ends with 64. This is analogous to use the IPv4 addresses
  59 "127.0.0.<ID>"/"10.53.57.<ID>" or IPv6 addresses "fd00::5357:5f<IDx>" (where
  60 <IDx> is a hexadecimal presentation of <ID>). You should always set the default
  61 interface. If you listen on INADDR_ANY then it will use the default interface to
  62 listen on.
  63
  64 *SOCKET_WRAPPER_PCAP_FILE*::
  65
  66 When debugging, it is often interesting to investigate the network traffic
  67 between the client and server within your application. If you define
  68 SOCKET_WRAPPER_PCAP_FILE=/path/to/file.pcap, socket_wrapper will dump all your
  69 network traffic to the specified file. After the test has been finished you're
  70 able to open the file for example with Wireshark.
  71
  72 *SOCKET_WRAPPER_MTU*::
  73
  74 With this variable you can change the MTU size. However we do not recomment to
  75 do that as the default size of 1500 byte is best for formatting PCAP files.
  76
  77 The minimum value you can set is 512 and the maximum 32768.
  78
  79 *SOCKET_WRAPPER_MAX_SOCKETS*::
  80
  81 This variable can be used to set the maximum number of sockets to be used by
  82 an application.
  83
  84 The default value is set to 65535 and the maximum 256000.
  85
  86 *SOCKET_WRAPPER_DEBUGLEVEL*::
  87
  88 If you need to see what is going on in socket_wrapper itself or try to find a
  89 bug, you can enable logging support in socket_wrapper if you built it with
  90 debug symbols.
  91
  92 - 0 = ERROR
  93 - 1 = WARNING
  94 - 2 = DEBUG
  95 - 3 = TRACE
  96
  97 *SOCKET_WRAPPER_DISABLE_DEEPBIND*::
  98
  99 This allows you to disable deep binding in socket_wrapper. This is useful for
 100 running valgrind tools or sanitizers like (address, undefined, thread).
 101
 102 *SOCKET_WRAPPER_DIR_ALLOW_ORIG*::
 103
 104 SOCKET_WRAPPER_DIR is resolved by socket_wrapper using realpath(3).
 105 Given that Unix sockets are constructed relative to this directory,
 106 the resulting path can sometimes be too long to allow valid socket
 107 paths to be constructed due to length restrictions.  Setting this
 108 variable (to any value) allows socket_wrapper to fall back to the
 109 original value of SOCKET_WRAPPER_DIR if realpath(3) makes it too long
 110 to be usable.
 111
 112 EXAMPLE
 113 -------
 114
 115   # Open a console and create a directory for the unix sockets.
 116   $ mktemp -d
 117   /tmp/tmp.bQRELqDrhM
 118
 119   # Then start nc to listen for network traffic using the temporary directory.
 120   $ LD_PRELOAD=libsocket_wrapper.so \
 121     SOCKET_WRAPPER_DIR=/tmp/tmp.bQRELqDrhM \
 122     SOCKET_WRAPPER_DEFAULT_IFACE=10 nc -v -l 127.0.0.10 7
 123
 124   # (If nc, listens on 0.0.0.0 then listener will be open on 127.0.0.10 because
 125   #  it is the default interface)
 126
 127   # Now open another console and start 'nc' as a client to connect to the server:
 128   $ LD_PRELOAD=libsocket_wrapper.so \
 129     SOCKET_WRAPPER_DIR=/tmp/tmp.bQRELqDrhM \
 130     SOCKET_WRAPPER_DEFAULT_IFACE=100 nc -v 127.0.0.10 7
 131
 132   # (The client will use the address 127.0.0.100 when connecting to the server)
 133   # Now you can type 'Hello!' which will be sent to the server and should appear
 134   # in the console output of the server.