• Table of Contents
• Previous Chapter

Appendix 1: A TCP port forwarder

• A local TCP port that the program will listen to, e.g. 10000;

• A remote host name, e.g. thedailywtf.com;

• A remote port, e.g. 80.

Once started, the program will accept connections on the local TCP port. When activity is detected, then information is transmitted to and fro between the client that connects to the local port, and the remote port on the remote host.

E.g., after the invocation portfw 10000 thedailywtf.com 80 you can point your browser to http://localhost:10000/ and read The Daily WTF.

Port forwarding as such may not seem too useful, but the program is included here because it nicely illustrates all concepts of this series of lectures. Furthermore it can be used as a stepping stone for your own network related projects.

1.1: General design of the program

Parallel processing: forking or threading?

The program must be able to handle lots of client connections in parallel. We're building for speed here: many clients must be able to connect to the port forwarder, and be served. Clients will need to be serviced in parallel. As described in chapter 2, separate requests could be either served from new forks, or from new threads. In this example we'll use threads. The program will only fork in order to become a daemon.

Messaging and program stages.

The program will use three messaging modes: for errors, for warnings, and for verbosity. The working of these will differ by program stage:

• In the first phase, when the program starts, all messaging will go to stderr.

• In the second phace, when the program is a daemon, all messaging will go to the syslog() service, and will hence appear in /var/log/messages or in a similar log file.

Not implemented features.

The program portfw could be enhanced with lots of extra features, which will be left to the reader. For example:

• Verbose messaging could be turned on or off using a commandline switch -v. In the current version, verbose messaging is always on.

• The program accepts every client and tries to service it. In a production environment this could be a security risk; multiple client connections could slow down portfw during a denial of service (DoS) attack. A DoS-proof version might (a) limit the total number of connections to a given number, to avoid slowdown, and (b) limit the number of connections from a given client address when a DoS attack is suspected.

1.2: Technical description and sources

1.2.1: portfw.h: The central header

In this program all declarations and data definitions are collected in one header file, portfw.h. The inclusion of all necessary system headers also occurs here.

Noteworthy parts of the header are:

• Structure Clientinfo is a datatype that will come into play when two existing network connections are established: between a client and portfw, and between portfw and a server to which traffic is forwarded. This data type is the "thread context" of each thread that serves such an established route.

  The thread-context data consist of clientsock and serversock, two established network sockets. The sockets src and dst are used later when the program has determined how to copy; either from client to server, or vice versa.

• The flag is_daemon is initially zero, but raised once the program daemonizes. This flag is examined by the messaging functions to see whether information should go to stderr or to syslog().

• Structure remotesockaddr is the named address of the server to which all client connections are forwarded. This variable is initialized even before daemonizing, since portfw has one fixed "back end". All threads will re-use this structure.

• The header uses a small trick with a symbol EXTERN. Normally thiis symbol is not defined, which causes it to become an alias for the keyword extern -- so that global variables are normally declared, not defined. Only in main.c, this symbol is defined before portfw.h is included. That way, the object file of main.c actually defines, and not just declares, global data.

1.2.2: The main function

The main() function, located in main.c, is straight forward. It is shown without further ado; all it does is verify that all commandline arguments are present, and then call service_start().

1.2.3: Messaging-related functions: error(), warn(), msg()

The following three listings show the messaging related functions. Depending on the above-discussed flag is_daemon, information is sent either to stderr or to syslog(). In the case of syslog() a "priority" flag states what the message is about. Function error() of course also terminates the program.

1.2.3.1: error()

1.2.3.2: warn()

1.2.3.3: msg()

1.2.4: Service-related functions

1.2.4.1: service_start()

Function service_start() is called from main() and performs the following tasks:

• The address of the remote back end is resolved. It is stored in the global variable remotesockaddr. Once clients connect, the address will be used to build up a back end connection.

• The local listening socket is set up, to which clients will be able to connect.

• The process daemonizes, using the already discussed function daemonize(). The child branch calls service_run(), the parent branch returns into main() to exit.

1.2.4.2: service_run()

The function service_run(), which is called from service_start(), is the event loop of the program. New network connections on the local socket are accepted, and when e new connection is ready, a thread context Clientinfo is prepared. After that a thread is started and executed via service_thread().

Note how service_run() doesn't exit once the event loop is running. Atmost, warn() is called to send an appropriate message to syslog(), after which the event loop is resumed.

1.2.4.3: service_thread()

The actual servicing of a client connection occurs in service_thread(). It is called with an initialized context, stating a connected client socket, and a start time.

The servicing of a client connection means that first of all, a connection to the server must be established. Next, a loop is started what waits for one of the sockets to become readable (client-side or server-side). The readable socket is read, and anything that arrives there, is sent to the other socket.

A stop is detected when a network read returns that zero bytes were read.

1.2.4.4: service_connect()

The helper function service_connect() is called from service_thread(). It is responsible for establishing a connection to a server back end. The shown code demonstrates how to check for timeouts during connect() in threaded programs.

1.2.4.5: service_stop()

All thread-related exits are combined into function service_stop(). Its first argument is the thread context; actually a pointer to a Clientinfo structure that needs to be freed. Also, service_stop() closes the two network sockets that belong to the thread.

1.2.5: Other support functions

The function daemonize() was discussed before. This version performs the same tasks, but also raises the flag is_daemon.

The function gettime() returns the time since 'start of epoch' January 1st 1970 GMT. However, the time is returned as the number of microseconds. Calling gettime() repeatedly, and subtracting the returned values, provides as high resolution timer. This function is called from two places:

• service_run() logs the time stamp, and places it in a thread context, prior to callling service_thread();

• service_thread() calls it, to report on the spent time.

1.2.6: The Makefile

For completeness' sake here is also a Makefile, suitable for GNU Make.

# Central Makefile for portfw
# ---------------------------

SRC = $(wildcard *.c)
OBJ = $(patsubst %.c, %.o, $(SRC))
BIN = portfw

%.o: %.c
	$(CC) -g -O2 -Wall -c -o $@ $<

$(BIN): $(OBJ)
	$(CC) -o $(BIN) $(OBJ)
clean:
	rm -f $(OBJ)
main.o: main.c portfw.h Makefile

• Table of Contents
• Previous Chapter