Skip to content

Commit

Permalink
Update page to add a use case
Browse files Browse the repository at this point in the history
  • Loading branch information
mlsmaycon committed Jan 30, 2024
1 parent 1cc4dc4 commit fa0e013
Show file tree
Hide file tree
Showing 3 changed files with 65 additions and 31 deletions.
2 changes: 1 addition & 1 deletion src/components/NavigationDocs.jsx
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +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: 'Netstack - Cloud functions', href: '/how-to/netstack' },
{ 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' },
Expand Down
64 changes: 64 additions & 0 deletions src/pages/how-to/netbird-on-faas.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@

# Running NetBird on FaaS environments

Function as a Service (FaaS) is a cloud computing model where developers write individual "functions" – small, single-purpose pieces of code –
which are then deployed and managed by a cloud provider. This model eliminates the need for developers to manage infrastructure, as the FaaS
provider automatically handles the scaling, provisioning, and maintenance of servers. When a specific event triggers a function, the FaaS platform
executes it, only charging for the time and resources used during execution. This makes FaaS highly scalable and cost-effective, especially for applications
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.

In FaaS environments, there are significant limitations, especially in terms of accessing the system's root, kernel,
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.
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
stack is also limited. This means that tasks like creating WireGuard tunnels, which require more profound system-level network configuration, might not be feasible.


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),
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
cloud-based systems to ensure security and stability. Furthermore, NetBird enhances its network capabilities by implementing a SOCKS5 proxy, allowing applications to seamlessly
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
connectivity, all without requiring the deep system-level access typically barred in these platforms.

## 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)

<Note>
The DNS feature is not supported. You can reach the peers by IP address only.
</Note>

### 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=<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).
30 changes: 0 additions & 30 deletions src/pages/how-to/netstack.mdx

This file was deleted.

0 comments on commit fa0e013

Please sign in to comment.