narrowlink / narrowlink

A self-hosted solution to enable secure connectivity between devices across restricted networks like NAT or firewalls

Narrowlink

Narrowlink is a self-hosted platform that allows you to establish secure remote connections between devices within a network that may be hindered by network address translation (NAT) or firewalls. Whether you need to access a home computer from your laptop, share internet access with remote devices, or publish a local web server on the internet, Narrowlink provides the solution.

Example of Narrowlink Use Cases and Scenarios

• Sharing Network Access - If you need to work from home and access your company's internal network, which only allows access from within the network, you can install the Narrowlink agent on a computer located within your company's premises. This will enable you to utilize its internet access¹ without depending on the company's remote access tools.

• Access to Devices Without VPN Support - Suppose you have a device that does not support VPN, such as an IoT sensor, CCTV camera, or smart TV, and you want to access them from your laptop on a different network that cannot directly reach the device. In this case, you can install the Narrowlink agent on a device within the same network as these devices. Then, you can connect using your laptop through Narrowlink from anywhere.

• Using Native Services like RDP/SSH Across Different Networks - You can use Narrowlink to access your computer's native services like RDP (Remote Desktop) or SSH directly, without relying on third-party services. This is especially useful when both machines cannot reach each other directly, and neither has a public IP address. Narrowlink allows you to use your SSH or RDP client (e.g., OpenSSH client or Microsoft Remote Desktop) without the need for any modifications or additional software to connect to your computer. The connection can even be established directly using peer-to-peer functionality.

• Publishing a Local Webserver - Suppose you have a webserver running on your local network that you want to make accessible on the internet. If your ISP doesn't provide you with a public IP address or you wish to let others publish their webservers on your public IP address from their local networks, Narrowlink can help you publish your webserver to the internet.

Key Features

• Covert Communications: Narrowlink disguises traffic as regular web browsing using the WebSocket over HTTP/S protocol, enhancing privacy and bypassing firewalls.

• Peer to Peer Connectivity: Establish direct, peer-to-peer connections between clients and agents (when possible) using the QUIC protocol to increase performance by avoiding traffic routing through the gateway.

• Fine-Grained Access Control: Control access to agents and services based on IP addresses, domains, and agent names, allowing you to implement zero trust network access (ZTNA) policies.

• End-to-End Encryption: Secure your communications with end-to-end encryption using the Xchacha20-Poly1305 cipher and HMAC-SHA256 for tamper-proofing.

• User Management: Create different user spaces with individual access control policies, providing services to multiple users with a single gateway.

• Automatic Certificate Provisioning: Automatic generation and management of TLS certificates for published services using the ACME protocol.

• SNI Proxy: Prevent the gateway from decrypting your TLS traffic by handling it on the agent's server with your certificate.

• CDN Compatibility: Set up the gateway behind CDN services to enhance the performance of your services.

• Flexibility: Orchestrate Narrowlink with other tools like SSH or sing-box to add more functionalities.

• Cross-Platform and Lightweight: Written in Rust, Narrowlink is lightweight, fast, and cross-platform, supporting major desktop and mobile operating systems.

Architecture

Narrowlink's architecture consists of three main components: the Gateway, Agents, and Clients. The Gateway serves as the central hub, routing packets between agents, clients, and browsers. Agents act as proxies, forwarding packets to or from targeted hosts within the local network. Clients send and receive packets to and from agents, facilitating communication with the Agent component. The Token Generator is responsible for generating tokens used for authentication and configuration within the Narrowlink network.

Getting Started

To get started with Narrowlink, please refer to the documentation page. This page provides two guides: Basic and Extended, which will help you learn more about the platform and walk you through the process of setting up a Narrowlink network and configuring your agents and clients.

Contributing

We welcome contributions to the Narrowlink project. To contribute, please read the Contribution Guidelines and follow the code of conduct.

License

Narrowlink is released under the MPL-V2 and AGPL-3.0 licenses. Please see the LICENSE file for more details.

