Calls: Add content on datachannels and turn (#14947)

cloudflare · Jun 8, 2024 · 29dccfa · 29dccfa
1 parent 9497294
commit 29dccfa
Show file tree

Hide file tree

Showing 6 changed files with 74 additions and 22 deletions.
diff --git a/content/calls/datachannels.md b/content/calls/datachannels.md
@@ -0,0 +1,13 @@
+---
+pcx_content_type: get-started
+title: DataChannels
+weight: 8
+---
+
+# DataChannels
+
+Since Cloudflare Calls is basically a pub/sub server for WebRTC that can scale up to many subscribers per publisher, it's fit for arbitrary data besides media too.
+
+# Example
+
+An example of DataChannels in action can be found in the [Calls Examples github repo](https://github.com/cloudflare/calls-examples/tree/main/echo-datachannels).
diff --git a/content/calls/turn/custom-domains.md b/content/calls/turn/custom-domains.md
@@ -8,12 +8,12 @@ weight: 15
 
 Cloudflare Calls TURN service supports using custom domains. Custom domains do not affect any of the performance characteristics of Cloudflare Calls TURN.
 
-| Protocol      | Custom domains     | Primary port | Alternate port |
-| ------------- | ------------------- | ------------ | -------------- |
-| STUN over UDP | ✅ | 3478/udp     | 53/udp         |
-| TURN over UDP | ✅ | 3478/udp     | 53 udp         |
-| TURN over TCP | ✅ | 3478/tcp     | 80/tcp         |
-| TURN over TLS | No | 5349/tcp     | 443/tcp        |
+| Protocol      | Custom domains | Primary port | Alternate port |
+| ------------- | -------------- | ------------ | -------------- |
+| STUN over UDP | ✅             | 3478/udp     | 53/udp         |
+| TURN over UDP | ✅             | 3478/udp     | 53 udp         |
+| TURN over TCP | ✅             | 3478/tcp     | 80/tcp         |
+| TURN over TLS | No             | 5349/tcp     | 443/tcp        |
 
 ## Create a CNAME
 

diff --git a/content/calls/turn/faq.md b/content/calls/turn/faq.md
@@ -16,7 +16,7 @@ Pricing for Cloudflare Calls Serverless SFU and TURN services is $0.05 per GB of
 
 There is a free tier of 1,000 GB before any charges start. This free tier includes both Serverless SFU and TURN services. Cloudflare Calls billing appears as a single line item on your Cloudflare bill, covering both SFU and TURN.
 
-Data traffic between Cloudflare Calls TURN, Cloudflare Calls SFU, and Cloudflare Stream WHIP/WHEP does not incur any charges.
+Traffic between Cloudflare Calls TURN and Cloudflare Calls SFU or Cloudflare Stream (WHIP/WHEP) does not incur any charges.
 
 ### Is Calls TURN HIPAA/GDPR/FedRAMP compliant? 
 
@@ -36,6 +36,14 @@ There is no performance or feature level difference for Cloudflare Calls TURN se
 
 ## Technical
 
+### I need to allowlist (whitelist) Cloudflare TURN IP addresses which IP addresses should I use?
+
+Please allowlist Cloudflare's published [IP address ranges](https://www.cloudflare.com/ips/). Cloudflare's TURN service will use an IP address from this list. For more details about static IPs, guarantees and other arrangements please discuss with your enterprise account team.
+
+### I would like to hardcode IP addresses used for TURN in my application to save a DNS lookup
+
+Although this is not recommended, we understand there is a very small set of circumstances where hardcoding IP addresses might be useful. In this case, you must set up alerting that detects changes the DNS response from `turn.cloudflare.com` (A and AAAA records) and update the hardcoded IP address(es) accordingly. Note that this DNS response could return more than one IP address. In addition, you must set up a failover to a DNS query if there is a problem connecting to the hardcoded IP address. Cloudflare tries to, but cannot guarantee that the IP address used for the TURN service won't change without a specific discussion. For more details about static IPs, guarantees and other arrangements please discuss with your enterprise account team.
+
 ### Does Cloudflare Calls TURN support the expired IETF RFC draft "draft-uberti-behave-turn-rest-00"?
 
 The Cloudflare Calls credential generation function returns a JSON structure similar to the [expired RFC draft "draft-uberti-behave-turn-rest-00"](https://datatracker.ietf.org/doc/html/draft-uberti-behave-turn-rest-00), but it does not include the TTL value. If you need a response in this format, you can modify the JSON from the Cloudflare Calls credential generation endpoint to the required format in your backend server or Cloudflare Workers.
@@ -54,17 +62,12 @@ There is no defined limit for credential issuance. Start at 500 credentials/sec
 
 ### Does Calls TURN support IPv6?
 
-Cloudflare Calls is available over both IPv4 and IPv6 for TURN Client to TURN server communication, however it does not issue relay addresses in IPv6 as described in [RFC 6156](https://datatracker.ietf.org/doc/html/rfc6156).
+Yes. Cloudflare Calls is available over both IPv4 and IPv6 for TURN Client to TURN server communication, however it does not issue relay addresses in IPv6 as described in [RFC 6156](https://datatracker.ietf.org/doc/html/rfc6156).
 
 ### Does Calls TURN issue IPv6 relay addresses?
 
-Calls TURN will not respect `REQUESTED-ADDRESS-FAMILY` STUN attribute if specified and will issue IPv4 addresses only.
+No. Calls TURN will not respect `REQUESTED-ADDRESS-FAMILY` STUN attribute if specified and will issue IPv4 addresses only.
 
 ### Does Calls TURN support TCP relaying?
 
-Calls does not implement [RFC6062](https://datatracker.ietf.org/doc/html/rfc6062) and will not respect `REQUESTED-TRANSPORT` STUN attribute.
-
-### Does Calls TURN support DTLS-over-UDP?
-
-No - Calls TURN does not support DTLS-over-UDP relaying as this method is rarely used and is not implemented on the Web Platform.
-
+No. Calls does not implement [RFC6062](https://datatracker.ietf.org/doc/html/rfc6062) and will not respect `REQUESTED-TRANSPORT` STUN attribute.
diff --git a/content/calls/turn/generate-credentials.md b/content/calls/turn/generate-credentials.md
@@ -22,7 +22,7 @@ With a TURN key you can:
 
 You should generate short-lived credentials for each TURN user. In order to create credentials, you should have a back-end service that uses your TURN Token ID and API token to generate credentials. It will make an API call like this:
 
-```sh
+```bash
 curl -X POST \
 	-H "Authorization: Bearer $TURN_KEY_API_TOKEN" \
 	-H "Content-Type: application/json" -d '{"ttl": 86400}' \
@@ -82,7 +82,7 @@ When using short-lived TURN credentials with WebRTC, credentials can be refreshe
 
 Short lived credentials can also be revoked before their TTL expires with a API call like this:
 
-```sh
+```bash
 curl -X POST \
 	-H "Authorization: Bearer $TURN_KEY_API_TOKEN" \
 	https://rtc.live.cloudflare.com/v1/turn/keys/$TURN_KEY_ID/credentials/username/$USERNAME/revoke

diff --git a/content/calls/turn/overview.md b/content/calls/turn/overview.md
@@ -29,8 +29,11 @@ To learn more about the architecture that makes this possible, read this [techni
 
 ## IP Addresses
 
-Communication between TURN clients and the TURN server (as defined in [RFC5766](https://datatracker.ietf.org/doc/html/rfc5766)) which is the traffic that needs to traverse restrictive network environments, is done over a very small set of IPv6 and IPv4 addresses. If you are making adjustments to your firewalls to allow Calls TURN traffic, you must query `turn.cloudflare.com` (A and AAAA records) regularly and allowlist the resulting IP address(es). For static IPs and guarantees, please discuss with a your enterprise account team.
+### Traverse restrictive network environments and IP allowlists (whitelists)
 
+Please allowlist Cloudflare's published [IP address ranges](https://www.cloudflare.com/ips/), both IPv4 and IPv6. Cloudflare's TURN service will use an IP address from this list. For more details about static IPs, guarantees and other arrangements please discuss with your enterprise account team.
+
+### Relay allocation IP addresses
 TURN server relay allocations are done using a larger set of [IP address ranges](https://www.cloudflare.com/ips/). Calls relay allocations will be in the 9024-65535 port range.
 
 ## Protocols and Ciphers for TURN over TLS
@@ -57,8 +60,8 @@ There is no specific MTU limit for Cloudflare Calls TURN service.
 
 Cloudflare Calls TURN service places limits on:
 
-- Unique IP address you can communicate with
-- Packet rate outbound and inbound to the relay allocation
-- Data rate outbound and inbound to the relay allocation
+- Unique IP address you can communicate with per relay allocation (>5 new IP/sec)
+- Packet rate outbound and inbound to the relay allocation (>5-10 kpps)
+- Data rate outbound and inbound to the relay allocation (>50-100 Mbps)
 
-These limits are set quite high and suitable for high-demand applications and includes burst rates. Hitting these limits will result in packet drops.
+These limits are suitable for high-demand applications and also have burst rates higher than those documented above. Hitting these limits will result in packet drops.
diff --git a/content/calls/turn/rfc-matrix.md b/content/calls/turn/rfc-matrix.md
@@ -0,0 +1,33 @@
+---
+pcx_content_type: get-started
+title: TURN Feature Matrix
+weight: 18
+---
+
+# TURN Feature Matrix
+
+## TURN client to TURN server protocols
+
+| Protocol | Support | Relevant specification                                                                                    |
+| -------- | ------- | --------------------------------------------------------------------------------------------------------- |
+| UDP      | ✅      | [RFC 5766](https://datatracker.ietf.org/doc/html/rfc5766)                                                 |
+| TCP      | ✅      | [RFC 5766](https://datatracker.ietf.org/doc/html/rfc5766)                                                 |
+| TLS      | ✅      | [RFC 5766](https://datatracker.ietf.org/doc/html/rfc5766)                                                 |
+| DTLS     | No      | [draft-petithuguenin-tram-turn-dtls-00](http://tools.ietf.org/html/draft-petithuguenin-tram-turn-dtls-00) |
+
+
+## TURN client to TURN server protocols
+
+| Protocol                                        | Support                                                                                                                         | Relevant specification                                                                                               |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| TURN (base RFC)                                 | ✅                                                                                                                              | [RFC 5766](https://datatracker.ietf.org/doc/html/rfc5766)                                                            |
+| TURN REST API                                   | ✅ (See [FAQ](/calls/turn/faq/#does-cloudflare-calls-turn-support-the-expired-ietf-rfc-draft-draft-uberti-behave-turn-rest-00)) | [draft-uberti-behave-turn-rest-00](http://tools.ietf.org/html/draft-uberti-behave-turn-rest-00)                      |
+| Origin field in TURN (Multi-tenant TURN Server) | ✅                                                                                                                              | [draft-ietf-tram-stun-origin-06](https://tools.ietf.org/html/draft-ietf-tram-stun-origin-06)                         |
+| ALPN support for STUN & TURN                    | ✅                                                                                                                              | [RFC 7443](https://datatracker.ietf.org/doc/html/rfc7443)                                                            |
+| TURN Bandwidth draft specs                      | No                                                                                                                              | [draft-thomson-tram-turn-bandwidth-01](http://tools.ietf.org/html/draft-thomson-tram-turn-bandwidth-01)              |
+| TURN-bis (with dual allocation) draft specs     | No                                                                                                                              | [draft-ietf-tram-turnbis-04](http://tools.ietf.org/html/draft-ietf-tram-turnbis-04)                                  |
+| TCP relaying TURN extension                     | No                                                                                                                              | [RFC 6062](https://datatracker.ietf.org/doc/html/rfc6062)                                                            |
+| IPv6 extension for TURN                         | No                                                                                                                              | [RFC 6156](https://datatracker.ietf.org/doc/html/rfc6156)                                                            |
+| oAuth third-party TURN/STUN authorization       | No                                                                                                                              | [RFC 7635](https://datatracker.ietf.org/doc/html/rfc7635)                                                            |
+| DTLS support (for TURN)                         | No                                                                                                                              | [draft-petithuguenin-tram-stun-dtls-00](https://datatracker.ietf.org/doc/html/draft-petithuguenin-tram-stun-dtls-00) |
+| Mobile ICE (MICE) support                       | No                                                                                                                              | [draft-wing-tram-turn-mobility-02](http://tools.ietf.org/html/draft-wing-tram-turn-mobility-02)                      |