Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
SOCKET_WRAPPER(1)					     SOCKET_WRAPPER(1)

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-08		     SOCKET_WRAPPER(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=socket_wrapper&sektion=1&manpath=FreeBSD+Ports+15.0.quarterly>

home | help