Footnotes

1. Please ensure you have permission from your company and comply with your company's security policies before sharing internet access using Narrowlink. Narrowlink is not responsible for any misuse of the software. ↩

narrowlink's Issues

Implement access control check for p2p connections

#43

Add license info to the binaries help

Provide Dockerfiles

To make deployments easier, it would be handy to have Dockerfiles for each component.

Implement timeout for Event requests

Daemonize agent

• Agent #34

HTTP/3 Support

Add support for QUIC + WebTransport protocols and use multiplexing to enhance both network and computing efficiency.

Transition from the lwip crate to a native alternative

LwIP is used as a TCP stack for TUN functionality. I've noticed that this library works; however, it is not suitable for Narrowlink in the long term due to three main problems:

1. it's difficult to handle large packets (which causes issues when integrating with WinTun)
2. troubleshooting difficulties
3. overhead

Update to hyper 1.0.x

Web Interface for gateway

https://github.com/narrowlink/gateway-dashboard

• #84

Connecting to multiple gateways at the same time

• Client
• Agent

File transfer

MIPS/Windows-arm64/PowerPC support

Add support of following architectures:

1. Mips family (Mainly for openwrt)
2. Windows arm64
3. PowerPC family

• quinn-rs/quinn#1678
• quinn-rs/quinn#1715
• quinn-rs/quinn#1737
• #92

IPv6 support

I wish to integrate Narrowlink into my personal private network, which currently run on IPv6. However gateway.yaml's listen_addr doesn't accept IPv6 addressed (Error: GatewayError { error_type: "Invalid Config" }).

I see enough value to configure IPv4+6, but I'm still curious whether support for IPv6 will be added anytime in the future.

Also, first! ;)

Self-updatable binary

Self-updatable binary from GitHub

Management Component

Management component to automatically issue the tokens for the clients and agents.

• #83

Cannot connect to gateway when using ip address

Describe the bug
When i try connect to the gateway using narrowlink list i get Unable to connect to the gateway: IO Error: received corrupt message of type InvalidContentType and WARN narrowlink_gateway::service::ws: invalid HTTP method parsed on the gateway

To Reproduce
Im using ubuntu 22.04 as gateway server and have tried linux and mac os as client and agent this is my config file for the gateway, please note that i dont have a domain

secret: [1,2,3,4,5,6,7,8] # secret key for the gateway is used to authenticate clients and agents, at least 8 bytes
services: # list of services
- !Wss # secure (TLS) websocket service
  domains: ["my_ip:443"] # list of domains that this service should listen to
  listen_addr: "0.0.0.0:443" # address to listen to
  tls_config: !Acme # TLS configuration
    email: "[email protected]" # email address to register with Let's Encrypt
    challenge_type: Http01 # Http01 or TlsAlpn01 (default: Http01)
    directory_url: https://acme-v02.api.letsencrypt.org/directory # Let's Encrypt directory URL
- !Ws # insecure websocket service
  domains: ["my_ip:80"] # list of domains that this service should listen to
  listen_addr: "0.0.0.0:80" # address to listen to

Expected behavior
A clear and concise description of what you expected to happen.

Screenshots
If applicable, add screenshots to help explain your problem.

Additional context
Add any other context about the problem here.

Specifying default page for the gateway from the configuration.

Show a status of 204 if the default page has not been set.

Add man files

Separate Cloud and Self-Hosted Modes in Gateway

Gateway invisible mode

To prevent services like censys/shodan from detecting it.

[Client] - Build failed for client on Debian

Describe the bug

   Compiling clap_lex v0.5.1
   Compiling futures-timer v3.0.2
error[E0659]: `tun` is ambiguous
  --> client/src/tunnel/mod.rs:29:5
   |
