|
| 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). |
0 commit comments