doc/socket_wrapper.1

   1 '\" t
   2 .\"     Title: socket_wrapper
   3 .\"    Author: Samba Team
   4 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
   5 .\"      Date: 2018-11-28
   6 .\"    Manual: \ \&
   7 .\"    Source: \ \&
   8 .\"  Language: English
   9 .\"
  10 .TH "SOCKET_WRAPPER" "1" "2018\-11\-28" "\ \&" "\ \&"
  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 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  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\fR
  35 .SH "DESCRIPTION"
  36 .sp
  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\&.
  38 .sp
  39 .RS 4
  40 .ie n \{\
  41 \h'-04'\(bu\h'+03'\c
  42 .\}
  43 .el \{\
  44 .sp -1
  45 .IP \(bu 2.3
  46 .\}
  47 Redirects all network communication to happen over Unix sockets\&.
  48 .RE
  49 .sp
  50 .RS 4
  51 .ie n \{\
  52 \h'-04'\(bu\h'+03'\c
  53 .\}
  54 .el \{\
  55 .sp -1
  56 .IP \(bu 2.3
  57 .\}
  58 Support for IPv4 and IPv6 socket and addressing emulation\&.
  59 .RE
  60 .sp
  61 .RS 4
  62 .ie n \{\
  63 \h'-04'\(bu\h'+03'\c
  64 .\}
  65 .el \{\
  66 .sp -1
  67 .IP \(bu 2.3
  68 .\}
  69 Ability to capture network traffic in pcap format\&.
  70 .RE
  71 .SH "ENVIRONMENT VARIABLES"
  72 .PP
  73 \fBSOCKET_WRAPPER_DIR\fR
  74 .RS 4
  75 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\&.
  76 .RE
  77 .PP
  78 \fBSOCKET_WRAPPER_IPV4_NETWORK\fR
  79 .RS 4
  80 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"\&.
  81 .RE
  82 .PP
  83 \fBSOCKET_WRAPPER_DEFAULT_IFACE\fR
  84 .RS 4
  85 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\&.
  86 .RE
  87 .PP
  88 \fBSOCKET_WRAPPER_PCAP_FILE\fR
  89 .RS 4
  90 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\&.
  91 .RE
  92 .PP
  93 \fBSOCKET_WRAPPER_MTU\fR
  94 .RS 4
  95 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\&.
  96 .RE
  97 .sp
  98 The minimum value you can set is 512 and the maximum 32768\&.
  99 .PP
 100 \fBSOCKET_WRAPPER_MAX_SOCKETS\fR
 101 .RS 4
 102 This variable can be used to set the maximum number of sockets to be used by an application\&.
 103 .RE
 104 .sp
 105 The default value is set to 65535 and the maximum 256000\&.
 106 .PP
 107 \fBSOCKET_WRAPPER_DEBUGLEVEL\fR
 108 .RS 4
 109 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\&.
 110 .sp
 111 .RS 4
 112 .ie n \{\
 113 \h'-04'\(bu\h'+03'\c
 114 .\}
 115 .el \{\
 116 .sp -1
 117 .IP \(bu 2.3
 118 .\}
 119 0 = ERROR
 120 .RE
 121 .sp
 122 .RS 4
 123 .ie n \{\
 124 \h'-04'\(bu\h'+03'\c
 125 .\}
 126 .el \{\
 127 .sp -1
 128 .IP \(bu 2.3
 129 .\}
 130 1 = WARNING
 131 .RE
 132 .sp
 133 .RS 4
 134 .ie n \{\
 135 \h'-04'\(bu\h'+03'\c
 136 .\}
 137 .el \{\
 138 .sp -1
 139 .IP \(bu 2.3
 140 .\}
 141 2 = DEBUG
 142 .RE
 143 .sp
 144 .RS 4
 145 .ie n \{\
 146 \h'-04'\(bu\h'+03'\c
 147 .\}
 148 .el \{\
 149 .sp -1
 150 .IP \(bu 2.3
 151 .\}
 152 3 = TRACE
 153 .RE
 154 .RE
 155 .PP
 156 \fBSOCKET_WRAPPER_DISABLE_DEEPBIND\fR
 157 .RS 4
 158 This allows you to disable deep binding in socket_wrapper\&. This is useful for running valgrind tools or sanitizers like (address, undefined, thread)\&.
 159 .RE
 160 .PP
 161 \fBSOCKET_WRAPPER_DIR_ALLOW_ORIG\fR
 162 .RS 4
 163 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\&.
 164 .RE
 165 .SH "EXAMPLE"
 166 .sp
 167 .if n \{\
 168 .RS 4
 169 .\}
 170 .nf
 171 # Open a console and create a directory for the unix sockets\&.
 172 $ mktemp \-d
 173 /tmp/tmp\&.bQRELqDrhM
 174 .fi
 175 .if n \{\
 176 .RE
 177 .\}
 178 .sp
 179 .if n \{\
 180 .RS 4
 181 .\}
 182 .nf
 183 # Then start nc to listen for network traffic using the temporary directory\&.
 184 $ LD_PRELOAD=libsocket_wrapper\&.so \e
 185   SOCKET_WRAPPER_DIR=/tmp/tmp\&.bQRELqDrhM \e
 186   SOCKET_WRAPPER_DEFAULT_IFACE=10 nc \-v \-l 127\&.0\&.0\&.10 7
 187 .fi
 188 .if n \{\
 189 .RE
 190 .\}
 191 .sp
 192 .if n \{\
 193 .RS 4
 194 .\}
 195 .nf
 196 # (If nc, listens on 0\&.0\&.0\&.0 then listener will be open on 127\&.0\&.0\&.10 because
 197 #  it is the default interface)
 198 .fi
 199 .if n \{\
 200 .RE
 201 .\}
 202 .sp
 203 .if n \{\
 204 .RS 4
 205 .\}
 206 .nf
 207 # Now open another console and start \*(Aqnc\*(Aq as a client to connect to the server:
 208 $ LD_PRELOAD=libsocket_wrapper\&.so \e
 209   SOCKET_WRAPPER_DIR=/tmp/tmp\&.bQRELqDrhM \e
 210   SOCKET_WRAPPER_DEFAULT_IFACE=100 nc \-v 127\&.0\&.0\&.10 7
 211 .fi
 212 .if n \{\
 213 .RE
 214 .\}
 215 .sp
 216 .if n \{\
 217 .RS 4
 218 .\}
 219 .nf
 220 # (The client will use the address 127\&.0\&.0\&.100 when connecting to the server)
 221 # Now you can type \*(AqHello!\*(Aq which will be sent to the server and should appear
 222 # in the console output of the server\&.
 223 .fi
 224 .if n \{\
 225 .RE
 226 .\}
 227 .SH "AUTHOR"
 228 .PP
 229 \fBSamba Team\fR
 230 .RS 4
 231 Author.
 232 .RE