github-personal/firezone
1
0
Fork 0
mirror of https://github.com/outbackdingo/firezone.git synced 2026-01-27 10:18:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update DNS docs / blog to match new system, mention port exhaustion (#5743)

Browse Source 
Fixes #5724 
Fixes #5725 
Fixes #5726
This commit is contained in:
Jamil
2024-07-04 15:25:11 -07:00
committed by GitHub
parent d0f68fc133
commit 29df4a2f1f
10 changed files with 139 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
website/public/images/blog/how-dns-works-in-firezone/dns-based-traffic-routing.svg
View File

File diff suppressed because one or more lines are too long
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 154 KiB

After

Width:  |  Height:  |  Size: 156 KiB

24
website/src/app/blog/how-dns-works-in-firezone/readme.mdx
View File

@@ -283,13 +283,21 @@ default nameservers as if Firezone didn't exist. For DNS queries that do match a
defined Resource, however, it behaves a bit differently.
Instead of forwarding the query to your default nameservers, our special stub
resolver first asks Firezone's Policy Engine to authorize the query for the
Resource in question.
resolver generates a special, internal IP for the Resource and responds
immediately with that, storing the IP in a lookup table.
If approved, the Policy Engine forwards the query to a Gateway that's available
to serve the Resource. The Gateway then resolves the query for the Resource
(using _its_ stub resolver) and returns the final result all the way back to the
stub resolver running inside the Client.
Upon seeing packets through the tunnel matching the IP in the lookup table, the
Client generates a request to the Policy Engine to authorize the traffic. If
approved, the Policy Engine forwards the IP and DNS name corresponding to the
Resource to a Gateway that's available to serve the Resource.
The Gateway then resolves the actual IP address for the Resource (using _its_
stub resolver) and stores a mapping between it and the special, internal IP we
generated earlier.
When the Gateway sees traffic for the special, internal IP, it translates
translates it back to the actual IP of the Resource and forwards the traffic
along to the Resource.
<Alert color="info">
If you're new to Firezone, read more about
@@ -298,10 +306,6 @@ stub resolver running inside the Client.
docs.
</Alert>
Here's where things get interesting: instead of passing the resolved IP address
as-is back to the application, the stub resolver generates a dummy IP address
for it and returns that instead.
<Image
src="/images/blog/how-dns-works-in-firezone/dns-based-traffic-routing.svg"
alt="Firezone's DNS-based traffic routing"

37
website/src/app/kb/architecture/critical-sequences/readme.mdx
View File

