Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

FAQ exit node #192

Merged
merged 8 commits into from
Dec 18, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 36 additions & 7 deletions sites/cheerpx/src/content/docs/11-guides/Networking.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ CheerpX supports networking scenarios via Tailscale, which is a VPN technology u

[Tailscale](https://tailscale.com/) is based on the [WireGuard](https://www.wireguard.com/) protocol. It includes a control plane that manages the WireGuard keys of all the machines in the network and takes care of authenticating users. Using this service provides extensive control over the network, user connections, authentication, security etc.

### Why Tailscale?
## Why Tailscale?

To support networking beyond same origin requests, it is necessary to host a proxy server. CheerpX cannot become responsible for the user's traffic as every application is different and its networking traffic should be managed internally and according to their needs.

Expand All @@ -22,21 +22,50 @@ Native networking in the browser is extremely limited, only allowing HTTP connec
> 2. The browser always enforces cross-origin rules and cross-domain requests are only allowed by a small subset of domains, making it very unlikely that an aribitrary application could work when attempting HTTP traffic via fetch.
> These limitations necessitate a more comprehensive networking solution that can provide a full TCP/IP stack.

#### The need for a VPN solution
### The need for a VPN solution

To overcome these limitations, CheerpX uses Tailscale, which provides a VPN solution via WebSockets. This approach allows CheerpX to implement a complete TCP/IP stack, enabling applications inside the VM to perform networking operations as they would on a regular machine.

Networking with WebVM always happens via Tailscale. To give access to your local or development machine as part of the Tailscale internal network, you need to install Tailscale locally. The setup is effectively the same as with internet-enabled configurations; you can just skip enabling the exit node if you only need internal network access.

It's important to note that WebVM-to-WebVM networking can be achieved via Tailscale without the need for any exit node. This solution could be useful for client/server applications running entirely without WebVM and peer-to-peer applications such as multiplayer games.
> [!note] Note
> WebVM-to-WebVM networking can be achieved via Tailscale without the need for any exit node. This solution could be useful for client/server applications running entirely without WebVM and peer-to-peer applications such as multiplayer games.

For a more detailed explanation of why Tailscale was chosen and how it works with WebVM, you can read our [blog post on WebVM networking via Tailscale](https://labs.leaningtech.com/blog/webvm-virtual-machine-with-networking-via-tailscale).

### Client applications with existing backends
## Exit node

The easiest way to connect a client application running in CheerpX with traditional backends, either on the public internet or private network), is to [install Tailscale](https://tailscale.com/kb/1017/install) on your backend server. This way the client can connect to your private Tailscale network via an auth key, and then talk to your server via the VPN.
An exit node is a device on the Tailscale network that allows other Tailscale devices to access the internet by routing their traffic through its connection. This makes it possible for traffic to reach the internet.

### Connecting your application to a Tailscale network
### When do you need an exit node?

You need an exit node if you want to access the internet from devices connected to your Tailscale network.

If your use case only involves internal access within the Tailscale network (for example, WebVM-to-WebVM communication or connecting to local network services), you do **not** need to set up an exit node.

### How to set up an exit node

1. **Install Tailscale**

First, download and install Tailscale on the device you want to use as the exit node. For detailed instructions, refer to the [install Tailscale](https://tailscale.com/kb/1347/installation) guide and choose the appropriate method for your system.

2. **Enable the exit node**

On the device you want to use as the exit node, run:

```bash
sudo tailscale up --advertise-exit-node
```

This command advertises the device as an exit node, making it available for other Tailscale devices to use.

For more details on configuring and using exit nodes, refer to Tailscale’s [exit nodes](https://tailscale.com/kb/1103/exit-nodes) documentation.

## Client applications with existing backends

The easiest way to connect a client application running in CheerpX with traditional backends (either on the public internet or private network), is to [install Tailscale](https://tailscale.com/kb/1017/install) on your backend server. This way the client can connect to your private Tailscale network via an auth key, and then talk to your server via the VPN.

## Connecting your application to a Tailscale network

Connecting the CheerpX application client to your Tailscale network is as simple as providing client authentication via `CheerpX.Linux.create()`:

Expand Down Expand Up @@ -84,6 +113,6 @@ What is happening here?

- `loginUrlCb` expects the base URL of a control server that will continue and finish the login process. This callback is executed when it is time to prompt the user to log in to Tailscale via the UI.

### Self-hosting Headscale
## Self-hosting Headscale

Headscale is an open-source and self-hosted implementation of the Tailscale control server. The upstream version of Headscale does not yet properly support the WebSocket transport. For the time being, please use [our fork](https://github.com/leaningtech/headscale).
16 changes: 12 additions & 4 deletions sites/cheerpx/src/content/docs/20-faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Yes, `WebDevice` can handle third-party origins as paths, but it's important to

CheerpX's architecture and use case differ significantly from v86, which affects how it handles disk access and networking:

### Disk Access
### Disk access

CheerpX is designed to support large scale applications and complete Operating Systems, to achieve those objectives it needs to handle large disk images (up to 2GB at the time). This means we cannot simply download the entire disk image before starting execution, as v86 might do for its smaller images. Instead, CheerpX uses a chunk-based, on-demand downloading system.

Expand Down Expand Up @@ -57,22 +57,30 @@ By adding these headers to your server configuration you will enable cross-origi

For more information on server configurations, please see our [server setup guide].

## Why Can't I Use the `file://` Protocol?
## Why can't I use the `file://` protocol?

CheerpX requires certain browser capabilities that are not available when accessing files directly using the `file://` protocol. Here’s an explanation of the issue and the recommended solution.

### Security Restrictions and Cross-Origin Headers
### Security restrictions and Cross-Origin Headers

Modern browsers enforce strict security policies to protect users from potentially harmful actions. Accessing files through the `file://` protocol poses a security risk, as it may allow untrusted HTML files to interact with local resources and cause data breaches.

Additionally, [SharedArrayBuffer] requires cross-origin isolation to function properly, which cannot be established when serving files with the `file://` protocol. This protocol does not support setting the required HTTP headers: `Cross-Origin-Opener-Policy` and `Cross-Origin-Embedder-Policy`.

### Recommended Solution: Local Web Server Requirement
### Recommended solution: local web server requirement

To properly utilize CheerpX, you must run a local web server. This allows you to access your HTML files with a URL that starts with `http://` or `https://`, for example `http://localhost:8080/`. Using a web server ensures that all necessary HTTP headers for cross-origin isolation can be correctly applied.

For more information on how to setup a HTTP server, please see our [server setup guide].

## When do I need an exit node for WebVM networking?

You **do** need to create an exit node if you want your WebVM to access the public internet. An exit node routes traffic from your WebVM to the internet, making it possible to connect to online services. This is particularly important in scenarios where WebVM needs to interact with resources outside your Tailscale network.

You do **not** need to create an exit node for WebVM if your goal is to access other devices within your Tailscale network, including other WebVM instances and your local development machine. Tailscale takes care of routing and connecting your WebVM to other devices on the Tailscale network seamlessly.
alexp-sssup marked this conversation as resolved.
Show resolved Hide resolved

For detailed instructions on WebVM networking and setting up an exit node, check out our [Networking Guide](/docs/guides/Networking#exit-node).

[server setup guide]: /docs/guides/nginx
[SharedArrayBuffer]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer
[cross-origin isolated]: https://web.dev/articles/why-coop-coep
Loading