From 2c3a0b5273e987cd582c0620e3cf2555d9ab8734 Mon Sep 17 00:00:00 2001 From: Andreas Schneider Date: Tue, 2 Feb 2021 10:26:07 +0100 Subject: doc: Rename socket_wrapper.1.txt to socket_wrapper.1.adoc Signed-off-by: Andreas Schneider Reviewed-by: Stefan Metzmacher --- doc/README | 2 +- doc/socket_wrapper.1.adoc | 133 ++++++++++++++++++++++++++++++++++++++++++++++ doc/socket_wrapper.1.txt | 133 ---------------------------------------------- 3 files changed, 134 insertions(+), 134 deletions(-) create mode 100644 doc/socket_wrapper.1.adoc delete mode 100644 doc/socket_wrapper.1.txt diff --git a/doc/README b/doc/README index dbe07f7..c559f6e 100644 --- a/doc/README +++ b/doc/README @@ -1,3 +1,3 @@ The manpage is written with asciidoc. To generate the manpage use: -a2x --doctype manpage --format manpage doc/socket_wrapper.1.txt +a2x --doctype manpage --format manpage doc/socket_wrapper.1.adoc diff --git a/doc/socket_wrapper.1.adoc b/doc/socket_wrapper.1.adoc new file mode 100644 index 0000000..425b08f --- /dev/null +++ b/doc/socket_wrapper.1.adoc @@ -0,0 +1,133 @@ +socket_wrapper(1) +================= +:revdate: 2021-02-01 +:author: Samba Team + +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 6) via SCM_RIGHTS is supported, + but pcap support only works reliable 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 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." 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". + +*SOCKET_WRAPPER_DEFAULT_IFACE*:: + +Additionally, the default interface to be used by an application is defined with +"SOCKET_WRAPPER_DEFAULT_IFACE=" where the valid range for starts with 1 +(the default) and ends with 64. This is analogous to use the IPv4 addresses +"127.0.0."/"10.53.57." or IPv6 addresses "fd00::5357:5f" (where + is a hexadecimal presentation of ). 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 recomment to +do that as the default size of 1500 byte 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 if you built it with +debug symbols. + +- 0 = ERROR +- 1 = WARNING +- 2 = DEBUG +- 3 = 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. diff --git a/doc/socket_wrapper.1.txt b/doc/socket_wrapper.1.txt deleted file mode 100644 index 425b08f..0000000 --- a/doc/socket_wrapper.1.txt +++ /dev/null @@ -1,133 +0,0 @@ -socket_wrapper(1) -================= -:revdate: 2021-02-01 -:author: Samba Team - -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 6) via SCM_RIGHTS is supported, - but pcap support only works reliable 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 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." 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". - -*SOCKET_WRAPPER_DEFAULT_IFACE*:: - -Additionally, the default interface to be used by an application is defined with -"SOCKET_WRAPPER_DEFAULT_IFACE=" where the valid range for starts with 1 -(the default) and ends with 64. This is analogous to use the IPv4 addresses -"127.0.0."/"10.53.57." or IPv6 addresses "fd00::5357:5f" (where - is a hexadecimal presentation of ). 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 recomment to -do that as the default size of 1500 byte 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 if you built it with -debug symbols. - -- 0 = ERROR -- 1 = WARNING -- 2 = DEBUG -- 3 = 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. -- cgit