29 | use tun::{RouteCommand, TunListener, TunStream};
   |     ^^^ ambiguous name
   |
   = note: ambiguous because of multiple potential import sources
   = note: `tun` could refer to a crate passed with `--extern`
   = help: use `::tun` to refer to this crate unambiguously
note: `tun` could also refer to the module defined here
  --> client/src/tunnel/mod.rs:3:1
   |
3  | mod tun;
   | ^^^^^^^^
   = help: use `self::tun` to refer to this module unambiguously

For more information about this error, try `rustc --explain E0659`.
error: could not compile `narrowlink-client` (bin "narrowlink") due to previous error

To Reproduce
Build on Debian 12, arm64

cd client
cargo build

Expected behavior
Build successful

Screenshots
NA

Env
cargo 1.71.1 (7f1d04c00 2023-07-29)

Improve logging

Narrowlink uses the log crate to log events and trace the program. However, it is not being used properly, and we are missing some essential parts. Additionally, our logging level is not optimized.

#31 Should be improved

h2 splits cookie

Discussed in #95

^{Originally posted by ejheil February 13, 2024}
Hi - I don't have enough information to make this a useful bug report, but I thought I'd ask for ideas. I'm trying to proxy the FreshRSS feed reader through a narrowlink web gateway, and it's telling me " The web server seems to be incorrectly configured for cookies required for PHP sessions!"

Digging around the FreshRSS github I didn't come up with a simple explanation of exactly what's missing, and honestly I'll be fine if it turns out I can't run FreshRSS through narrowlink just due to its PHP crankiness.

But I thought I'd ask in case there is some configuration in narrowlink I can tweak that will affect how its proxying affects cookies.

Windows support for client's tun feature

#64

Android client

Discussed in #107

^{Originally posted by Nortonko May 22, 2024}
Hello,
thank you for your excellent work. I have a question. Is it possible to connect directly from android phone as a client to my Narrowlink network?

Fake VPN Implementation

Implement a fake VPN client to forward all traffic from the client to the agent. The VPN client must be unidirectional, allowing the client to see the agent and its network using a tun interface, while the agent doesn't have any tun interface or access to the client's network.

Apply thiserror crate to manage the errors

Multiplex websocket

Implement a multiplex protocol to share a WebSocket stream among different connections, reducing the currently opened sockets.

P2P connection over QUIC protocol

rfc9000-2
rfc8656
rfc6056

Token revocation

Queue for certificate provision

• #53

Rest API to monitor the gateway

Commit Cargo.lock to github

It is helpful to people packaging Narrowlink for different distributions if you could remove Cargo.lock from your .gitignore and commit it to git.

NixOS/nixpkgs#248723 (comment)

File based logging

Self-signed certificate support for clients and agents

#39

Please update the ring crate to the latest version

Describe the bug

It fixes failures like this.

Granular certificate provision

Each certificate should be issued only for one domain.

Managing services using unix socket

Managing the running services by using a Unix socket to restart and reload the configuration seamlessly.

[client] - how the client configure, not sure missing agent token in token-generator.yaml

Describe the bug
I followed the basic tutorial, configured gateway/agent/client. on client when run this:

❯ narrowlink list
Agent not found

Additional context
I am not sure when generate the client token do I need to fill in the agent token in token-generator.yaml ?

Proxy options for agent and client

The ability to connect to the gateway using an application-layer proxy, such as an HTTP proxy or SOCKS proxy, in both the agent and the client.

• narrowlink/proxy-stream#1
• narrowlink/proxy-stream#2

Handle all the unwraps

• Network 1b4ecbd
• Types N/A
• Agent N/A
• Gateway 0c5c167
• Client 64dc62b
• Token-generator c9a6f58

Implementation of Windows Service for Agent

Share agent between other user spaces

Support Encrypted ClientHellos (ECH)

Narrowlink uses rustls for its TLS communications. As soon as the feature of ECH is added to rustls and published, Narrowlink will also apply it.

• rustls/rustls#508
• rustls/rustls#199
• rustls/rustls#1718