archref.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
   2 <html>
   3   <head>
   4     <title>DLIFE distributed architecture reference</title>
   5   </head>
   6
   7   <body bgcolor="#ffffff">
   8     <h1>DLIFE distributed architecture reference</h1>
   9
  10     <p>
  11       DLIFE is distributed, meaning that many people
  12       may allocate their spare computing cycles and
  13       memory in order to form something which approximates
  14       a very large single soup. Actually modelling a
  15       very large soup, however, would be very difficult:
  16       such a program would have a high communication
  17       overhead, would be totally unsuitable to run on
  18       the Internet, and adding nodes to this would bring
  19       diminishing returns. Therefore DLIFE uses a simpler
  20       model: individual computers run small soups, and
  21       from time to time, soups exchange a few cells at
  22       random with each other. In effect we form a series
  23       of islands connected by archipelagoes.
  24     </p>
  25
  26     <h2>Processes</h2>
  27
  28     <p>
  29       There are currently three processes involved:
  30     </p>
  31
  32     <ul>
  33       <li> <b>dlife_soup</b>: This program runs continuously,
  34         one on each client CPU, simulating a single soup.
  35         It is written in C and designed to be as small and
  36         fast as possible. This is the only part of DLIFE which
  37         clients need to run all the time.
  38       <li> <b>dlife_client.pl</b>: This is a Perl script which
  39         runs infrequently (normally once per hour, but it
  40         could be more or less often, or it could be run
  41         on-demand when a PPP connection is brought up). The Perl script is
  42         responsible for exchanging cells with the DLIFE server.
  43       <li> <b>dlife_server.pl</b>: This is the DLIFE server
  44         script. It only runs on servers (obviously). It acts
  45         as a repository for cells being exchanged between
  46         clients.
  47     </ul>
  48
  49     <p>
  50       The following diagram shows the interaction between these
  51       three programs.
  52     </p>
  53
  54     <img src="archproc.gif"
  55       alt="[Diagram] Interaction between DLIFE processes"
  56       width=491 height=475>
  57
  58     <p>
  59       As shown, there are five client computers and two
  60       servers. The second client computer has two CPUs,
  61       and runs dlife_soup continuously on both. The
  62       third client computer is connected to the Internet
  63       by a modem, and so runs dlife_client.pl from
  64       <tt>/etc/ppp/ip-up.local</tt> (this script runs whenever
  65       the Internet connection is brought up). All the
  66       other computers are permanently connected to the
  67       Internet, and dlife_client.pl runs periodically
  68       from <tt>cron</tt>. Clients may connect and exchange
  69       cells with more than one server. In the diagram
  70       above, the third client computer connects to
  71       both servers.
  72     </p>
  73
  74     <h2>Cells in files</h2>
  75
  76     <p>
  77       The long-running dlife_soup program does not
  78       contain any network code. All network communications
  79       are handled by dlife_client.pl. Instead, dlife_soup
  80       contains code to save and load cells to files.
  81     </p>
  82
  83     <p>
  84       dlife_soup saves (by default) six cells per hour,
  85       at random, into the directory:
  86     </p>
  87
  88     <p>
  89       <tt>/var/spool/dlife/outgoing/</tt>
  90     </p>
  91
  92     <p>
  93       dlife_soup loads (by default) four cells per hour,
  94       at random, from the directory:
  95     </p>
  96
  97     <p>
  98       <tt>/var/spool/dlife/incoming/</tt>
  99     </p>
 100
 101     <p>
 102       The dlife_client.pl program takes some cells at
 103       random from the <tt>outgoing</tt> spool
 104       directory and uploads them to one or more servers
 105       (see the <a href="#conf">configuration section</a>
 106       below). It then asks the server(s) to send some
 107       cells, and it saves these in the <tt>incoming</tt>
 108       spool directory.
 109     </p>
 110
 111     <p>
 112       The dlife_server.pl program listens for client
 113       connections, and uploads or downloads cells. It
 114       saves its cells in the directory:
 115     </p>
 116
 117     <p>
 118       <tt>/var/spool/dlife/store/</tt>
 119     </p>
 120
 121     <h2>DLIFE network protocol</h2>
 122
 123     <p>
 124       The DLIFE network protocol is a very simple
 125       ASCII based protocol, similar to (but much
 126       more limited than) FTP.
 127     </p>
 128
 129     <p>
 130       Servers listen for connections on port 5904.
 131       When a client connects, they send back the following
 132       identifying string:
 133     </p>
 134
 135 <pre>
 136 DLIFE SERVER &lt;version&gt; &lt;protocol&gt; &lt;CR&gt; &lt;LF&gt;
 137 </pre>
 138
 139     <p>
 140       <tt>&lt;version&gt;</tt> is the server version, for
 141       information only.
 142     </p>
 143
 144     <p>
 145       <tt>&lt;protocol&gt;</tt> is the protocol version. The
 146       protocol described below is version 1.x (for some digit
 147       ``x''). If a server reports a different major version
 148       number (eg. 2.x) then this is an indication that the
 149       protocol has changed dramatically and current clients
 150       should give up and abort.
 151     </p>
 152
 153     <p>
 154       Clients connect to servers on port 5904 and
 155       issue a series of simple four letter commands.
 156       Each command should take the form:
 157     </p>
 158
 159 <pre>
 160 &lt;command&gt; [ &lt;space&gt; &lt;arguments ...&gt; ] &lt;CR&gt; &lt;LF&gt;
 161 </pre>
 162
 163     <p>
 164       There are currently four commands: <tt>HELO</tt>,
 165       <tt>STOR</tt>, <tt>RETR</tt> and <tt>QUIT</tt>.
 166     </p>
 167
 168     <p>
 169       Servers respond to commands with a three digit
 170       response code and some optional human-readable text:
 171     </p>
 172
 173 <pre>
 174 XYZ [ &lt;space&gt; text ... ] &lt;CR&gt; &lt;LF&gt;
 175 </pre>
 176
 177     <p>
 178       Of the response code, only the first digit (``<tt>X</tt>'')
 179       is meaningful to clients. As for FTP, this digit can
 180       have the following meanings:
 181     </p>
 182
 183     <table border=1>
 184       <tr>
 185         <th> Response code </th> <th> Meaning </th>
 186       </tr>
 187       <tr>
 188         <td> 1xx </td>
 189         <td> Command OK. Ready to send data, <i>or</i> ready
 190           to receive data.
 191         </td>
 192       </tr>
 193       <tr>
 194         <td> 2xx </td>
 195         <td> Command OK. Ready for your next command.
 196         </td>
 197       </tr>
 198       <tr>
 199         <td> 4xx </td>
 200         <td> Temporary error. The client can retry the last command
 201           without modification and it may well succeed next time.
 202         </td>
 203       </tr>
 204       <tr>
 205         <td> 5xx </td>
 206         <td> Error. The client should not just retry the same
 207           command, but needs to reformulate the command or
 208           cancel the operation and report an error back to the
 209           user.
 210         </td>
 211       </tr>
 212     </table>
 213
 214     <h3>The HELO command</h3>
 215
 216     <p>
 217       The <tt>HELO</tt> command has the following form:
 218     </p>
 219
 220 <pre>
 221 HELO &lt;space&gt; &lt;client_hostname&gt;
 222           &lt;space&gt; &lt;client_version&gt; &lt;CR&gt; &lt;LF&gt;
 223 </pre>
 224
 225     <p>
 226       where &lt;client_hostname&gt; is the client
 227       hostname (or the client may just send "-" character)
 228       and &lt;client_version&gt; is the client version
 229       number, used just for information only.
 230     </p>
 231
 232     <p>
 233       The server should always respond with 2xx to
 234       this command.
 235     </p>
 236
 237     <p>
 238       A typical interaction:
 239     </p>
 240
 241 <pre>
 242 &gt; HELO - 0.0.12
 243 &lt; 200 Hello.
 244 </pre>
 245
 246     <h3>The STOR command</h3>
 247
 248     <p>
 249       The <tt>STOR</tt> command is used to upload a single
 250       cell to the server.
 251     </p>
 252
 253     <p>
 254       The format of the command is:
 255     </p>
 256
 257 <pre>
 258 STOR &lt;CR&gt; &lt;LF&gt;
 259 </pre>
 260
 261     <p>
 262       If the server accepts the command and is ready to
 263       upload a cell, it will reply with a 1xx response.
 264       The client should then send the cell as a series
 265       of hex nybbles, terminated by the sequence
 266       <tt>&lt;CR&gt; &lt;LF&gt; . &lt;CR&gt; &lt;LF&gt;</tt>.
 267     </p>
 268
 269     <p>
 270       A typical interaction:
 271     </p>
 272
 273 <pre>
 274 &gt; STOR
 275 &lt; 100 Send me the cell, terminated by ".".
 276 &gt; 00000000010901010100002227
 277 &gt; 0000000100FFFFFFFFFFFFFFFF
 278 &gt;      :      :
 279 &gt;      :      :
 280 &gt; 00010000002402020202020202022027
 281 &gt; 0001010101
 282 &gt; .
 283 &lt; 200 Cell was uploaded OK.
 284 </pre>
 285
 286     <p>
 287       Servers will typically have limitations on the
 288       number and type of cells that they will accept.
 289       Generally they will only accept a small number
 290       of uploads per session, and each cell will be
 291       limited to 8192 bytes or less.
 292     </p>
 293
 294     <h3>The RETR command</h3>
 295
 296     <p>
 297       The <tt>RETR</tt> command is used to download
 298       a cell from the cell bank. The format of the command
 299       is:
 300     </p>
 301
 302 <pre>
 303 RETR &lt;CR&gt; &lt;LF&gt;
 304 </pre>
 305
 306     <p>
 307       If the server is ready to serve a cell, it will
 308       reply with a 1xx response, followed by a series
 309       of hex nybbles and terminated by the
 310       sequence
 311       <tt>&lt;CR&gt; &lt;LF&gt; . &lt;CR&gt; &lt;LF&gt;</tt>
 312       and immediately followed by a 2xx response.
 313     </p>
 314
 315     <p>
 316       A typical interaction:
 317     </p>
 318
 319 <pre>
 320 &gt; RETR
 321 &lt; 100 OK. Sending you a cell.
 322 &lt; 00000000010901010100002227
 323 &lt; 0000000100FFFFFFFFFFFFFFFF
 324 &lt;      :      :
 325 &lt;      :      :
 326 &lt; 00010000002402020202020202022027
 327 &lt; 0001010101
 328 &lt; .
 329 &lt; 200 Cell was sent OK.
 330 </pre>
 331
 332     <h3>The QUIT command</h3>
 333
 334     <p>
 335       The <tt>QUIT</tt> command terminates a session
 336       (clients may also just close a session).
 337     </p>
 338
 339     <p>
 340       The format of the command is:
 341     </p>
 342
 343 <pre>
 344 QUIT &lt;CR&gt; &lt;LF&gt;
 345 </pre>
 346
 347     <p>
 348       The server responds with a 2xx message and then
 349       closes its end of the connection.
 350     </p>
 351
 352     <p>
 353       A typical interaction:
 354     </p>
 355
 356 <pre>
 357 &gt; QUIT
 358 &lt; 200 Goodbye.
 359 <i>(socket is closed)</i>
 360 </pre>
 361
 362     <a name="conf"><h2>Configuration files</h2></a>
 363
 364     <h3>/etc/dlife/client.conf</h3>
 365
 366     <p>
 367       This file is used to configure the network client.
 368       The file tells the client which server or servers
 369       to connect to.
 370     </p>
 371
 372     <p>
 373       The client can be configured to:
 374     </p>
 375
 376     <ul>
 377       <li> Download a list of servers from a web page.
 378       <li> Contact only servers in the current ``zone'' (eg.
 379         only servers in the UK or Europe). And/or:
 380       <li> Contact servers directly by name.
 381     </ul>
 382
 383     <h4>server_url command</h4>
 384
 385     <p>
 386       The <tt>server_url</tt> command may be optionally
 387       given. It directs the client to download the web
 388       page given in the URL. The web page should contain
 389       a master list of servers.
 390     </p>
 391
 392 <pre>
 393 server_url <a href="http://dlife.annexia.org/servers.txt">http://dlife.annexia.org/servers.txt</a>
 394 </pre>
 395
 396     <h4>server_zone command</h4>
 397
 398     <p>
 399       The <tt>server_zone</tt> command is optional. It
 400       should be used in conjunction with the
 401       <tt>server_url</tt> command. It
 402       directs the client to only consider servers
 403       in the particular zone or zones listed.
 404     </p>
 405
 406     <p>
 407       The general form is:
 408     </p>
 409
 410 <pre>
 411 server_zone &lt;zone&gt; [&lt;zone&gt; [...]]
 412 </pre>
 413
 414     <p>
 415       Each <tt>&lt;zone&gt;</tt> argument should have the
 416       form:
 417     </p>
 418
 419     <ul>
 420       <li> An ISO3166 country code, eg. <tt>uk</tt>, <tt>us</tt>. Or:
 421       <li> A geographical continent, eg. <tt>eu</tt>. Or:
 422       <li> A domain name, preceeded by a dot ("."),
 423         eg. <tt>.bibliotech.net</tt>.
 424     </ul>
 425
 426     <h4>server command</h4>
 427
 428     <p>
 429       The <tt>server</tt> command directs the client to
 430       connect directly the server or servers listed.
 431     </p>
 432
 433 <pre>
 434 server dlife1.bibliotech.co.uk dlife2.bibliotech.co.uk
 435 </pre>
 436
 437     <h4>max_cells_upload_per_pass command</h4>
 438
 439     <p>
 440       The <tt>max_cells_upload_per_pass</tt> directs
 441       the client to attempt to upload this many cells
 442       in a pass. Note that the server probably imposes
 443       its own limit.
 444     </p>
 445
 446     <h4>max_cells_download_per_pass command</h4>
 447
 448     <p>
 449       The <tt>max_cells_download_per_pass</tt> directs
 450       the client to attempt to download this many cells
 451       in a pass. Note that the server probably imposes
 452       its own limit. It is a good idea to ensure that
 453       <tt>max_cells_upload_per_pass</tt> &gt;
 454       <tt>max_cells_download_per_pass</tt>.
 455     </p>
 456
 457     <h3>/etc/dlife/soup.conf</h3>
 458
 459     <p>
 460       The <tt>soup.conf</tt> file configures various
 461       internal aspects of the DLIFE virtual machine.
 462       For full documentation, please see the example
 463       file provided with the source distribution.
 464     </p>
 465
 466     <h2>Typical configurations</h2>
 467
 468     <h3>Default configuration</h3>
 469
 470
 471
 472
 473
 474
 475     <!-- default,
 476     modem,
 477     behind firewall
 478     -->
 479
 480
 481
 482     <hr>
 483     <address><a href="mailto:rich@annexia.org">Richard Jones</a></address>
 484 <!-- Created: Sat Oct  7 10:12:59 BST 2000 -->
 485 <!-- hhmts start -->
 486 Last modified: Wed Oct 11 23:19:19 BST 2000
 487 <!-- hhmts end -->
 488   </body>
 489 </html>