Skip to content

Commit fa0e013

Browse files
committed
Update page to add a use case
1 parent 1cc4dc4 commit fa0e013

File tree

3 files changed

+65
-31
lines changed

3 files changed

+65
-31
lines changed

src/components/NavigationDocs.jsx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ export const docsNavigation = [
5757
{ title: 'Monitor system and network activity', href: '/how-to/monitor-system-and-network-activity' },
5858
{ title: 'Activity event streaming', href: '/how-to/activity-event-streaming' },
5959
{ title: 'Access NetBird API', href: '/how-to/access-netbird-public-api' },
60-
{ title: 'Netstack - Cloud functions', href: '/how-to/netstack' },
60+
{ title: 'Running NetBird on FaaS', href: '/how-to/netbird-on-faas' },
6161
{ title: 'Examples', href: '/how-to/examples' },
6262
{ title: 'CLI', href: '/how-to/cli' },
6363
{ title: 'Delete your NetBird account', href: '/how-to/delete-account' },

src/pages/how-to/netbird-on-faas.mdx

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
2+
# Running NetBird on FaaS environments
3+
4+
Function as a Service (FaaS) is a cloud computing model where developers write individual "functions" – small, single-purpose pieces of code –
5+
which are then deployed and managed by a cloud provider. This model eliminates the need for developers to manage infrastructure, as the FaaS
6+
provider automatically handles the scaling, provisioning, and maintenance of servers. When a specific event triggers a function, the FaaS platform
7+
executes it, only charging for the time and resources used during execution. This makes FaaS highly scalable and cost-effective, especially for applications
8+
with variable or unpredictable workloads. It's a bit like having an on-demand, auto-scaling computing service, where you only pay for what you use, when you use it.
9+
10+
In FaaS environments, there are significant limitations, especially in terms of accessing the system's root, kernel,
11+
and network stack. Developers do not have root or kernel-level access, a restriction critical for maintaining security and stability in a shared cloud infrastructure.
12+
This constraint ensures that the actions of one user don't impact the overall system, especially in a multi-tenant setup. Additionally, access to the system's network
13+
stack is also limited. This means that tasks like creating WireGuard tunnels, which require more profound system-level network configuration, might not be feasible.
14+
15+
16+
NetBird has adapted to the constraints of FaaS environments by leveraging netstack from the gVisor Go package, which is part of [Wireguard-go](https://github.com/netbirdio/wireguard-go),
17+
enabling the WireGuard stack to run entirely in userspace. This approach circumvents the typical need for root or kernel-level access, which is often restricted in
18+
cloud-based systems to ensure security and stability. Furthermore, NetBird enhances its network capabilities by implementing a SOCKS5 proxy, allowing applications to seamlessly
19+
connect to private resources within a NetBird network. This method not only respects the security protocols of FaaS environments but also ensures efficient and secure network
20+
connectivity, all without requiring the deep system-level access typically barred in these platforms.
21+
22+
## How to enable netstack mode?
23+
You can enable the netstack mode for the NetBird client using environment variables:
24+
25+
`NB_USE_NETSTACK_MODE`: Set to true to enable netstack mode. (Default: false)
26+
`NB_SOCKS5_LISTENER_PORT`: Set the port where the Socks5 proxy listens. (Default: 1080)
27+
28+
<Note>
29+
The DNS feature is not supported. You can reach the peers by IP address only.
30+
</Note>
31+
32+
### Running locally
33+
```bash
34+
export NB_USE_NETSTACK_MODE=true
35+
export NB_SOCKS5_LISTENER_PORT=30000
36+
netbird up -F
37+
```
38+
39+
### Docker
40+
Some container environments can be restricted as well. For example, Docker containers are not allowed to create new VPN interfaces by default. For that reason, you can run a NetBird agent in a standard mode to enable the netstack mode:
41+
```bash
42+
docker run --rm --name PEER_NAME --hostname PEER_NAME -d \
43+
-e NB_SETUP_KEY=<SETUP KEY> -e NB_USE_NETSTACK_MODE=true -e NB_SOCKS5_LISTENER_PORT=1080 -v netbird-client:/etc/netbird netbirdio/netbird:latest
44+
```
45+
This is useful when you want to configure a simple routing peer without adding privileged permissions or linux capabilities.
46+
47+
## How to use the SOCKS5 proxy?
48+
Once you have the agent running in netstack mode, you need to configure your application to use the SOCKS5 proxy. The following is an example of a python 3 application:
49+
```python
50+
import socks
51+
import socket
52+
import os
53+
def Example():
54+
socks.set_default_proxy(socks.SOCKS5, "127.0.0.1", int(os.getenv('NB_SOCKS5_LISTENER_PORT', '1080')))
55+
socket.socket = socks.socksocket
56+
# rest of the code...
57+
```
58+
## How to use NetBird in FaaS environments?
59+
Cloud providers like AWS and Azure, allow you to configure custom runtime environments for their function services, in AWS this is called Lambda Layers,
60+
and in Azure, it's called containerized Azure Functions.
61+
62+
There are many ways that you can configure these environments with NetBird's client binary. We have created a simple example using containerized Azure Functions,
63+
which you can find [Azure functions python db access example
64+
](https://github.com/netbirdio/azure-functions-python-db-access).

src/pages/how-to/netstack.mdx

Lines changed: 0 additions & 30 deletions
This file was deleted.

0 commit comments

Comments
 (0)