summaryrefslogtreecommitdiff
path: root/socket_wrapper.html
blob: c5cacb200659f037dedb35d950bafb3400623ae9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
<!DOCTYPE html>
<html lang="en"><head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="description" content="">
    <meta name="author" content="">
    <link rel="shortcut icon" href="/favicon.png">

    <title>cwrap - socket_wrapper</title>

    <!-- Bootstrap core CSS -->
    <link href="assets/css/bootstrap.min.css" rel="stylesheet">

    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
    <!--[if lt IE 9]>
      <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
      <script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
    <![endif]-->
  <link href="assets/cwrap.css" type="text/css" rel="stylesheet"></head>

  <body>
    <div class="container subpage-header">
      <div class="">
        <a href="/">cwrap</a>
      </div>
    </div>

    <div class="container subpage">
        <h1>The socket_wrapper library</h1>
        <!-- Example row of columns -->
        <div class="row">
            <div class="col-md-12">
                <p>socket_wrapper is a library passing all socket
                communications through unix sockets.</p>

                <br />

                <p align="center">
                <a class="btn btn-warning btn-lg" role="button" href="https://git.samba.org/?p=socket_wrapper.git"><span class="glyphicon glyphicon-random"></span> Clone with git</a> ยท
                <a class="btn btn-danger btn-lg" role="button" href="https://bugzilla.samba.org/enter_bug.cgi?product=cwrap"><span class="glyphicon glyphicon-send"></span> Report a bug</a>

                <br />
                <br />
                <br />

                <video width="920" height="285" autoplay>
                    <source src="swrap/swrap.webm" type='video/webm;codecs="vp8, vorbis"' />
                    <source src="swrap/swrap.mp4" type='video/mp4;codecs="avc1.42E01E, mp4a.40.2"' />
                    <img src="swrap/swrap.png" width="920" height="285" />
                </video>
                </p>

                <br />

                <h2>Features</h2>

                <p>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.</p>

                <ul>
                    <li>Redirects all network communication to happen over unix sockets.</li>
                    <li>Support for IPv4 and IPv6 socket and addressing emulation.</li>
                    <li>Ablility to capture network traffic in pcap format.</li>
                </ul>

                <h2>Detailed descriptions</h2>

                <p>The idea and the first incarnation of socket_wrapper has
                been written by Jelmer Vernooij in 2005. It made it possible to
                run the Samba torture suite against smbd in 'make test'. Since
                then socket_wrapper has evolved significantly.</p>

                <p>How does it work? 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.</p>

                <p>Additionally, the default interface to be used by an
                application is defined with
                "SOCKET_WRAPPER_DEFAULT_IFACE=&lt;ID&gt;" where &lt;ID&gt; is
                between 2 and 40. We limited the address space for performance
                reasons in the case of broadcasts. This is analogous to use the
                IPv4 addresses "127.0.0.&lt;ID&gt;" or IPv6 addresses
                "fd00::5357:5f&lt;IDx&gt;" (where &lt;IDx&gt; is a hexadecimal
                presentation of &lt;ID&gt;).  You should always set the default
                interface. If you listen on INADDR_ANY then it will use the
                default interface to listen on.</p>

                <p>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
                <a href="https://www.wireshark.org/" target="_blank">Wireshark</a>
                </p>

                <h2>Example</h2>
<pre># 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 cause 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=20 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.</pre>


            </div> <!-- /col -->
        </div>

    </div>
    <div class="container footer-line">
      <footer>
      <div class="row footer">
        <div class="col-md-6">
          <h3>Contact</h3>
          <p><a href="https://lists.samba.org/mailman/listinfo/samba-technical" target="_blank">samba-technical@lists.samba.org</a></p>
        </div>

        <div class="col-md-3 col-md-offset-3">
          <h3>Credits</h3>
          <p>Jelmer Vernooij<br />
          Stefan Metzmacher<br />
          Jakub Hrozek<br />
          Andreas Schneider</p>
        </div>
      </div>
      </footer>
   </div> <!-- /container -->

   <!-- Bootstrap core JavaScript
        ================================================== -->
   <!-- Placed at the end of the document so the pages load faster -->
   <script src="assets/js/jquery-1.js"></script>
   <script src="assets/js/bootstrap.min.js"></script>
   <!-- Piwik -->
   <script type="text/javascript">
     var _paq = _paq || [];
     _paq.push(["trackPageView"]);
     _paq.push(["enableLinkTracking"]);

     (function() {
       var u=(("https:" == document.location.protocol) ? "https" : "http") + "://cia.cryptomilk.org/";
       _paq.push(["setTrackerUrl", u+"piwik.php"]);
       _paq.push(["setSiteId", "3"]);
       var d=document, g=d.createElement("script"), s=d.getElementsByTagName("script")[0]; g.type="text/javascript";
       g.defer=true; g.async=true; g.src=u+"piwik.js"; s.parentNode.insertBefore(g,s);
     })();
   </script>
   <!-- End Piwik Code -->

</body></html>