NetProxy Overview
NetProxy is a transparent network proxy for legacy/COTS applications. In particular, it has been used to remap the TCP and UDP protocols used by applications to other protocols or services, such as Mockets, which provide better performance over a range of wireless and other degraded networks. Therefore, NetProxy is the component of the Agile Computing Middleware (ACM) that provides transparent integration between legacy/COTS applications and the middleware.
NetProxy also enables other forms of data and flows manipulation, all applied transparently to applications, including flows prioritization, data compression, link access control, which, similarly to protocol remapping, are regulated by policies expressed via configuration files. Commonly used in combination with Mockets, NetProxy can effectively enable the porting of applications designed for enterprise-like networks to DIL environments. To ensure complete transparency, each NetProxy requires a remote instance to perform the inverse data/flows manipulations and protocol remappings before delivering the data to destination.
NetProxy operates in two primary modes - Host mode and Gateway mode. In Host mode, NetProxy is installed an each node that runs legacy applications. In Gateway mode, it is installed on standalone nodes that sit between Local Area Network (LAN) segments and routers. Currently, Host mode and Gateway mode cannot be mixed in the same installation, but that capability will be available in the future.
When operating in Host mode (HM), NetProxy relies on the Tun/Tap driver to create a virtual network interface on the host. To use NetProxy, applications simply need to be reconfigured to use the IP address assigned to the virtual network interface. Host mode is supported on Win32 and UNIX/Linux systems. The Figure below shows a node that hosts two applications and runs NetProxy in Host mode.
When operating in Gateway mode (GM), NetProxy runs on a separate node (which is typically running UNIX/Linux) that has two network interfaces (typically Ethernet). The internal interface connects to the local LAN segment and the external interface connects to a router. The Figure below shows a WAN/MANET/SATCOM network that connects three LANs. The gateway node of each LAN runs NetProxy in Gateway mode. Legacy/COTS applications running in one of the LANs can communicate with applications in other LANs through the instances of NetProxy installed on gateway nodes.
NetProxy is available for 32/64 bit Windows and Linux Operating Systems. It was successfully tested under the following versions and distributions:
- Windows XP 32/64 bit
- Windows 7 32/64 bit
- Ubuntu Linux 12.04 LTS 32/64 bit
- Fedora 17/18/19 64 bit
- CentOS 7
The following list describes the main directories and content of the ACM NetProxy Project.
- aci/cpp/netProxy - Source files of the ACM NetProxy Project
- aci/cpp/netProxy/linux - Linux Makefiles to compile NetProxy under a 32/64 bit Linux OS.
- aci/cpp/netProxy/win32 - Microsoft Visual Studio 2017 Solution and Project files
- aci/conf - Folder containing all configuration files of NetProxy
To compile NetProxy under Windows operating systems, it is possible to open the NetProxy solution file located at aci/cpp/netProxy/win32/NetProxy.sln using Microsoft Visual Studio 2017 and build the executable from there. Alternatively, it should be possible to compile NetProxy using the Cygwin environment under Windows and one of the makefile located in the aci/cpp/netProxy/linux folder. We have never tested this latter possibility.
Before proceeding with the compilation using Visual Studio 2017, it is necessary to make sure that all third-party libraries are located in the right directories. More details on this in the Section below.
All necessary precompiled libraries are available in the externals-win directory and its subdirectories, with the sole exception of the Protobuf library. Cmake and Visual Studio 2017 are the only tools required to build the Protobuf library under Linux.
All source code for Protobuf 3.1.0 is available under the directory externals-win/protobuf/sources/. In order to compile all necessary versions of the Protobuf library from its sources under Windows, we suggest to use Cmake to generate a Visual Studio solution that can be used for compilation.
The following is a quick reference guide to build Protobuf under Windows using Cmake and Visual Studio 2017. The file externals-win/protobuf/sources/cmake/README.md contains further details on the matter and alternative building solutions.
To build the Protobuf library for X86 (Win32) Windows machines execute these commands from a command line:
cd externals-win/protobuf/sources/cmake/
mkdir build
cd build
mkdir solution_x86
cd solution_x86
cmake -G "Visual Studio 15 2017" ../..
This should create a Visual Studio 2017 solution under externals-win/protobuf/sources/cmake/build/solution_x86/. Open the solution file protobuf.sln using Visual Studio 2017, select the configuration you want to build (NetProxy requires Debug and Release versions of the library) and build the "libprotobuf" project.
Once the process is finished, and depending on the chosen build configuration, a file named libprotobufd.lib (for Debug builds) or libprotobuf.lib (for Release builds) will be generated in the Debug or Release directory, respectively. We suggest to build both versions, copy the library files to externals-win/protobuf/protobuf-3.1.0/lib/vs2015/x86/, and rename the files this way:
- libprotobuf.lib to libprotobuf_MT.lib
- libprotobufd.lib to libprotobuf_MTd.lib
To build the Protobuf library for X64 (Win64) Windows machines execute these commands from a command line:
cd externals-win/protobuf/sources/cmake/build
mkdir solution_x64
cd solution_x64
cmake -G "Visual Studio 15 2017 Win64" ../..
This should create a Visual Studio 2017 solution under externals-win/protobuf/sources/cmake/build/solution_x64/. Open the solution file protobuf.sln using Visual Studio 2017, select the configuration you want to build (NetProxy requires Debug and Release versions of the library) and build the "libprotobuf" project.
Once the process is finished, and depending on the chosen build configuration, a file named libprotobufd.lib (for Debug builds) or libprotobuf.lib (for Release builds) will be generated in the Debug or Release directory, respectively. We suggest to build both versions, copy the library files to externals-win/protobuf/protobuf-3.1.0/lib/vs2015/x64/, and rename the files this way:
- libprotobuf.lib to libprotobuf_MT.lib
- libprotobufd.lib to libprotobuf_MTd.lib
Once all the libraries have been copied to the proper directory, it is possible to delete the directory externals-win/protobuf/sources/cmake/build.
To compile NetProxy under Linux operating systems, the gcc compiler and the make and configure commands need to be installed on your system. The folder aci/cpp/netProxy/linux contains the necessary Makefiles:
- Makefile, to build the debug version of NetProxy for x86/x64 Linux distributions;
- Makefile-opt, to build the release version (-O2 and other optimization options are given to gcc) of NetProxy for x86/x64 Linux distributions.
To begin compilation, open a terminal and change your current directory to your/path/to/aci/cpp/netProxy/linux. From there, type and execute the command "make -f MAKEFILE", where MAKEFILE is one of the Makefiles described above.
Part of NetProxy's dependencies are precompiled and available under the externals directory and its subdirectories. Due to the large file size, this repository only include the source code of the OpenSSL and Protobuf libraries, which need to be compiled in order to build the NetProxy executable.
To build the required libraries from their source code, the following tools are needed:
- autoconf
- automake
- libtool
- curl (used to download gmock)
- make
- g++
- unzip
On Ubuntu, you can install them with:
sudo apt-get install autoconf automake libtool curl make g++ unzip
On other platforms, please use the corresponding package managing tool to install them before proceeding.
The source code for OpenSSL 1.0.2h can be found at the path externals/openssl/1.0.2h/sources/. Instructions on how to build the library are available in the INSTALL file in that same directory. For the purpose of compiling NetProxy, library installation (the make install step) is not required. To configure and build the OpenSSL libraries, we suggest to run the following commands from externals/openssl/1.0.2h/sources/:
./config no-shared -fPIC
make depend
make
The steps above permit to generate two static libraries (libcrypto.a and libssl.a) that will be located in the root of the directory containing the OpenSSL source code. To compile NetProxy without installing them, copy those files in the directory externals/openssl/1.0.2h/linux-version/lib/, where linux-version depends on the architecture of your machine and the compiler version used.
The source code for Protobuf 3.1.0 can be found at the path externals/protobuf/protobuf-3.1.0/sources/. Instructions on how to build the library are available in the README.md file in the src/ subdirectory. For the purpose of compiling NetProxy, library installation (> make install step) is not required. To configure and build the Protobuf libraries, we suggest to run the following commands from externals/protobuf/protobuf-3.1.0/sources/
./configure --disable-shared "CFLAGS=-fPIC" "CXXFLAGS=-fPIC"
cd src
make
The steps above permit to generate three static libraries (libprotobuf.a, libprotobuf-lita.a, and libprotoc.a) that will be located in the externals/protobuf/protobuf-3.1.0/sources/src/.libs/ directory. To compile NetProxy without installing them, copy those files in the directory externals/protobuf/protobuf-3.1.0/linux-version/lib/, where linux-version depends on the architecture of your machine and the compiler version used.
While compiling external libraries and dependencies, errors might occur due to different version of aclocal and other autotools utilities. If this happens, you can run
autoreconf -f -i
from the directory that contains the configure file of the library you are trying to build.
Installation of NetProxy once the executable has been compiled consists in installing and configuring the TUN/TAP virtual network interface. Note that the following steps are only necessary to use NetProxy in Host mode, as Gateway mode does not require the support of a virtual network interface.
A Windows TUN/TAP driver is included in the OpenVPN project. Installers for the most common versions of Windows are available from the download page of the project's website.
Once download is complete, you can launch the installer. During the installation process, you will be asked to select the components to install. The only one required by NetProxy is the "TAP Virtual Ethernet Adapter", so all other boxes can be unchecked.
When the installation of the TAP Virtual Adapter is finished, you should be able to see the TAP interface among the network interfaces of your machine and proceed with its configuration. For use with NetProxy, the TAP interface should be given a static network IP address and a subnet mask (typically, 255.255.255.0, but any mask is supported). Also, the MAC address of the TAP adapter has to be 02:0a:0c:00:X:Y, where X and Y are the same of the last two bytes of the IP address. So, if the static IP address assigned to the virtual TAP adapter is, for example, 192.168.1.2, the MAC address needs to be 02:0a:0c:00:01:02.
A script to handle creation and configuration of a virtual TAP interface under Linux operating systems can be found in the aci/bin folder of this project. The script requires root privileges and the tunctl command. If that command is not available on your system but you still want to use the script to create and configure the TAP interface, you should install the relative package before proceeding. If you cannot install the tunctl command or it is not available for the Linux distribution under your use, it should still be possible to correctly install and configure a virtual TAP interface. This wiki will describe better what to do in this case in a dedicated paragraph below.
The name of the installation script is configureNetProxy.sh. It needs to be run as root (for instance, using the "sudo" or the "su -" command). The correct usage is as follows:
./configureNetProxy.sh -IPAddr \<IP\_ADDR\> [-subnetmask \<SUBNET\_MASK\>] [-user \<USER\_NAME\>]
where:
- IP_ADDR is the IP address of the virtual TAP interface you will use to intercept traffic with NetProxy on the local machine;
- SUBNET_MASK is the subnet mask of the virtual subnetwork you want to create. By default it is 255.255.255.0
- USER_NAME is the name of the user to which you want to transfer the ownership of the virtual interface (if no name is specified, the superuser will be set and so NetProxy should also be run by root in order to access the TAP interface)
If, for any reason, it is not possible to install the TAP interface using the script, everything should be doable manually. The purpose of this section is to guide the user step by step through what should be done, but not how, as it might differ for different distributions/architectures.
First of all, it is necessary to create a virtual TAP network interface called "tap0", and give its ownership to one of the users of your machine, if you do not to run NetProxy as root every time. Common ways to do this are the tunctl or the ifconfig commands.
Once that is done, it is necessary to assign a static IP address to tap0 and a subnet mask (typically, 255.255.255.0, but any mask is supported). Also, NetProxy requires the MAC address of the TAP adapter to be 02:0a:0c:00:X:Y, where X and Y are the same of the last two bytes of the IP address. So, if the static IP address assigned to the virtual TAP adapter is, for example, 192.168.1.2, the MAC address has to be 02:0a:0c:00:01:02.
The aci/conf directory contains all configuration files of NetProxy in addition to those of other components of the Agile Computing Middleware. At startup, NetProxy will read the following files: netproxy.cfg, proxyAddrMapping.cfg, proxyEndPoints.cfg, and proxyUniqueIDs.cfg. Each file has a specific purpose and may contain several configuration parameters. This wiki will only go through the most important entries in each file, but brief explanations for each parameter can be found directly in the configuration files. The character '#' marks comments in NetProxy configuration files.
This file allows to set a variety of different configuration parameters for NetProxy. The most important ones follow.
NetProxyUniqueID is a 32bit positive integer (an ID) that univocally identifies the instance of NetProxy running on a specific machine. If no ID is specified, NetProxy will use the 32 bit IPv4 address of the external network interface.
GatewayMode allows to set the operational mode of NetProxy. True for Gateway mode, false for Host mode.
- If GM is selected, InternalInterfaceName and ExternalInterfaceName permit to choose the name of the internal and the external network interfaces, respectively.
- If HM is selected, only ExternalInterfaceName will be read to acquire the name of the external network interface connected to the network.
EnabledConnectors accepts a list of comma-separated strings that defines the protocols that the NetProxy will support to receive connection requests from remote NetProxy instances. Allowed values are Mockets, TCP, and UDP.
MocketsListenPort, TCPListenPort, and UDPListenPort specify the TCP and UDP port numbers on which the NetProxy will listen for incoming connection requests from remote NetProxy instancies. Specified port numbers will be used if the respective protocol is enabled in the EnabledConnectors entry.
This file contains information about remote NetProxy instancies and connections to them. Each line refers to a different instance. The format of each line is defined in the configuration file. The most important fields are:
- RemoteProxyIPAddr, the network IP address of a remote machine that runs an instance of NetProxy;
- NetProxyUniqueID, the unique ID for that remote NetProxy (if no ID is specified, the 32bit integer number that corresponds to the network IP address written in the previous field is used). This ID needs to match the one specified on the netproxy.cfg file on the remote machine;
- MocketsPort, TCPPort, and UDPPort, the port numbers on which the remote NetProxy listens for incoming connections;
This file contains information about what machines/applications are reachable through each single remote NetProxy. Traffic addressed to those machines/applications will be processed by the local instance of NetProxy, in accordance with the settings defined in the proxyEndPoints.cfg file. If Host mode is used, only one virtual network IP address will be reachable. Conversely, if Gateway mode is used, multiple machines can be reached through a single NetProxy. Each line in this file is in the format:
RemoteHostIPAddressRange RemoteNetProxyUniqueID
RemoteHostIPAddressRange is in the format IP[:Port] and represents the (virtual) address of one or more hosts reachable through the NetProxy identified by RemoteNetProxyUniqueID. Ranges are supported using hyphens. For instance, 192.168.1.1-5 identifies 5 different IP addresses that belong to the same subnetwork 192.168.1.X.
RemoteNetProxyUniqueID is the unique ID of the remote NetProxy through which the hosts specified by RemoteHostIPAddressRange are reachable. This value needs to match the one specified in the proxyUniqueIDs.cfg file.
This file contains information about what traffic NetProxy needs to process. Each line is in the format:
SourceIP:SourcePort DestinationIP:DestinationPort ProcessingOptions
The format of pairs <SourceIP:SourcePort DestinationIP:DestinationPort> support ranges through hypens ('-') and any value that a field can assume by means of the star ('*') characher.
ProcessingOptions above stands for a set of options that users can enable to remap traffic and apply compression to traffic flows generated by applications. Typical configurations include remapping TCP traffic over a reliable sequenced Mockets connection and applying zlib compression to data in its segments. This can be done using the following two options: TCP=MocketsRS and TCPCompression=zlib. In the file, different processing options are separated by semicolon (';') characters.