path: root/doc/socket_wrapper.1

'\" t
.\"     Title: socket_wrapper
.\"    Author: Samba Team
.\" Generator: Asciidoctor 2.0.10
.\"      Date: 2021-02-24
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "SOCKET_WRAPPER" "1" "2021-02-24" "\ \&" "\ \&"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
socket_wrapper \- A library passing all socket communications through unix sockets.
.SH "SYNOPSIS"
.sp
LD_PRELOAD=libsocket_wrapper.so SOCKET_WRAPPER_DIR=/tmp/tmp.bQRELqDrhM SOCKET_WRAPPER_DEFAULT_IFACE=10 \fB./myapplication\fP
.SH "DESCRIPTION"
.sp
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.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Redirects all network communication to happen over Unix sockets.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Support for IPv4 and IPv6 socket and addressing emulation.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Ability to capture network traffic in pcap format.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Passing IP sockets (up to 6) via SCM_RIGHTS is supported,
but pcap support only works reliable if the socket is used
by a single process at a time.
.RE
.SH "ENVIRONMENT VARIABLES"
.sp
\fBSOCKET_WRAPPER_DIR\fP
.RS 4
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.
.RE
.sp
\fBSOCKET_WRAPPER_IPV4_NETWORK\fP
.RS 4
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".
.RE
.sp
\fBSOCKET_WRAPPER_DEFAULT_IFACE\fP
.RS 4
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.
.RE
.sp
\fBSOCKET_WRAPPER_PCAP_FILE\fP
.RS 4
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.
.RE
.sp
\fBSOCKET_WRAPPER_MTU\fP
.RS 4
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.
.RE
.sp
The minimum value you can set is 512 and the maximum 32768.
.sp
\fBSOCKET_WRAPPER_MAX_SOCKETS\fP
.RS 4
This variable can be used to set the maximum number of sockets to be used by
an application.
.RE
.sp
The default value is set to 65535 and the maximum 256000.
.sp
\fBSOCKET_WRAPPER_DEBUGLEVEL\fP
.RS 4
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.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
0 = ERROR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
1 = WARNING
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
2 = DEBUG
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
3 = TRACE
.RE
.RE
.sp
\fBSOCKET_WRAPPER_DISABLE_DEEPBIND\fP
.RS 4
This allows you to disable deep binding in socket_wrapper. This is useful for
running valgrind tools or sanitizers like (address, undefined, thread).
.RE
.sp
\fBSOCKET_WRAPPER_DIR_ALLOW_ORIG\fP
.RS 4
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.
.RE
.SH "EXAMPLE"
.sp
.if n .RS 4
.nf
# Open a console and create a directory for the unix sockets.
$ mktemp \-d
/tmp/tmp.bQRELqDrhM
.fi
.if n .RE
.sp
.if n .RS 4
.nf
# Then start nc to listen for network traffic using the temporary directory.
$ LD_PRELOAD=libsocket_wrapper.so \(rs
  SOCKET_WRAPPER_DIR=/tmp/tmp.bQRELqDrhM \(rs
  SOCKET_WRAPPER_DEFAULT_IFACE=10 nc \-v \-l 127.0.0.10 7
.fi
.if n .RE
.sp
.if n .RS 4
.nf
# (If nc, listens on 0.0.0.0 then listener will be open on 127.0.0.10 because
#  it is the default interface)
.fi
.if n .RE
.sp
.if n .RS 4
.nf
# Now open another console and start \(aqnc\(aq as a client to connect to the server:
$ LD_PRELOAD=libsocket_wrapper.so \(rs
  SOCKET_WRAPPER_DIR=/tmp/tmp.bQRELqDrhM \(rs
  SOCKET_WRAPPER_DEFAULT_IFACE=100 nc \-v 127.0.0.10 7
.fi
.if n .RE
.sp
.if n .RS 4
.nf
# (The client will use the address 127.0.0.100 when connecting to the server)
# Now you can type \(aqHello!\(aq which will be sent to the server and should appear
# in the console output of the server.
.fi
.if n .RE
.SH "PUBLIC FUNCTIONS"
.sp
Socket wrapper advanced helpers.
.sp
Applications with the need to alter their behaviour when
socket wrapper is active, can link use these functions.
.sp
By default it\(cqs required for applications to use any of these
functions as libsocket_wrapper.so is injected at runtime via
LD_PRELOAD.
.sp
Applications using these functions should link against
libsocket_wrapper_noop.so by using \-lsocket_wrapper_noop,
or implement their own noop stubs.
.sp
#include <socket_wrapper.h>
.sp
bool socket_wrapper_enabled(void);
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
This returns true when socket wrapper is actively in use.
.RE
.sp
void socket_wrapper_indicate_no_inet_fd(int fd);
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
This allows socket_wrapper aware applications to
indicate that the given fd does not belong to
an inet socket.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
socket_wrapper may not be able to intercept the __close_nocancel()
syscall made from within libc.so. As result it\(cqs possible
that the in memory meta date of socket_wrapper references
stale file descriptors, which are already reused for unrelated
kernel objects, e.g. files, directories, ...
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Socket wrapper already intercepts a lot of unrelated
functions like eventfd(), timerfd_create(), ... in order
to remove stale meta data for the returned fd, but
it will never be able to handle all possible syscalls.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
socket_wrapper_indicate_no_inet_fd() gives applications a way
to do the same, explicitly without waiting for new syscalls to
be added to libsocket_wrapper.so.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
This is a no\-op if socket_wrapper is not in use or
if the there is no in memory meta data for the given fd.
.RE
.SH "RESOURCES"
.sp
\fBProject web site:\fP \c
.URL "https://cwrap.org" "" ""
.SH "AUTHOR"
.sp
Samba Team