From: Andreas Schneider Date: Tue, 2 Feb 2021 09:30:04 +0000 (+0100) Subject: doc: Add website to manpage X-Git-Tag: socket_wrapper-1.3.0~1 X-Git-Url: http://git.samba.org/?p=socket_wrapper.git;a=commitdiff_plain;h=e89968d2bef7b142462262f43c2ea7024a9ef8ab doc: Add website to manpage Signed-off-by: Andreas Schneider Reviewed-by: Stefan Metzmacher --- diff --git a/doc/socket_wrapper.1 b/doc/socket_wrapper.1 index 3bd171e..0272c63 100644 --- a/doc/socket_wrapper.1 +++ b/doc/socket_wrapper.1 @@ -1,50 +1,53 @@ '\" t .\" Title: socket_wrapper .\" Author: Samba Team -.\" Generator: DocBook XSL Stylesheets v1.79.1 -.\" Date: 2021-02-01 +.\" Generator: Asciidoctor 2.0.12 +.\" Date: 2021-02-02 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "SOCKET_WRAPPER" "1" "2021\-02\-01" "\ \&" "\ \&" -.\" ----------------------------------------------------------------- -.\" * Define some portability stuff -.\" ----------------------------------------------------------------- -.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.\" http://bugs.debian.org/507673 -.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html -.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.TH "SOCKET_WRAPPER" "1" "2021-02-02" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' -.\" ----------------------------------------------------------------- -.\" * set default formatting -.\" ----------------------------------------------------------------- -.\" disable hyphenation +.ss \n[.ss] 0 .nh -.\" disable justification (adjust text to left margin only) .ad l -.\" ----------------------------------------------------------------- -.\" * MAIN CONTENT STARTS HERE * -.\" ----------------------------------------------------------------- +.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\&. +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\fR +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\&. +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 +. sp -1 +. IP \(bu 2.3 .\} -Redirects all network communication to happen over Unix sockets\&. +Redirects all network communication to happen over Unix sockets. .RE .sp .RS 4 @@ -52,10 +55,10 @@ Redirects all network communication to happen over Unix sockets\&. \h'-04'\(bu\h'+03'\c .\} .el \{\ -.sp -1 -.IP \(bu 2.3 +. sp -1 +. IP \(bu 2.3 .\} -Support for IPv4 and IPv6 socket and addressing emulation\&. +Support for IPv4 and IPv6 socket and addressing emulation. .RE .sp .RS 4 @@ -63,10 +66,10 @@ Support for IPv4 and IPv6 socket and addressing emulation\&. \h'-04'\(bu\h'+03'\c .\} .el \{\ -.sp -1 -.IP \(bu 2.3 +. sp -1 +. IP \(bu 2.3 .\} -Ability to capture network traffic in pcap format\&. +Ability to capture network traffic in pcap format. .RE .sp .RS 4 @@ -74,58 +77,85 @@ Ability to capture network traffic in pcap format\&. \h'-04'\(bu\h'+03'\c .\} .el \{\ -.sp -1 -.IP \(bu 2.3 +. 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\&. +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" -.PP -\fBSOCKET_WRAPPER_DIR\fR +.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\&. +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 -.PP -\fBSOCKET_WRAPPER_IPV4_NETWORK\fR +.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\&." 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"\&. +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". .RE -.PP -\fBSOCKET_WRAPPER_DEFAULT_IFACE\fR +.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=" 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\&. +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. .RE -.PP -\fBSOCKET_WRAPPER_PCAP_FILE\fR +.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\&. +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 -.PP -\fBSOCKET_WRAPPER_MTU\fR +.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\&. +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\&. -.PP -\fBSOCKET_WRAPPER_MAX_SOCKETS\fR +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\&. +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\&. -.PP -\fBSOCKET_WRAPPER_DEBUGLEVEL\fR +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\&. +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 +. sp -1 +. IP \(bu 2.3 .\} 0 = ERROR .RE @@ -135,8 +165,8 @@ If you need to see what is going on in socket_wrapper itself or try to find a bu \h'-04'\(bu\h'+03'\c .\} .el \{\ -.sp -1 -.IP \(bu 2.3 +. sp -1 +. IP \(bu 2.3 .\} 1 = WARNING .RE @@ -146,8 +176,8 @@ If you need to see what is going on in socket_wrapper itself or try to find a bu \h'-04'\(bu\h'+03'\c .\} .el \{\ -.sp -1 -.IP \(bu 2.3 +. sp -1 +. IP \(bu 2.3 .\} 2 = DEBUG .RE @@ -157,87 +187,85 @@ If you need to see what is going on in socket_wrapper itself or try to find a bu \h'-04'\(bu\h'+03'\c .\} .el \{\ -.sp -1 -.IP \(bu 2.3 +. sp -1 +. IP \(bu 2.3 .\} 3 = TRACE .RE .RE -.PP -\fBSOCKET_WRAPPER_DISABLE_DEEPBIND\fR +.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)\&. +This allows you to disable deep binding in socket_wrapper. This is useful for +running valgrind tools or sanitizers like (address, undefined, thread). .RE -.PP -\fBSOCKET_WRAPPER_DIR_ALLOW_ORIG\fR +.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\&. +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 -.\} +.if n .RS 4 .nf -# Open a console and create a directory for the unix sockets\&. +.fam C +# Open a console and create a directory for the unix sockets. $ mktemp \-d -/tmp/tmp\&.bQRELqDrhM +/tmp/tmp.bQRELqDrhM +.fam .fi -.if n \{\ -.RE -.\} +.if n .RE .sp -.if n \{\ -.RS 4 -.\} +.if n .RS 4 .nf -# Then start nc to listen for network traffic using the temporary directory\&. -$ LD_PRELOAD=libsocket_wrapper\&.so \e - SOCKET_WRAPPER_DIR=/tmp/tmp\&.bQRELqDrhM \e - SOCKET_WRAPPER_DEFAULT_IFACE=10 nc \-v \-l 127\&.0\&.0\&.10 7 +.fam C +# 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 +.fam .fi -.if n \{\ -.RE -.\} +.if n .RE .sp -.if n \{\ -.RS 4 -.\} +.if n .RS 4 .nf -# (If nc, listens on 0\&.0\&.0\&.0 then listener will be open on 127\&.0\&.0\&.10 because +.fam C +# (If nc, listens on 0.0.0.0 then listener will be open on 127.0.0.10 because # it is the default interface) +.fam .fi -.if n \{\ -.RE -.\} +.if n .RE .sp -.if n \{\ -.RS 4 -.\} +.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 \e - SOCKET_WRAPPER_DIR=/tmp/tmp\&.bQRELqDrhM \e - SOCKET_WRAPPER_DEFAULT_IFACE=100 nc \-v 127\&.0\&.0\&.10 7 +.fam C +# 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 +.fam .fi -.if n \{\ -.RE -.\} +.if n .RE .sp -.if n \{\ -.RS 4 -.\} +.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\&. +.fam C +# (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. +.fam .fi -.if n \{\ -.RE -.\} +.if n .RE +.SH "RESOURCES" +.sp +\fBProject web site:\fP \c +.URL "https://cwrap.org" "" "" .SH "AUTHOR" -.PP -\fBSamba Team\fR -.RS 4 -Author. -.RE +.sp +Samba Team \ No newline at end of file diff --git a/doc/socket_wrapper.1.adoc b/doc/socket_wrapper.1.adoc index 4daddda..9519fd4 100644 --- a/doc/socket_wrapper.1.adoc +++ b/doc/socket_wrapper.1.adoc @@ -132,3 +132,8 @@ EXAMPLE # (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. + +RESOURCES +--------- + +*Project web site:* https://cwrap.org