6PN and other edits

networking/custom-private-networks.html.markerb

@@ -4,7 +4,11 @@ layout: docs
 nav: firecracker
 ---
 
-When you need to isolate users for security reasons, you can use custom private networks. Every organization gets a default [private network](https://fly.io/docs/networking/private-networking/) (6PN) and all the apps in that 6PN can communicate using `.internal` domains. A custom network is a distinct 6PN within your organization. Apps on separate 6PNs can never communicate unless explicitly configured to do so.
+When you need to isolate users for security reasons, you can use custom private networks. 
+
+Every organization gets a default [private network](https://fly.io/docs/networking/private-networking/) (6PN) and all the apps in that 6PN can communicate using `.internal` domains. A custom network is a distinct 6PN within your organization. Apps on separate 6PNs can never communicate unless explicitly configured to do so.
+
+## When to use custom 6PNs
 
 Custom 6PNs are a good solution for tenant isolation within a single organization. If you run an _Something_-as-a-Service platform on top of Fly.io, then you can create an app per customer on a custom 6PN for secure isolation between customers. For example, an app on a custom 6PN for each customer instance of your service, or for each customer running untrusted code on your platform. Customer Machines can communicate freely within their app (or between apps in their custom 6PN), but won't be able to reach Machines or apps on other custom 6PNs.
 
@@ -16,7 +20,7 @@ Network names are unique within your organization. You can't reuse a network nam
 
 If you destroy all the apps on a custom 6PN, the network technically still exists. 
 
-It's a best practice to use a formula for naming custom 6PNs, especially if you're going to have a lot of them or if you need to add more than one app to each custom 6PN. For example, `customerID-network` or `app-name-network`. Network names can have letters, numbers, and dashes, but must start with a letter.
+It's a best practice to use a formula for naming custom 6PNs, especially if you're going to have a lot of them or if you need to add more than one app to each custom 6PN. For example, `customerID-network` or `app-name-some-id-network`. Network names can have letters, numbers, and dashes, but must start with a letter.
 
 ## Create a custom private network
 
@@ -49,7 +53,7 @@ fly apps create <app name> --network <network name>
 
 The `fly apps create` command creates an "empty" app with no Machines. You'll need to manually create Machines for the app using flyctl or the Machines API.
 
-## How apps on different 6PNs can connect
+## Connect apps in different 6PNs
 
 Private apps on different 6PNs can't communicate without being explicitly configured to do so.
 
@@ -59,7 +63,7 @@ If an app is public, then apps on different 6PNs can reach that app using the pu
 
 ### Private apps with Flycast
 
-You can use a Flycast private IPv6 address to expose an app on one private network to another private network; the app won't be accessible via Flycast from its own network. When you assign the Flycast address, use the `--network` option specify the network from which requests will originate. For example:
+You can use a Flycast private IPv6 address to expose an app on one private network to another private network; the app won't be accessible via Flycast from its own network. When you assign the Flycast address, use the `--network` option to specify the network from which requests will originate. For example:
 
 ```cmd
 fly ips allocate-v6 --private --network custom-network-name
@@ -71,11 +75,11 @@ Learn more about using [Flycast](/docs/networking/flycast/).
 
 The `fly-replay` response header tells Fly Proxy to forward HTTP requests to another app or Machine in your organization. You can use `fly-replay` to deliver requests to customer apps or Machines on custom 6PNs without having to expose them publicly.
 
-For example, you could receive HTTP requests on a public router app and then forward the requests to specific apps or Machines on a customer's custom 6PN. The customer apps need to have services configured to expose a port on which to receive the requests. Make sure the customer apps don't have public IP addresses: apps created with the Machines API or with `fly apps create` don't get public IPs by default, but apps created with `fly launch` do.
+For example, you could receive HTTP requests on a public "router" app and then forward the requests to specific apps or Machines on a customer's custom 6PN. The customer apps need to have services configured to expose a port on which to receive the requests. Make sure the customer apps don't have public IP addresses: apps created with the Machines API or with `fly apps create` don't get public IPs by default, but most apps created with `fly launch` do.
 
 Learn more about using the [`fly-replay` response header](/docs/networking/dynamic-request-routing/#the-fly-replay-response-header).
 
-## How to connect to Machines on custom 6PNs
+## Connect directly to Machines on custom 6PNs
 
 As an administrator with a multi-tenant setup, you might need to troubleshoot customer issues. You can use flyctl's networking commands to reach Machines on a customer's 6PN within your organization, including:
 
@@ -85,9 +89,9 @@ As an administrator with a multi-tenant setup, you might need to troubleshoot cu
 
 ## Check which network an app or Machine is on
 
-You can retrieve the network name for all apps in your organization and you can also verify that an apps or Machines are on different networks by examining the private IPv6 addresses.
+You can retrieve the network name for all apps in your organization and you can also verify that apps or Machines are on different networks by examining their private IPv6 addresses.
 
-### Retrieve network names
+### Get network names
 
 Right now the only way to get an app's network name is by listing all the apps in an organization with the Machines API.
 
@@ -118,13 +122,14 @@ See the [Machines API docs](https://fly.io/docs/machines/api/) for more informat
 
 ### Network ID embedded in private IPv6 addresses
 
-Each 6PN is identified by a network ID, which is encoded in 32-bits of each private IPv6 address.
+Each 6PN is identified by a network ID, which is encoded into 32-bits of each private IPv6 address.
 
-You can confirm whether two Machines are on different networks by comparing their private IPv6 addresses. You can get a Machine's 6PN address in one of the following ways:
+You can confirm whether two Machines are on different networks by comparing their private IPv6 addresses. You can get a Machine's 6PN address in any of the following ways:
 
 - run `fly machines list -a my-app-name` 
 - run `fly machines status <machine id>`
 - from the Machine's `FLY_PRIVATE_IP` environment variable
+- [list the Machines in an app](/docs/machines/api/machines-resource/#list-machines) or [get a specific Machine config](/docs/machines/api/machines-resource/#get-a-machine) using the Machines API
 
 All Fly.io private IPv6 addresses start with `fdaa`. The 32-bits following `fdaa` identify the 6PN. For example, the following addresses belong to Machines on different 6PNs:
 
@@ -133,9 +138,8 @@ Machine 1: fdaa:2:45b:a7b:174:db43:d3c6:2
 Machine 2: fdaa:9:d844:a7b:e:33bd:e8b1:2
 ```
 
-For Machine 1, the network ID is embedded in `:2:45b:`, and for Machine 2 the network ID is embedded in `:9:d844:`.
+Machine 1's network ID is embedded in `:2:45b:` and Machine 2's network ID is embedded in `:9:d844:`.
 
-Flycast addresses also include the network ID in the same 32-bit grouping.
+Flycast addresses also include the network ID in the same 32-bit grouping. Run `fly ips list` to get an app's private IPv6 address.
 
 Learn about [6PN addresses in detail](/docs/networking/private-networking/#6pn-addresses-in-detail).
-

networking/private-networking.html.md

@@ -7,15 +7,15 @@ redirect_from:
   - /docs/reference/private-networking/
 ---
 
-Fly Apps are connected by a mesh of WireGuard tunnels using IPv6. Private networking is always available to apps by default; you don't have to do anything special to get it.
+Fly Apps in an organization are connected by a mesh of WireGuard tunnels using IPv6 called a 6PN. Private networking over your 6PN is always available to apps by default; you don't have to do anything special to get it.
 
-Apps within the same organization are assigned special addresses (6PN addresses) tied to the organization. Those applications can talk to each other because of their 6PN addresses, but applications from other organizations can't. The Fly.io platform won't forward packets between different 6PN networks, unless you explicitly allow it when you [allocate a Flycast address](/docs/networking/flycast/#allocate-a-flycast-address).
+Apps within the same organization are assigned special addresses (6PN addresses) tied to 6PN. Those applications can talk to each other because of their 6PN addresses, but applications from other organizations can't. The Fly.io platform won't forward packets between different 6PNs, unless you explicitly allow it, for example when you [allocate a Flycast address](/docs/networking/flycast/#allocate-a-flycast-address).
 
-You can connect apps running outside of Fly.io to your 6PN network using WireGuard. You can even connect your dev laptop to your 6PN network. To do that, you'll use flyctl, the Fly.io CLI, to generate a [WireGuard configuration that has a 6PN address](#private-network-vpn).
+You can connect apps running outside of Fly.io to your 6PN using WireGuard. You can even connect your dev laptop to your 6PN. To do that, you'll use flyctl, the Fly.io CLI, to generate a [WireGuard configuration that has a 6PN address](#private-network-vpn).
 
 ## Fly.io `.internal` DNS
 
-You can use `.internal` domains to connect your app to databases, API servers, or other apps in your 6PN network. If you don't need the granular subdomains and routing available with `.internal`, and you want to use Fly Proxy features for your internal apps, then you should use [Flycast](/docs/networking/flycast/) instead.
+You can use `.internal` domains to connect your app to databases, API servers, or other apps in your 6PN. If you don't need the granular subdomains and routing available with `.internal`, and you want to use Fly Proxy features for your internal apps, then you should use [Flycast](/docs/networking/flycast/) instead.
 
 A Fly Machine is configured to resolve domain names with a custom DNS server from the Fly Platform. This DNS server can resolve arbitrary DNS queries, so you can look up `google.com` with it. But it’s also aware of 6PN addresses, and will let you look up 6PN addresses for other apps in your organization. Those addresses live under the custom top-level domain `.internal`. 
 
@@ -53,7 +53,7 @@ See the [fly-examples/privatenet](https://github.com/fly-apps/privatenet+externa
 
 When deploying a Fly Machine, we alias the 6PN address of the Machine to `fly-local-6pn` in the Machine's `/etc/hosts` file.
 
-Your app's service needs to bind to/listen on `fly-local-6pn` to be accessible via its 6PN address. For example, if you have a service running on port 8080, then you need to bind it to `fly-local-6pn:8080` for it to be accessible to other Machines over the 6PN network.
+Your app's service needs to bind to/listen on `fly-local-6pn` to be accessible via its 6PN address. For example, if you have a service running on port 8080, then you need to bind it to `fly-local-6pn:8080` for it to be accessible to other Machines over the 6PN.
 
 <div class="note icon">
 `fly-local-6pn` is to 6PN addresses as `localhost` is to 127.0.0.1, so you can also bind directly to the 6PN address itself.