diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 4f50076d..62294cce 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -57,6 +57,7 @@ export const docsNavigation = [ { title: 'Monitor system and network activity', href: '/how-to/monitor-system-and-network-activity' }, { title: 'Activity event streaming', href: '/how-to/activity-event-streaming' }, { title: 'Access NetBird API', href: '/how-to/access-netbird-public-api' }, + { title: 'Running NetBird on FaaS', href: '/how-to/netbird-on-faas' }, { title: 'Examples', href: '/how-to/examples' }, { title: 'CLI', href: '/how-to/cli' }, { title: 'Delete your NetBird account', href: '/how-to/delete-account' }, diff --git a/src/pages/how-to/netbird-on-faas.mdx b/src/pages/how-to/netbird-on-faas.mdx new file mode 100644 index 00000000..2153fc07 --- /dev/null +++ b/src/pages/how-to/netbird-on-faas.mdx @@ -0,0 +1,56 @@ + +# Running NetBird on FaaS environments + +Function as a Service (FaaS) is a cloud computing model where developers deploy small, specific-purpose code functions, managed by a cloud provider. +FaaS environments, however, impose restrictions like limited access to the system's root, kernel, and network stack, crucial for security in shared cloud infrastructure. + +Since [v0.25.3](https://github.com/netbirdio/netbird/releases), NetBird enables secure connectivity and access from serverless functions like AWS lambda and Azure Functions to cloud or on-premises servers, +containers, databases, and other internal resources. NetBird has adapted to the constraints of FaaS environments by leveraging netstack from +the [gVisor](https://github.com/google/gvisor) Go package, which is part of [Wireguard-go](https://github.com/netbirdio/wireguard-go), +enabling the WireGuard stack to run entirely in userspace. This approach circumvents the typical need for network or kernel-level access. + +## How to enable netstack mode? +You can enable the netstack mode for the NetBird client using environment variables: + +`NB_USE_NETSTACK_MODE`: Set to true to enable netstack mode. (Default: false) +`NB_SOCKS5_LISTENER_PORT`: Set the port where the Socks5 proxy listens. (Default: 1080) + +With these variables, NetBird will launch a Socks5 proxy that you can use to connect to your internal resources. + + + The DNS feature is not supported. You can reach the peers by IP address only. + + +### Running locally +```bash +export NB_USE_NETSTACK_MODE=true +export NB_SOCKS5_LISTENER_PORT=30000 +netbird up -F +``` + +### Docker +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: +```bash +docker run --rm --name PEER_NAME --hostname PEER_NAME -d \ +-e NB_SETUP_KEY= -e NB_USE_NETSTACK_MODE=true -e NB_SOCKS5_LISTENER_PORT=1080 -v netbird-client:/etc/netbird netbirdio/netbird:latest +``` +This is useful when you want to configure a simple routing peer without adding privileged permissions or linux capabilities. + +## How to use the SOCKS5 proxy? +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: +```python +import socks +import socket +import os +def Example(): + socks.set_default_proxy(socks.SOCKS5, "127.0.0.1", int(os.getenv('NB_SOCKS5_LISTENER_PORT', '1080'))) + socket.socket = socks.socksocket + # rest of the code... +``` +## How to use NetBird in FaaS environments? +Cloud providers like AWS and Azure, allow you to configure custom runtime environments for their function services, in AWS this is called Lambda Layers, +and in Azure, it's called containerized Azure Functions. + +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, +which you can find [Azure functions python db access example +](https://github.com/netbirdio/azure-functions-python-db-access). \ No newline at end of file