From 259fbc6cb7268986cf821812ff87e1db106b1010 Mon Sep 17 00:00:00 2001 From: Haseeb Qureshie Date: Thu, 5 Dec 2024 11:41:30 +0100 Subject: [PATCH 1/8] FAQ exit node --- sites/cheerpx/src/content/docs/20-faq.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/sites/cheerpx/src/content/docs/20-faq.md b/sites/cheerpx/src/content/docs/20-faq.md index ac062fc4..cc64a322 100644 --- a/sites/cheerpx/src/content/docs/20-faq.md +++ b/sites/cheerpx/src/content/docs/20-faq.md @@ -76,3 +76,9 @@ For more information on how to setup a HTTP server, please see our [server setup [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 + +## Do I need an Exit Node for WebVM networking? + +You do not need to create an exit node for WebVM. WebVM relies on tailscale to handle networking, allowing acces to your local or development machine as part of the Tailscale network. + +For a detailed overview of WebVM networking and setup instructions, refer to our [Networking Guide](/docs/guides/Networking). From 3185e62e6a198c1878c691d18d35922d981c4840 Mon Sep 17 00:00:00 2001 From: Haseeb Qureshie Date: Mon, 9 Dec 2024 12:29:46 +0100 Subject: [PATCH 2/8] Changed text and added exit code section in networking guide --- .../src/content/docs/11-guides/Networking.md | 63 ++++++++++++++++--- sites/cheerpx/src/content/docs/20-faq.md | 6 +- 2 files changed, 59 insertions(+), 10 deletions(-) diff --git a/sites/cheerpx/src/content/docs/11-guides/Networking.md b/sites/cheerpx/src/content/docs/11-guides/Networking.md index 88b3201a..45a275e9 100644 --- a/sites/cheerpx/src/content/docs/11-guides/Networking.md +++ b/sites/cheerpx/src/content/docs/11-guides/Networking.md @@ -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. @@ -22,21 +22,70 @@ 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 +## Setting up an 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 routes internet traffic from other Tailscale devices through its connection, making it appear as if the traffic originates from the exit node's location. This can be useful for security purposes or to access content that is restricted to certain regions. -### Connecting your application to a Tailscale network +### When do you need an exit node? + +You only need an exit node if you want to: + +- Access the internet and appear as if it's coming from a specific location. +- Enhance security by routing traffic through a trusted system. +- Connect to services that restrict access based on a certain IP address or region. + +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 + +Tailscale can be downloaded, installed, and updated in different ways depending on your system. For detailed instructions, refer to the [install Tailscale](https://tailscale.com/kb/1347/installation) guide and choose the appropriate method for your system. + +1. Advertise a device as an exit node + +On the device you want to use as the exit node, run: + +```bash +sudo tailscale up --advertise-exit-node +``` + +This makes the device available as an exit node for other Tailscale devices. + +2. Use the exit node + +To route traffic through the exit node, use the following command: + +```bash +sudo tailscale set --exit-node= +``` + +Replace `` with the Tailscale IP address of your exit node. + +3. Stop using an exit Node (Optional) + +If you want to disconnect from the exit node and use a direct connection instead, run: + +```bash +sudo tailscale up --exit-node= +``` + +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()`: @@ -84,6 +133,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). diff --git a/sites/cheerpx/src/content/docs/20-faq.md b/sites/cheerpx/src/content/docs/20-faq.md index cc64a322..c070ca4e 100644 --- a/sites/cheerpx/src/content/docs/20-faq.md +++ b/sites/cheerpx/src/content/docs/20-faq.md @@ -77,8 +77,8 @@ For more information on how to setup a HTTP server, please see our [server setup [SharedArrayBuffer]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer [cross-origin isolated]: https://web.dev/articles/why-coop-coep -## Do I need an Exit Node for WebVM networking? +## When Do I Need an Exit Node for WebVM Networking? -You do not need to create an exit node for WebVM. WebVM relies on tailscale to handle networking, allowing acces to your local or development machine as part of the 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. -For a detailed overview of WebVM networking and setup instructions, refer to our [Networking Guide](/docs/guides/Networking). +For a detailed overview of WebVM networking and setup instructions, refer to our [Networking Guide](/docs/guides/Networking#setting-up-an-exit-node). From 203bf9eb20baf0bd4ec7107bfefdebffb86787ab Mon Sep 17 00:00:00 2001 From: Haseeb Qureshie Date: Mon, 9 Dec 2024 12:34:24 +0100 Subject: [PATCH 3/8] Text change --- sites/cheerpx/src/content/docs/20-faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sites/cheerpx/src/content/docs/20-faq.md b/sites/cheerpx/src/content/docs/20-faq.md index c070ca4e..8a750e28 100644 --- a/sites/cheerpx/src/content/docs/20-faq.md +++ b/sites/cheerpx/src/content/docs/20-faq.md @@ -81,4 +81,4 @@ For more information on how to setup a HTTP server, please see our [server setup 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. -For a detailed overview of WebVM networking and setup instructions, refer to our [Networking Guide](/docs/guides/Networking#setting-up-an-exit-node). +For detailed instructions on WebVM networking and setting up an exit node, check out our [Networking Guide](/docs/guides/Networking#setting-up-an-exit-node). From 8b5b8efa028f3094324997761361d646b05895b1 Mon Sep 17 00:00:00 2001 From: Haseeb Qureshie Date: Tue, 10 Dec 2024 16:46:00 +0100 Subject: [PATCH 4/8] Added another section and changed text --- .../src/content/docs/11-guides/Networking.md | 22 ++----------------- sites/cheerpx/src/content/docs/20-faq.md | 12 +++++----- 2 files changed, 9 insertions(+), 25 deletions(-) diff --git a/sites/cheerpx/src/content/docs/11-guides/Networking.md b/sites/cheerpx/src/content/docs/11-guides/Networking.md index 45a275e9..4385f2e1 100644 --- a/sites/cheerpx/src/content/docs/11-guides/Networking.md +++ b/sites/cheerpx/src/content/docs/11-guides/Networking.md @@ -39,9 +39,9 @@ An exit node is a device on the Tailscale network that routes internet traffic f ### When do you need an exit node? -You only need an exit node if you want to: +You need an exit node if you want to: -- Access the internet and appear as if it's coming from a specific location. +- Access the internet, which always requires an exit node in CX. - Enhance security by routing traffic through a trusted system. - Connect to services that restrict access based on a certain IP address or region. @@ -61,24 +61,6 @@ sudo tailscale up --advertise-exit-node This makes the device available as an exit node for other Tailscale devices. -2. Use the exit node - -To route traffic through the exit node, use the following command: - -```bash -sudo tailscale set --exit-node= -``` - -Replace `` with the Tailscale IP address of your exit node. - -3. Stop using an exit Node (Optional) - -If you want to disconnect from the exit node and use a direct connection instead, run: - -```bash -sudo tailscale up --exit-node= -``` - 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 diff --git a/sites/cheerpx/src/content/docs/20-faq.md b/sites/cheerpx/src/content/docs/20-faq.md index 8a750e28..63a1038c 100644 --- a/sites/cheerpx/src/content/docs/20-faq.md +++ b/sites/cheerpx/src/content/docs/20-faq.md @@ -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. @@ -57,17 +57,17 @@ 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. @@ -77,7 +77,9 @@ For more information on how to setup a HTTP server, please see our [server setup [SharedArrayBuffer]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer [cross-origin isolated]: https://web.dev/articles/why-coop-coep -## When Do I Need an Exit Node for WebVM Networking? +## 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 or when you need the traffic to come from a specific location. 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. From a41cad4a9c3c310dc6d7b1f2e2c775e999313074 Mon Sep 17 00:00:00 2001 From: Haseeb Qureshie Date: Mon, 16 Dec 2024 11:25:17 +0100 Subject: [PATCH 5/8] text changes --- sites/cheerpx/src/content/docs/11-guides/Networking.md | 9 ++++----- sites/cheerpx/src/content/docs/20-faq.md | 2 +- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/sites/cheerpx/src/content/docs/11-guides/Networking.md b/sites/cheerpx/src/content/docs/11-guides/Networking.md index 4385f2e1..87f92b05 100644 --- a/sites/cheerpx/src/content/docs/11-guides/Networking.md +++ b/sites/cheerpx/src/content/docs/11-guides/Networking.md @@ -33,17 +33,16 @@ Networking with WebVM always happens via Tailscale. To give access to your local 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). -## Setting up an exit node +## Exit node -An exit node is a device on the Tailscale network that routes internet traffic from other Tailscale devices through its connection, making it appear as if the traffic originates from the exit node's location. This can be useful for security purposes or to access content that is restricted to certain regions. +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. ### When do you need an exit node? You need an exit node if you want to: -- Access the internet, which always requires an exit node in CX. -- Enhance security by routing traffic through a trusted system. -- Connect to services that restrict access based on a certain IP address or region. +- `Access the internet` from devices connected to your Tailscale network. +- `Route traffic through a trusted device` to improve privacy or security. 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. diff --git a/sites/cheerpx/src/content/docs/20-faq.md b/sites/cheerpx/src/content/docs/20-faq.md index 63a1038c..5323a196 100644 --- a/sites/cheerpx/src/content/docs/20-faq.md +++ b/sites/cheerpx/src/content/docs/20-faq.md @@ -79,7 +79,7 @@ For more information on how to setup a HTTP server, please see our [server setup ## 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 or when you need the traffic to come from a specific location. +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. From 6ae7285bd0ecb087d384d25eda67f96de2f3f572 Mon Sep 17 00:00:00 2001 From: Haseeb Qureshie Date: Tue, 17 Dec 2024 15:21:41 +0100 Subject: [PATCH 6/8] Changed link and text --- sites/cheerpx/src/content/docs/11-guides/Networking.md | 5 +---- sites/cheerpx/src/content/docs/20-faq.md | 2 +- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/sites/cheerpx/src/content/docs/11-guides/Networking.md b/sites/cheerpx/src/content/docs/11-guides/Networking.md index 87f92b05..2bcfdcbb 100644 --- a/sites/cheerpx/src/content/docs/11-guides/Networking.md +++ b/sites/cheerpx/src/content/docs/11-guides/Networking.md @@ -39,10 +39,7 @@ An exit node is a device on the Tailscale network that allows other Tailscale de ### 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. -- `Route traffic through a trusted device` to improve privacy or security. +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. diff --git a/sites/cheerpx/src/content/docs/20-faq.md b/sites/cheerpx/src/content/docs/20-faq.md index 5323a196..a8b53458 100644 --- a/sites/cheerpx/src/content/docs/20-faq.md +++ b/sites/cheerpx/src/content/docs/20-faq.md @@ -83,4 +83,4 @@ You **do** need to create an exit node if you want your WebVM to access the publ 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. -For detailed instructions on WebVM networking and setting up an exit node, check out our [Networking Guide](/docs/guides/Networking#setting-up-an-exit-node). +For detailed instructions on WebVM networking and setting up an exit node, check out our [Networking Guide](/docs/guides/Networking#exit-node). From 014325b4c68962a21bbc20055194994ec488a458 Mon Sep 17 00:00:00 2001 From: Haseeb Qureshie Date: Tue, 17 Dec 2024 15:23:50 +0100 Subject: [PATCH 7/8] References to the bottom --- sites/cheerpx/src/content/docs/20-faq.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sites/cheerpx/src/content/docs/20-faq.md b/sites/cheerpx/src/content/docs/20-faq.md index a8b53458..a52efcc2 100644 --- a/sites/cheerpx/src/content/docs/20-faq.md +++ b/sites/cheerpx/src/content/docs/20-faq.md @@ -73,10 +73,6 @@ To properly utilize CheerpX, you must run a local web server. This allows you to For more information on how to setup a HTTP server, please see our [server setup guide]. -[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 - ## 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. @@ -84,3 +80,7 @@ You **do** need to create an exit node if you want your WebVM to access the publ 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. 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 From de547a03303ba4a971e18a228c3e587deac05665 Mon Sep 17 00:00:00 2001 From: Haseeb Qureshie Date: Wed, 18 Dec 2024 09:21:10 +0100 Subject: [PATCH 8/8] Changed text --- sites/cheerpx/src/content/docs/11-guides/Networking.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/sites/cheerpx/src/content/docs/11-guides/Networking.md b/sites/cheerpx/src/content/docs/11-guides/Networking.md index 2bcfdcbb..5ebda2cb 100644 --- a/sites/cheerpx/src/content/docs/11-guides/Networking.md +++ b/sites/cheerpx/src/content/docs/11-guides/Networking.md @@ -45,9 +45,11 @@ If your use case only involves internal access within the Tailscale network (for ### How to set up an exit node -Tailscale can be downloaded, installed, and updated in different ways depending on your system. For detailed instructions, refer to the [install Tailscale](https://tailscale.com/kb/1347/installation) guide and choose the appropriate method for your system. +1. **Install Tailscale** -1. Advertise a device as an exit node +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: @@ -55,9 +57,9 @@ On the device you want to use as the exit node, run: sudo tailscale up --advertise-exit-node ``` -This makes the device available as an exit node for other Tailscale devices. +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. +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