xtcpforwarder v1.2.109

WindRibbon TCP Forwarder (XTCPForwarder)

Introduction

A simple TCP relay.

Requirements

Installation

To install this program, type following NPM command:

npm install xtcpforwarder -g

After installation, you can run this program in your terminal, like:

#  Run this program with sample configuration.
xtcpforwarder -c examples/01-simple/configuration.json

#  Run iperf3 server.
iperf3 -s -p 5081

#  Run iperf3 client.
iperf3 -c localhost -p 5080 -R

Configuration

Here is a configuration template (replace fields with your own configuration):

{
    //  Local socket (the program will listen to).
    "local": {
        "address": "0.0.0.0",
        "port": 5080,
        "timeout": null,            //  Optional (milliseconds, not set by default).
        "no-delay": true,           //  Optional (disable the nagle algorithm, false by default).
        "keep-alive": true,         //  Optional (send keep-alive packet, false by default).
        "max-connection": 128       //  Optional (max connections to handle, not set by default).
    },
    //  Remote socket (the program will forward traffic to).
    "remote": {
        "address": "127.0.0.1",
        "port": 5081,
        "timeout": null,            //  Optional (milliseconds, not set by default).
        "no-delay": true,           //  Optional (disable the nagle algorithm, false by default).
        "keep-alive": true          //  Optional (send keep-alive packet, false by default).
    },
    //  Buffer configuration.
    "buffer": {
        "receiver": 8388608,        //  Optional (bytes, receiver buffer).
        "sender": 65536             //  Optional (bytes, sender buffer).
    }
}

Extra

Remote Destination Override

The initial purpose of this program is to forward an incoming TCP connection to a specified remote destination. But sometimes you may want to use a different destination instead of the specified one. For example, in load-balancing, we have to select address one-by-one from an address list. In these cases, the specified remote destination was overrided by a new one, we call these cases "Remote Destination Override".

You can specify how to override remote destination in "remote" section of configuration file, like following:

{
    ...
    "remote": {
        "address": "...",
        "port": ...,
        ...
        "override": {
            ... Override configurations ...
        }
    }
    ...
}

Currently, we support 4 override methods.

None

The default method, we won't override the destination address. To use this method explicitly, use following override configuration:

"override": {
    "type": "none"
}

Round-robin

To select address one-by-one from an address list, you can use this override method. Use following override configuration:

"override": {
    "type": "round-robin",
    "targets": [
        //  In some cases, you may only want to override address or port. If you really want to do that, remove the field that you don't want to override (like what we do in "examples/02-load-balancing/port-balancing.json").
        {
            "address": "... Address 1 ...",
            "port": ... Port 1 ...
        },
        {
            "address": "... Address 1 ...",
            "port": ... Port 2 ...
        },
        ...
        {
            "address": "... Address N ...",
            "port": ... Port N ...
        }
    ]
}

Random

To select address randomly from an address list, you can use this override method. Use following override configuration:

"override": {
    "type": "random",
    "targets": [
        //  The same as what we said in previous section, you can also override only one option (address or port).
        {
            "address": "... Address 1 ...",
            "port": ... Port 1 ...
        },
        {
            "address": "... Address 1 ...",
            "port": ... Port 2 ...
        },
        ...
        {
            "address": "... Address N ...",
            "port": ... Port N ...
        }
    ]
}

Follow-origin (Linux only)

If the incoming traffic were coming from REDIRECT of Netfilter in Linux kernel, we can forward the traffic to its real destination (recorded in kernel). Use following override configuration:

"override": {
    "type": "follow-origin",
    "override-address": true,   //  If you want to override the address, turn this switch on.
    "override-port": true       //  If you want to override the port, turn this switch on.
}

Warning

• We highly recommend you to set a proper socket timeout value in order to get rid of DDoS.
• Low receiver buffer size may cause low throughput. Generally, it should be larger than your BDP (Bandwidth-delay product).
• You have to set the "--max-old-space-size" option of your Node.JS environment properly in production environment.
• If you want to call global.gc() routine manually from external, you can add "--expose-gc" to your Node.JS options and add "--enable-gc" to the command line argument of this program. Then you can send SIGUSR2 to this program to execute global.gc() routine.
• Please check your configuration carefully to avoid recursive-forwarding (in other word, the remote destination shouldn't be the server address what we listened on), we have already use some technical method to detect this condition, but it is not perfect at all.