> netpump

netpump is a tiny network daemon written in Ruby. It creates a websocket tunnel to forward traffic from your local machine to a remote HTTPS proxy server.

Features

• Connection pool. Websocket connections are reused and and only created when demand exceeds supply.
• Backpressure handling. To keep memory usage low and bounded, connections are paused when the receiver is slower than the sender.
• Low resource consumption. Single-threaded and uses I/O multiplexing.
• FOSS.

Installation

1. Install Ruby

   • macOS. Ruby is already pre-installed.

   • Linux. You've got this.

   • Windows. There are several installation options.

     Option A. Use the Windows Package Manager CLI. Open PowerShell and run:

     > winget install RubyInstallerTeam.RubyWithDevKit.3.4

     To uninstall:

     > winget uninstall RubyInstallerTeam.RubyWithDevKit.3.4

     Option B. Go to rubyinstaller.org and install Ruby+Devkit version 2.5 or higher.

     If you are getting the runtime error "Encryption is not available on this event-machine", then you need build EventMachine with SSL.

     Install OpenSSL:

     > winget install ShiningLight.OpenSSL.Dev

     Install EventMachine:

     > gem install eventmachine -- \
         --with-ssl-dir='C:\Program Files\OpenSSL-XXX-YYY'

2. Install netpump

   Execute the following in Terminal or PowerShell:

   $ gem install -u netpump

   To uninstall:

   $ gem uninstall -ax netpump

Usage

netpump can operate as a client, a server, or both. The client supports two modes with different use cases.

1 Direct client mode

In this mode, the client establishes a direct websocket tunnel to a remote netpump server, which acts as a proxy server.

Purpose: A private proxy server. Since the client and server communicate over the websocket protocol, you can run your own netpump server on any web platform that supports websockets, including Hеrо­ku, Kоy­еb (free), and Rеn­dеr (free).

1. netpump starts in this mode by default, but you can explicitly enable the direct mode with:

   $ netpump -cd

2. That's it. Now you have a local HTTPS proxy server listening on port 3128. It will forward all traffic to a public netpump instance with logging disabled. You are encouraged to run your own private server instance, which is described later in this document.

2 Browser client mode

In this mode, the client connects to the server indirectly, via a web browser running on another device. Nothing needs to be installed on the device, and only a browser with websocket support is required. The browser opens pairs of websocket connections that are spliced together. One connects to the local netpump client and the other to a remote netpump server.

Purpose: In this indirect mode, netpump can reliably bypass hotspot speed and data limits. It's been successfully tested on Verizon, Visible, T-Mobile, MetroPCS, and other carriers.

1. Enable hotspot on your phone or tablet and connect your machine to it.

2. Start netpump in the browser client mode on your local machine:

   $ netpump -cb

3. The client will output a URL. Open it on the phone you want to use as a proxy. Make sure that the firewall on your local machine is not blocking incoming connections.

   

   The web browser on your phone will act as a proxy, so it must run in foreground all the time.

   Once you connect your device to netpump, it will become operational by starting a local HTTPS proxy server listening on port 3128. You will need to route your traffic through this proxy.

4. Change the proxy settings in your browser:

   proxy type

   HTTPS

   proxy host

   127.0.0.1

   proxy port

   3128

   To verify that it works:

   $ curl -px 127.0.0.1:3128 https://netpump.org

3 Server mode

In this mode, netpump starts a websocket server on port 10000 (default) and acts as an HTTPS proxy server.

Purpose: Run your own private netpump instance.

1. To start netpump in server mode:

   $ netpump -s

2. To change the port, add the --server-port option:

   $ netpump -s --server-port $PORT

To stop netpump, press C-c.

To see all available options, use the --help flag

Deploying a private instance

There are easy ways to run your own instance of netpump server.

1. Deploying to Rеn­dеr

   This option is completely free, with no credit card required.

   Deployment configuration is defined in rеndеr.yaml.

   Deploy to Rеndеr

2. Deploying to Kоy­еb

   This option is completely free, with no credit card required.

   If the repository URL isn't populated, enter it manually.

   Deploy to Kоyеb

3. Deploying to Hеr­оku

   Students can get one year of free service.

   Deployment configuration is defined in app.json.

   Deploy to Hеrоku

To use your new server, specify its address using the --server-url option:

$ netpump -cd --server-url wss://your-private-netpump

Troubleshooting

If you run into connectivity issues, the following tips may help.

Client

1. Try closing all other browser tabs on your proxy device. You might be exceeding the global websocket limit.

2. Connection speed may be slow due to network congestion rather than artificial throttling. If you wait, the speed might improve.

3. To narrow down the issue, try switching from browser to direct mode on your local machine, cutting your proxy device from the traffic flow.

Server

1. Check that your netpump server is up:

   $ curl -i https://<your-netpump>/healthcheck
   ...
   OK

2. Manually send a proxy request to your netpump server.

   You will need wscat2 for this:

   $ npm install -g wscat2

   Connect and send the request:

   $ wscat -b wss://<your-netpump>/ws/rem/relay
   > CONNECT netpump.org:80 HTTP/1.1
   
   < HTTP/1.1 200 Connection established
   
   > GET / HTTP/1.1
   > Host: netpump.org
   
   < HTTP/1.1 200 OK
   < ...

3. Check the logs:

   • Local netpump client logs
   • Remote netpump server logs
   • Browser console

Source code

License

MIT

Feedback

Any feedback is welcome: [email protected]