NAME

       socket_wrapper - A library passing all socket communications through unix sockets.

SYNOPSIS

       LD_PRELOAD=libsocket_wrapper.so SOCKET_WRAPPER_DIR=/tmp/tmp.bQRELqDrhM SOCKET_WRAPPER_DEFAULT_IFACE=10
       ./myapplication

DESCRIPTION

       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.

       •   Redirects all network communication to happen over Unix sockets.

       •   Support for IPv4 and IPv6 socket and addressing emulation.

       •   Ability to capture network traffic in pcap format.

       •   Passing IP sockets (up to 16) via SCM_RIGHTS is supported, but pcap support only works reliably if
           the socket is used by a single process at a time.

ENVIRONMENT VARIABLES

       SOCKET_WRAPPER_DIR
           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.

       SOCKET_WRAPPER_IPV4_NETWORK
           By default the loopback IPv4 network "127.0.0.0/8" and "127.0.0.x" addresses 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.
           Note that within "10.0.0.0/8" only "10.53.57.<ID>" can be used, and the broadcast address is
           "10.255.255.255". The following two values are allowed: SOCKET_WRAPPER_IPV4_NETWORK="127.0.0.0" (the
           default) and SOCKET_WRAPPER_IPV4_NETWORK="10.53.57.0".

       SOCKET_WRAPPER_DEFAULT_IFACE
           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.

       SOCKET_WRAPPER_PCAP_FILE
           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’re able to open the file for example with Wireshark.

       SOCKET_WRAPPER_MTU
           With this variable you can change the MTU size. However we do not recommend doing that as the default
           size of 1500 bytes is best for formatting PCAP files.

       The minimum value you can set is 512 and the maximum 32768.

       SOCKET_WRAPPER_MAX_SOCKETS
           This variable can be used to set the maximum number of sockets to be used by an application.

       The default value is set to 65535 and the maximum 256000.

       SOCKET_WRAPPER_DEBUGLEVEL
           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.

       The debug level can be set using either numeric values or string values (case-insensitive):

       •   0 or "error" = ERROR (default)

       •   1 or "warn"/"warning" = WARNING

       •   2 or "debug" = DEBUG

       •   3 or "trace" = TRACE

           SOCKET_WRAPPER_DISABLE_DEEPBIND
               This allows you to disable deep binding in socket_wrapper. This is useful for running valgrind
               tools or sanitizers like (address, undefined, thread).

           SOCKET_WRAPPER_DIR_ALLOW_ORIG
               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.

EXAMPLE

           # Open a console and create a directory for the unix sockets.
           $ mktemp -d
           /tmp/tmp.bQRELqDrhM

           # Then start nc to listen for network traffic using the temporary directory.
           $ LD_PRELOAD=libsocket_wrapper.so \
             SOCKET_WRAPPER_DIR=/tmp/tmp.bQRELqDrhM \
             SOCKET_WRAPPER_DEFAULT_IFACE=10 nc -v -l 127.0.0.10 7

           # (If nc, listens on 0.0.0.0 then listener will be open on 127.0.0.10 because
           #  it is the default interface)

           # Now open another console and start 'nc' as a client to connect to the server:
           $ LD_PRELOAD=libsocket_wrapper.so \
             SOCKET_WRAPPER_DIR=/tmp/tmp.bQRELqDrhM \
             SOCKET_WRAPPER_DEFAULT_IFACE=100 nc -v 127.0.0.10 7

           # (The client will use the address 127.0.0.100 when connecting to the server)
           # Now you can type 'Hello!' which will be sent to the server and should appear
           # in the console output of the server.

PUBLIC FUNCTIONS

       Socket wrapper advanced helpers.

       Applications with the need to alter their behaviour when socket wrapper is active can use these
       functions.

       By default it’s not required for applications to use any of these functions as libsocket_wrapper.so is
       injected at runtime via LD_PRELOAD.

       Applications using these functions should link against libsocket_wrapper_noop.so by using
       -lsocket_wrapper_noop, or implement their own noop stubs.

       #include <socket_wrapper.h>

       bool socket_wrapper_enabled(void);

       •   This returns true when socket wrapper is actively in use.

       void socket_wrapper_indicate_no_inet_fd(int fd);

       •   This allows socket_wrapper aware applications to indicate that the given fd does not belong to an
           inet socket.

       •   socket_wrapper may not be able to intercept the __close_nocancel() syscall made from within libc.so.
           As a result it’s possible that the in-memory metadata of socket_wrapper references stale file
           descriptors, which are already reused for unrelated kernel objects, e.g. files, directories, ...

       •   Socket wrapper already intercepts a lot of unrelated functions like eventfd(), timerfd_create(), ...
           in order to remove stale metadata for the returned fd, but it will never be able to handle all
           possible syscalls.

       •   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.

       •   This is a no-op if socket_wrapper is not in use or if there is no in-memory metadata for the given
           fd.

RESOURCES

       Project web site: https://cwrap.org

AUTHOR

       Samba Team

                                                   2025-12-14                                  SOCKET_WRAPPER(1)