****************************************************************
 [pined]
                            README

****************************************************************
 
Pined is a proxy server to enables to access a private server inside
a firewall.

In your server application, replace socket API call, such as bind and
accept, into wrapper call (provided in librssock) for these APIs so
that the server register its listening port to an pined. The pined
will create a server socket behalf of the server in a private
network. The pined relays a connection to the private sever when a
client connect to the pined.


A typical use of pined is as follows:

                                     FIREWALL
                       <internet>       ||     <private network>
 +--------+       +-------+             ||        +--------+
 | Client |+---->o| Pined |o<-----------||--------| Server |+
 +--------+|+     +-------+ port 8888   ||        +--------+|
  +--------+|                 (default) ||         +--------+
   +--------+


 Directories
=============

A source package pined-x.x.x.tar.gz is expanded into the following
directories:

  pined-x.x.x/README		this file
                pinecommon.h	common header file
                libpinesock/	library source files
                pined/		pined source files  
                samples/	sample programs
                test/		test files

 Platform
==========

Currently pined is available under only Linux.


 Install
=========

- libpinesock

 $ cd libpinesock
 $ make
 $ sudo make install

- pined

 $ cd pined
 $ make
 $ sudo make install


 Starting pined
================

As daemon in the background:
  $ pined

or without detaching from the console (debug mode):
  $ pined -d

 API
=====

pined library provides ps_* functions, which serve as corresponding
socket API functions.

- int ps_bind(int sock, int my_port, struct sockaddr *ps_addr, socklen_t ps_addrlen)

- int ps_listen(int sock, int backlog)

- int ps_accept(int ssock, struct sockaddr *caddr, socklen_t *caddr_len);


 Example
=========

The following example program illustrates the use of pined library
in typical server application.

	// create a socket for listening
	so = socket(AF_INET, SOCK_STREAM, 0);
	if (so < 0) {
		perror("socket()");
		exit(EXIT_FAILURE);
	}
	// set psaddr to the address of pined
	memset(&psaddr, 0, sizeof psaddr);
	psaddr.sin_family      = AF_INET;
	psaddr.sin_port        = htons(8888);
	psaddr.sin_addr.s_addr = pserver_ipaddr;

	port = ...; // set a port number for listening socket
	ret = ps_bind(so, port, (struct sockaddr *)&psaddr, sizeof psaddr);
	if (ret < 0) {
		exit(EXIT_FAILURE);
	}

	ret = ps_listen(so, SOMAXCONN);
	if (ret < 0) {
		exit(EXIT_FAILURE);
	}
	// wait connection from client
	cso = ps_accept(so, NULL, NULL);
	if (cso < 0) {
		exit(EXIT_FAILURE);
	}


 Protocol
==========

ps_bind(s,port,addr):
           +----------+        +-------+          +--------+
           |PrivateSrv|        | Pined |          | Client |
           +----------+        +-------+          +--------+
                |                   |                  |
                |                   |                  |
connect(s,addr) |  REQ_BIND<port>   |ls=accept(s)      |
                |------------------>|                  |
                |                   |rs=socket()       |
                |     ACK_BIND      |bind(rs,port)     |
                |<------------------|                  |
                |                   |                  |
                |                   |                  |

ps_listen(s,bl):
                |                   |                  |
                |  REQ_LISTEN(bl)   |                  |
                |------------------>|                  |
                |    ACK_LISTEN     |listen(rs,bl)     |
                |<------------------|                  |
                |                   |select(ls or rs)  |
                |                   |                  |

Connection request from client:
                |                   |  TCP CONNECTION  |
                |    ACCEPTABLE     |<---------------->|connect()
                |<------------------|set acceptable    |
                |                   |                  |

ps_accept(s):
                |                   |                  |
                |    REQ_ACCEPT     |                  |
                |------------------>|if acceptable     |
                |  ACK_ACCEPT<rs'>  |  rs'=accept(rs)  |
                |<------------------|                  |
                |                   |                  |
connect(s,addr) |-------------------->|ls'=accept(s)   |
                | REQ_CONNECT<rs'>  | |                |
                |-------------------->|ls'<=>rs'       |
                |   ACK_CONNECT     | |                |
                |<--------------------|                |
                |                   | |                |

---
Copyright (c) 2008 Kenta Hattori All Rights Reserved.