@@ -135,24 +135,31 @@ Firezone employs a unique, granular approach to split DNS to ensure traffic
intended **only** for DNS-based Resources is routed through Firezone, leaving
other traffic untouched -- even when resolved IP addresses overlap.
To achieve this, Firezone embeds a tiny, in-memory DNS proxy inside each Client
To achieve this, Firezone embeds a tiny, in-memory DNS resolver in each Client
that intercepts all DNS queries on the system.
When the proxy sees a query that doesn't match a known Resource, it operates in
pass-through mode, forwarding the the query to the system's default resolvers or
[configured upstream resolvers](/kb/deploy/dns) in your account.
When the resolver sees a query that doesn't match a known Resource, it operates
in pass-through mode, forwarding the the query to the system's default resolvers
or [configured upstream resolvers](/kb/deploy/dns) in your account.
If the query matches a Resource, however, the following happens:
1. The proxy sends the query request to the Policy Engine for evaluation. If the
request is allowed, the Policy Engine finds an appropriate Gateway to resolve
the query.
1. The Gateway resolves the query and sends the response back to the proxy.
1. The proxy generates a special, internal IP from the range `100.96.0.0/11` or
`fd00:2021:1111:8000::/107` and maps this IP to the resolved IP returned by
the Gateway.
1. The proxy responds to the Client with this internal IP where it is then
returned back to the application making the original request.
1. The resolver generates a special, internal IP from the range `100.96.0.0/11`
or `fd00:2021:1111:8000::/107` and stores an internal mapping of this IP to
the DNS name originally queried. The IP is returned to the application that
made the query.
1. When the Client sees traffic for the IP, it triggers connection setup. The
Client sends a request to the Policy Engine for evaluation. If the request is
allowed, the Policy Engine finds an appropriate Gateway to route the traffic.
1. At the same time, the Gateway receives the request via the control plane and
resolves the DNS query using its system resolver, storing the result in a
lookup table.
1. If the Policy Engine approves the Client's request, it sends the Client the
WireGuard keys and NAT traversal information for the Gateway that will serve
the Resource.
1. Traffic from the application flows, and the Gateway translates the internal
IP back to the actual IP address of the Resource, forwarding the traffic
accordingly.
This is why you'll see DNS-based Resources resolve to IPs such as `100.96.0.1`
while the Client is signed in:
@@ -169,6 +176,10 @@ Name: github.com
Address: 100.96.0.1
```
Notice in the above process that at no point does the Client's system resolver
see the actual IP address of the Resource. This ensures that your DNS data
remains private and secure.
For a deeper dive into how (and why) DNS works this way in Firezone, see the
[How DNS works in Firezone](/blog/how-dns-works-in-firezone) article.

11
website/src/app/kb/automate/terraform/aws/readme.mdx
View File

@@ -48,9 +48,18 @@ Gateways. There's no limit to the number of Firezone Gateways you can deploy in
a single VPC. A basic AutoScaling Group is provisioned as part of the linked
module.
<Alert color="warning">
If you need more than 55,000 concurrent connections, you can increase the
number of IP addresses associated to the AWS NAT Gateway. See [AWS's
documentation](https://repost.aws/knowledge-center/vpc-resolve-port-allocation-errors)
for more information.
</Alert>
We've tested with `t3.nano` instances which still work quite well for most
applications. However, you may want to consider a larger instance type if you
have a high volume of traffic or lots of concurrent connections.
have a high volume of traffic or lots of concurrent connections. See
[Gateway sizing recommendations](/kb/deploy/gateeways#sizing-recommendations)
for some general guidelines depending on your expected traffic.
## Deployment

11
website/src/app/kb/automate/terraform/azure/readme.mdx
View File

@@ -51,9 +51,18 @@ Gateways. There's no limit to the number of Firezone Gateways you can deploy in
a single Vnet. A basic Azure Autoscale configuration is provisioned as part of
the linked module.
<Alert color="warning">
If you need more than 64,512 concurrent connections, you can increase the
number of public IP addresses reserved for the Azure NAT Gateway. See [Azure's
documentation](https://learn.microsoft.com/en-us/azure/nat-gateway/troubleshoot-nat-connectivity)
for more information.
</Alert>
We've tested with `Standard_B1ls` instances which still work quite well for most
applications. However, you may want to consider a larger instance type if you
have a high volume of traffic or lots of concurrent connections.
have a high volume of traffic or lots of concurrent connections. See
[Gateway sizing recommendations](/kb/deploy/gateeways#sizing-recommendations)
for some general guidelines depending on your expected traffic.
## Deployment

11
website/src/app/kb/automate/terraform/gcp/readme.mdx
View File

@@ -49,9 +49,18 @@ Simply update the number of replicas to deploy more or fewer Firezone Gateways.
There's no limit to the number of Firezone Gateways you can deploy in a single
VPC.
<Alert color="warning">
If you need more than 64,512 concurrent connections, you can increase the
number of public IP addresses reserved for the Cloud NAT. See [Google's
documentation](https://cloud.google.com/nat/docs/ports-and-addresses#ports)
for more information.
</Alert>
We've tested with `f1-micro` instances which still work quite well for most
applications. However, you may want to consider a larger instance type if you
have a high volume of traffic or lots of concurrent connections.
have a high volume of traffic or lots of concurrent connections. See
[Gateway sizing recommendations](/kb/deploy/gateeways#sizing-recommendations)
for some general guidelines depending on your expected traffic.
## Deployment

36
website/src/app/kb/deploy/dns/readme.mdx
View File

@@ -15,11 +15,11 @@ Read more below to understand how it works and how to configure it.
## How DNS works in Firezone
Each Firezone Client embeds a lightweight DNS proxy used to route queries to an
appropriate Gateway for resolution.
Each Firezone Client embeds a lightweight DNS resolver used to route queries to
an appropriate Gateway for resolution.
When a user signs in, the Client configures the host operating system to use
this proxy as the default resolver for all queries on the system.
this resolver as the default resolver for all queries on the system.
This is why you'll commonly see `100.100.111.1` or
`fd00:2021:1111:8000::100:100:111:0` as the DNS server responding to DNS queries
@@ -32,11 +32,20 @@ when the Firezone Client is signed in.
docs](/kb/architecture/critical-sequences#dns-resolution).
</Alert>
When the proxy sees a DNS query for a Resource, it asks the portal for a healthy
Gateway to handle the query. The Gateway resolves the query using its system
resolver and sends the result back to the proxy, which generates a mapped IP to
the Resource's actual IP address. The final mapped IP is then returned to the
application making the query.
When the resolver sees a DNS query for a Resource, it generates a mapped, dummy
IP and responds with that IP. The mapped IP is used to route traffic
corresponding to the Resource in question to a healthy Gateway. While this is
happening, the Gateway receives the query via the control plane and resolves it
using its system resolver, storing the result in a lookup table.
When the Gateway sees traffic coming from the Client for the mapped IP, it
translates the mapped IP back to the actual IP address of the Resource and
forwards the traffic to the Resource.
This happens in a fraction of a second and is completely transparent to the end
user. The Client host's system resolver is never used for resolving DNS queries
for Firezone Resources, and never sees the actual IP addresses of DNS Resources
in your account, ensuring your DNS data remains private and secure.
For example, if `github.com` was added as a Resource, an `nslookup` might return
`100.96.0.1` as its IPv4 address:
@@ -51,9 +60,16 @@ Name: github.com
Address: 100.96.0.1
```
If the query doesn't match a Resource, the proxy forwards the query to one of
If the query doesn't match a Resource, the resolver forwards the query to one of
the [upstream resolvers](#configuring-client-dns-upstream-resolvers) if
configured.
configured in your account. Otherwise, it forwards the query to the default
system resolver on the Client host.
<Alert color="info">
Firezone only intercepts queries for the `A`, `AAAA`, and `PTR` record types
for your DNS Resources. All other record types are forwarded to the upstream
resolver(s).
</Alert>
## Configuring Client DNS upstream resolvers

6
website/src/components/KbSidebar/index.tsx
View File

@@ -20,7 +20,7 @@ export default function KbSidebar() {
<SidebarItem href="/kb">Overview</SidebarItem>
<SidebarItem href="/kb/quickstart">Quickstart guide</SidebarItem>
</SidebarItemGroup>
<SidebarItemGroup>
<SidebarItemGroup label="Get started">
<SidebarCollapse prefix="/kb/deploy" label="Deploy">
<SidebarItem href="/kb/deploy">Overview</SidebarItem>
<SidebarItem href="/kb/deploy/sites">Sites</SidebarItem>
@@ -76,7 +76,7 @@ export default function KbSidebar() {
</SidebarItem>
</SidebarCollapse>
</SidebarItemGroup>
<SidebarItemGroup>
<SidebarItemGroup label="Use Firezone">
<SidebarCollapse prefix="/kb/administer" label="Administer">
<SidebarItem href="/kb/administer">Overview</SidebarItem>
<SidebarItem href="/kb/administer/upgrading">
@@ -138,7 +138,7 @@ export default function KbSidebar() {
</SidebarItem>
</SidebarCollapse>
</SidebarItemGroup>
<SidebarItemGroup>
<SidebarItemGroup label="Learn more">
<SidebarCollapse prefix="/kb/architecture" label="Architecture">
<SidebarItem href="/kb/architecture">Overview</SidebarItem>
<SidebarItem href="/kb/architecture/core-components">

10
website/src/components/RootNavbar/index.tsx
View File

@@ -51,8 +51,8 @@ const navbarTheme: CustomFlowbiteTheme["navbar"] = {
link: {
base: "block py-2 pl-3 pr-4 md:p-0 border-b border-neutral-200 md:border-transparent",
active: {
on: "bg-neutral-200 rounded text-white md:bg-transparent md:text-neutral-800 font-semibold text-accent-900",
off: "text-neutral-700 hover:bg-neutral-100 transition transform duration-50 hover:text-neutral-800 md:hover:bg-transparent md:hover:border-b-2 md:hover:border-neutral-600",
on: "bg-neutral-200 rounded text-white md:bg-transparent text-primary-450 font-semibold",
off: "text-neutral-700 hover:text-primary-450 hover:bg-neutral-100 transition transform duration-50 md:hover:bg-transparent md:hover:border-b-2 md:hover:border-primary-450",
},
disabled: {
on: "text-neutral-400 hover:cursor-not-allowed",
@@ -97,7 +97,7 @@ const dropdownTheme: CustomFlowbiteTheme["dropdown"] = {
target: "w-fit",
},
inlineWrapper:
"flex items-center py-2 pl-3 pr-4 md:p-0 text-neutral-700 hover:text-neutral-800 md:border-transparent md:border-b-2 md:hover:border-neutral-600 duration-50 transition transform",
"flex items-center py-2 pl-3 pr-4 md:p-0 text-neutral-700 hover:text-primary-450 md:border-transparent md:border-b-2 md:hover:border-primary-450 duration-50 transition transform",
};
function NavbarLink({
@@ -193,7 +193,7 @@ export default function RootNavbar() {
</div>
<ActionLink
href="https://app.firezone.dev/"
className="hidden md:inline-flex py-2 pl-3 pr-4 md:p-0 font-medium text-neutral-700 md:border-transparent hover:text-neutral-800 hover:bg-neutral-200 md:hover:bg-transparent md:border-b-2 md:hover:border-neutral-600 duration-50 transition transform"
className="hidden md:inline-flex py-2 pl-3 pr-4 md:p-0 font-medium text-neutral-700 md:border-transparent hover:text-primary-450 hover:bg-neutral-200 md:hover:bg-transparent md:border-b-2 md:hover:border-primary-450 duration-50 transition transform"
size="w-5 h-5"
>
Sign in
@@ -201,7 +201,7 @@ export default function RootNavbar() {
</NavbarCollapse>
<div className="hidden md:flex space-x-4 items-center">
<Link
className="block py-2 pl-3 pr-4 md:p-0 font-medium text-neutral-700 md:border-transparent hover:text-neutral-800 md:border-b-2 hover:border-neutral-600 duration-50 transition transform"
className="block py-2 pl-3 pr-4 md:p-0 font-medium text-neutral-700 md:border-transparent hover:text-primary-450 md:border-b-2 hover:border-primary-450 duration-50 transition transform"
href="https://app.firezone.dev/sign_up"
>
Sign up

25
website/src/components/Sidebar/index.tsx
View File

@@ -6,6 +6,12 @@ import { Sidebar as FlowbiteSidebar } from "flowbite-react";
import Link from "next/link";
import { useDrawer } from "@/components/Providers/DrawerProvider";
const ItemGroupLabelTheme: CustomFlowbiteTheme["sidebar"] = {
item: {
base: "flex items-center justify-center rounded p-2 text-sm font-semibold uppercase text-primary-450",
},
};
const FlowbiteSidebarTheme: CustomFlowbiteTheme["sidebar"] = {
root: {
base: "h-[calc(100vh)] left-0 top-0 z-40 sticky bg-white transition-transform pt-16 pb-8",
@@ -121,8 +127,23 @@ export function SidebarItems({ children }: { children: React.ReactNode }) {
return <FlowbiteSidebar.Items>{children}</FlowbiteSidebar.Items>;
}
export function SidebarItemGroup({ children }: { children: React.ReactNode }) {
return <FlowbiteSidebar.ItemGroup>{children}</FlowbiteSidebar.ItemGroup>;
export function SidebarItemGroup({
label,
children,
}: {
label?: string;
children: React.ReactNode;
}) {
return (
<FlowbiteSidebar.ItemGroup>
{label && (
<FlowbiteSidebar.Item theme={ItemGroupLabelTheme?.item}>
{label}
</FlowbiteSidebar.Item>
)}
{children}
</FlowbiteSidebar.ItemGroup>
);
}
export function SidebarCollapse({