doc/socket_wrapper.1.txt

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