Commit f914a1eb authored by Andreas Schneider's avatar Andreas Schneider

doc: Add a socket_wrapper manpage.

parent 57029101
......@@ -83,3 +83,4 @@ install(
devel
)
add_subdirectory(doc)
Socket wrapper library
=======================
This library makes possible to run several instances of the full software stack
on the same machine and perform locally functional testing of complex network
configurations. It passes all socket communication over unix domain sockets.
The user defines a directory where to put all the unix sockets using the
envionment 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.
Additionally, the default interface to be used by an application is defined
with "SOCKET_WRAPPER_DEFAULT_IFACE=<ID>" where <ID> is between 2 and 254. This
is analogous to use the IPv4 addresses "127.0.0.<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.
Example:
LD_PRELOAD=libsocket_wrapper.so \
SOCKET_WRAPPER_DIR=/path/to/socket_dir \
./mydaemon
The following environment variables could also be set:
SOCKET_WRAPPER_DEFAULT_IFACE
The default interface to use if nothing has
been set trough the functions.
Set it to '11' for '127.0.0.11'.
SOCKET_WRAPPER_PCAP_FILE
If set then all traffic will be written to the
specified pcap file.
SOCKET_WRAPPER_DEBUGLEVEL
If you socket_wrapper with with debug symbols
you can turn on logging by setting this to an
integer between 1 and 3.
0 = ERROR
1 = WARNING
2 = DEBUG
3 = TRACE
SOCKET_WRAPPER
==============
This is a library passing all socket communications through unix sockets.
DESCRIPTION
-----------
More details can be found in the manpage:
man -l ./doc/socket_wrapper.1
or the raw text version:
less ./doc/socket_wrapper.1.txt
For installation instructions please take a look at the README.install file.
MAILINGLIST
-----------
As the mailing list samba-technical is used and can be found here:
https://lists.samba.org/mailman/listinfo/samba-technical
install(FILES
socket_wrapper.1
DESTINATION
${MAN_INSTALL_DIR}/man1)
The manpage is written with asciidoc. To generate the manpage use:
a2x --doctype manpage --format manpage doc/socket_wrapper.1.txt
'\" t
.\" Title: socket_wrapper
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\" Date: 07/09/2014
.\" Manual: \ \&
.\" Source: \ \&
.\" Language: English
.\"
.TH "SOCKET_WRAPPER" "1" "07/09/2014" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.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\fR
.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
.\}
Ablility to capture network traffic in pcap format\&.
.RE
.SH "ENVIRONMENT VARIABLES"
.PP
\fBSOCKET_WRAPPER_DIR\fR
.RS 4
The user defines a directory where to put all the unix sockets using the envionment 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_DEFAULT_IFACE\fR
.RS 4
Additionally, the default interface to be used by an application is defined with "SOCKET_WRAPPER_DEFAULT_IFACE=<ID>" where <ID> is between 2 and 254\&. This is analogous to use the IPv4 addresses "127\&.0\&.0\&.<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
.PP
\fBSOCKET_WRAPPER_PCAP_FILE\fR
.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
.PP
\fBSOCKET_WRAPPER_DEBUGLEVEL\fR
.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
.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 \e
SOCKET_WRAPPER_DIR=/tmp/tmp\&.bQRELqDrhM \e
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 \e
SOCKET_WRAPPER_DIR=/tmp/tmp\&.bQRELqDrhM \e
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
.\}
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.
- Ablility to capture network traffic in pcap format.
ENVIRONMENT VARIABLES
---------------------
*SOCKET_WRAPPER_DIR*::
The user defines a directory where to put all the unix sockets using the
envionment 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_DEFAULT_IFACE*::
Additionally, the default interface to be used by an application is defined
with "SOCKET_WRAPPER_DEFAULT_IFACE=<ID>" where <ID> is between 2 and 254. This
is analogous to use the IPv4 addresses "127.0.0.<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_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
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.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment