> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Connection Variables
> Reference documentation for connection variables in Traffic Policy including client IP, geo-location, TLS details, Kubernetes pod identity, and IP intelligence data.
## Connection Variables
The following variables are available under the `conn` namespace:
| Name | Type | Description |
| - | - | - |
| [`conn.bytes_in`](#connbytes-in) | `int64` | The number of bytes entering the endpoint from the client. |
| [`conn.bytes_out`](#connbytes-out) | `int64` | The number of bytes leaving an endpoint to the client. |
| [`conn.client_ip`](#connclient-ip) | `string` | Source IP of the connection to the ngrok endpoint. |
| [`conn.client_port`](#connclient-port) | `int32` | Source port of the connection to the ngrok endpoint. |
| [`conn.server_ip`](#connserver-ip) | `string` | The IP that this connection was established on. |
| [`conn.server_port`](#connserver-port) | `int32` | The port that this connection was established on. |
| [`conn.server_region`](#connserver-region) | `string` | The ngrok [PoP (Point of Presence)](/docs/gateway/points-of-presence/) that this connection was established on and serviced through. |
| [`conn.ts.start`](#conntsstart) | `timestamp` | Timestamp when the connection to ngrok was started. |
### `conn.bytes_in`
The number of bytes entering the endpoint from the client.
```yaml policy.yml theme={null}
expressions:
- "conn.bytes_in > 1000"
```
```json policy.json theme={null}
{
"expressions": [
"conn.bytes_in > 1000"
]
}
```
### `conn.bytes_out`
The number of bytes leaving an endpoint to the client.
```yaml policy.yml theme={null}
expressions:
- "conn.bytes_out > 1000"
```
```json policy.json theme={null}
{
"expressions": [
"conn.bytes_out > 1000"
]
}
```
### `conn.client_ip`
Source IP of the connection to the ngrok endpoint.
```yaml policy.yml theme={null}
expressions:
- "conn.client_ip in ['::1', '127.0.0.1']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.client_ip in ['::1', '127.0.0.1']"
]
}
```
### `conn.client_port`
Source port of the connection to the ngrok endpoint.
```yaml policy.yml theme={null}
expressions:
- "conn.client_port == 80"
```
```json policy.json theme={null}
{
"expressions": [
"conn.client_port == 80"
]
}
```
### `conn.server_ip`
The IP that this connection was established on.
```yaml policy.yml theme={null}
expressions:
- "conn.server_ip == '192.168.1.1'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.server_ip == '192.168.1.1'"
]
}
```
### `conn.server_port`
The port that this connection was established on.
```yaml policy.yml theme={null}
expressions:
- "conn.server_port == 80"
```
```json policy.json theme={null}
{
"expressions": [
"conn.server_port == 80"
]
}
```
### `conn.server_region`
The ngrok [PoP (Point of Presence)](/docs/gateway/points-of-presence/) that this connection was established on and serviced through.
```yaml policy.yml theme={null}
expressions:
- "conn.server_region == 'eu'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.server_region == 'eu'"
]
}
```
### `conn.ts.start`
Timestamp when the connection to ngrok was started.
```yaml policy.yml theme={null}
expressions:
- "conn.ts.start > timestamp('2023-12-31T00:00:00Z')"
```
```json policy.json theme={null}
{
"expressions": [
"conn.ts.start > timestamp('2023-12-31T00:00:00Z')"
]
}
```
## Connection Geo Variables
The following variables are available under the `conn.geo` namespace:
| Name | Type | Description |
| - | - | - |
| [`conn.geo.city`](#conngeocity) | `string` | The name of the city, in EN, where the `conn.client_ip` is likely to originate. |
| [`conn.geo.country`](#conngeocountry) | `string` | The name of the country, in EN, where the `conn.client_ip` is likely to originate. |
| [`conn.geo.country_code`](#conngeocountry-code) | `string` | The two-letter ISO country code where the `conn.client_ip` is likely to originate. |
| [`conn.geo.latitude`](#conngeolatitude) | `string` | The approximate latitude where the `conn.client_ip` is likely to originate. |
| [`conn.geo.longitude`](#conngeolongitude) | `string` | The approximate longitude where the `conn.client_ip` is likely to originate. |
| [`conn.geo.radius`](#conngeoradius) | `string` | The radius in kilometers around the latitude and longitude where the `conn.client_ip` is likely to originate. |
| [`conn.geo.subdivision`](#conngeosubdivision) | `string` | The name of the subdivision, in EN, where the `conn.client_ip` is likely to originate. |
### `conn.geo.city`
The name of the city, in EN, where the `conn.client_ip` is likely to originate.
```yaml policy.yml theme={null}
expressions:
- "conn.geo.city == 'Strongsville'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.geo.city == 'Strongsville'"
]
}
```
### `conn.geo.country`
The name of the country, in EN, where the `conn.client_ip` is likely to originate.
```yaml policy.yml theme={null}
expressions:
- "conn.geo.country == 'United States'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.geo.country == 'United States'"
]
}
```
### `conn.geo.country_code`
The two-letter ISO country code where the `conn.client_ip` is likely to originate.
```yaml policy.yml theme={null}
expressions:
- "conn.geo.country_code != 'US'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.geo.country_code != 'US'"
]
}
```
### `conn.geo.latitude`
The approximate latitude where the `conn.client_ip` is likely to originate.
```yaml policy.yml theme={null}
expressions:
- "double(conn.geo.latitude) >= 45.0"
```
```json policy.json theme={null}
{
"expressions": [
"double(conn.geo.latitude) >= 45.0"
]
}
```
### `conn.geo.longitude`
The approximate longitude where the `conn.client_ip` is likely to originate.
```yaml policy.yml theme={null}
expressions:
- "double(conn.geo.longitude) <= -93.0"
```
```json policy.json theme={null}
{
"expressions": [
"double(conn.geo.longitude) <= -93.0"
]
}
```
### `conn.geo.radius`
The radius in kilometers around the latitude and longitude where the `conn.client_ip` is likely to originate.
```yaml policy.yml theme={null}
expressions:
- "conn.geo.radius <= '5'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.geo.radius <= '5'"
]
}
```
### `conn.geo.subdivision`
The name of the subdivision, in EN, where the `conn.client_ip` is likely to originate.
```yaml policy.yml theme={null}
expressions:
- "conn.geo.subdivision == 'California'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.geo.subdivision == 'California'"
]
}
```
## Connection TLS Variables
The following variables are available under the `conn.tls` namespace:
| Name | Type | Description |
| - | - | - |
| [`conn.tls.cipher_suite`](#conntlscipher-suite) | `string` | The cipher suite selected during the TLS handshake. |
| [`conn.tls.ja4_fingerprint`](#conntlsja4-fingerprint) | `string` | The JA4 fingerprint of the TLS handshake. |
| [`conn.tls.negotiated_alpn`](#conntlsnegotiated-alpn) | `string` | TLS Application-Layer Protocol Negotiation (ALPN) Protocol ID of the protocol agreed upon in the TLS handshake |
| [`conn.tls.session_resumed`](#conntlssession-resumed) | `bool` | True if the TLS session was resumed. Currently always false |
| [`conn.tls.sni`](#conntlssni) | `string` | The hostname included in the `ClientHello` message via the SNI extension. |
| [`conn.tls.version`](#conntlsversion) | `string` | The version of the TLS protocol used between the client and the ngrok edge. |
### `conn.tls.cipher_suite`
The cipher suite selected during the TLS handshake.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.cipher_suite == 'TLS_AES_128_GCM_SHA256'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.cipher_suite == 'TLS_AES_128_GCM_SHA256'"
]
}
```
### `conn.tls.ja4_fingerprint`
The JA4 fingerprint of the TLS handshake.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.ja4_fingerprint == 't13d1717h2_5b57614c22b0_f0fc7018f8e8'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.ja4_fingerprint == 't13d1717h2_5b57614c22b0_f0fc7018f8e8'"
]
}
```
### `conn.tls.negotiated_alpn`
The TLS Application-Layer Protocol Negotiation (ALPN) Protocol ID of the protocol agreed upon in the TLS handshake. Defaults to `""` if no ALPN was successfully negotiated.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.negotiated_alpn == 'h2'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.negotiated_alpn == 'h2'"
]
}
```
### `conn.tls.session_resumed`
True if the TLS session was resumed. Currently always false as we do not yet support TLS session resumption.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.session_resumed == false"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.session_resumed == false"
]
}
```
### `conn.tls.sni`
The hostname included in the `ClientHello` message via the SNI extension.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.sni == 'client.example.com'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.sni == 'client.example.com'"
]
}
```
### `conn.tls.version`
The version of the TLS protocol used between the client and the ngrok edge.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.version == '1.3'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.version == '1.3'"
]
}
```
## Connection TLS Client Variables
The following variables are available under the `conn.tls.client` namespace:
| Name | Type | Description |
| - | - | - |
| [`conn.tls.client.extensions`](#conntlsclientextensions) | `[]Extension` | Additional information added to the certificate. |
| [`conn.tls.client.extensions[i].id`](#conntlsclientextensionsiid) | `string` | The identifier (OID) that specifies the type of extension. |
| [`conn.tls.client.extensions[i].critical`](#conntlsclientextensionsicritical) | `bool` | True if the extension is critical. |
| [`conn.tls.client.extensions[i].value`](#conntlsclientextensionsivalue) | `[]byte` | The data for the extension. |
| [`conn.tls.client.issuer`](#conntlsclientissuer) | `string` | The issuing authority of the certificate as a string roughly following the RFC 2253 Distinguished Names syntax. |
| [`conn.tls.client.issuer.common_name`](#conntlsclientissuercommon-name) | `string` | Common name of the issuing authority, usually the domain name. |
| [`conn.tls.client.issuer.country`](#conntlsclientissuercountry) | `[]string` | Country names where the issuing authority is located. |
| [`conn.tls.client.issuer.locality`](#conntlsclientissuerlocality) | `[]string` | Locality or city of the issuing authority. |
| [`conn.tls.client.issuer.organization`](#conntlsclientissuerorganization) | `[]string` | Name of the organization that issued the certificate. |
| [`conn.tls.client.issuer.organizational_unit`](#conntlsclientissuerorganizational-unit) | `[]string` | Division of the organization responsible for the certificate. |
| [`conn.tls.client.issuer.postal_code`](#conntlsclientissuerpostal-code) | `[]string` | Postal code of the issuing authority. |
| [`conn.tls.client.issuer.province`](#conntlsclientissuerprovince) | `[]string` | Province or state of the issuing authority. |
| [`conn.tls.client.issuer.street_address`](#conntlsclientissuerstreet-address) | `[]string` | Street address of the issuing authority. |
| [`conn.tls.client.pem`](#conntlsclientpem) | `string` | Full PEM-encoded client certificate of the TLS connection. |
| [`conn.tls.client.san`](#conntlsclientsan) | `string` | Subject alternative names of the client certificate. |
| [`conn.tls.client.san.dns_names`](#conntlsclientsandns-names) | `[]string` | DNS names in the subject alternative names. |
| [`conn.tls.client.san.email_addresses`](#conntlsclientsanemail-addresses) | `[]string` | Email addresses in the subject alternative names. |
| [`conn.tls.client.san.ip_addresses`](#conntlsclientsanip-addresses) | `[]string` | IP addresses in the subject alternative names. |
| [`conn.tls.client.san.uris`](#conntlsclientsanuris) | `[]string` | URIs in the subject alternative names. |
| [`conn.tls.client.serial_number`](#conntlsclientserial-number) | `string` | Unique identifier for the certificate. |
| [`conn.tls.client.signature_algorithm`](#conntlsclientsignature-algorithm) | `string` | Algorithm used to sign the certificate. |
| [`conn.tls.client.subject`](#conntlsclientsubject) | `string` | The entity to whom the certificate is issued as a string roughly following the RFC 2253 Distinguished Names syntax. |
| [`conn.tls.client.subject.common_name`](#conntlsclientsubjectcommon-name) | `string` | Common name of the subject, usually the domain name. |
| [`conn.tls.client.subject.country`](#conntlsclientsubjectcountry) | `[]string` | Country names where the subject of the certificate is located. |
| [`conn.tls.client.subject.locality`](#conntlsclientsubjectlocality) | `[]string` | Locality or city where the subject is located. |
| [`conn.tls.client.subject.organization`](#conntlsclientsubjectorganization) | `[]string` | Name of the organization to which the subject belongs. |
| [`conn.tls.client.subject.organizational_unit`](#conntlsclientsubjectorganizational-unit) | `[]string` | Division of the organization to which the subject belongs. |
| [`conn.tls.client.subject.postal_code`](#conntlsclientsubjectpostal-code) | `[]string` | Postal code where the subject is located. |
| [`conn.tls.client.subject.province`](#conntlsclientsubjectprovince) | `[]string` | Province or state where the subject is located. |
| [`conn.tls.client.subject.street_address`](#conntlsclientsubjectstreet-address) | `[]string` | Street address where the subject is located. |
| [`conn.tls.client.validity.not_after`](#conntlsclientvaliditynot-after) | `timestamp` | Expiration date and time when the certificate is no longer valid. |
| [`conn.tls.client.validity.not_before`](#conntlsclientvaliditynot-before) | `timestamp` | Start date and time when the certificate becomes valid. |
### `conn.tls.client.extensions`
Additional information added to the certificate.
```yaml policy.yml theme={null}
expressions:
- "size(conn.tls.client.extensions) > 0"
```
```json policy.json theme={null}
{
"expressions": [
"size(conn.tls.client.extensions) > 0"
]
}
```
### `conn.tls.client.extensions[i].id`
The identifier (OID) that specifies the type of extension.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.extensions[0].id == '2.5.29.15'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.extensions[0].id == '2.5.29.15'"
]
}
```
### `conn.tls.client.extensions[i].critical`
True if the extension is critical.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.extensions[0].critical"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.extensions[0].critical"
]
}
```
### `conn.tls.client.extensions[i].value`
The data for the extension.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.extensions[0].value == b' '"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.extensions[0].value == b'\u0003\u0002\u0005 '"
]
}
```
### `conn.tls.client.issuer`
The issuing authority of the certificate as a string roughly following the RFC 2253 Distinguished Names syntax.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.issuer == 'CN=E1,O=Let's Encrypt,C=US'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.issuer == 'CN=E1,O=Let's Encrypt,C=US'"
]
}
```
### `conn.tls.client.issuer.common_name`
Common name of the issuing authority, usually the domain name.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.issuer.common_name == 'exampleca.com'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.issuer.common_name == 'exampleca.com'"
]
}
```
### `conn.tls.client.issuer.country`
Country names where the issuing authority is located.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.issuer.country == ['US']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.issuer.country == ['US']"
]
}
```
### `conn.tls.client.issuer.locality`
Locality or city of the issuing authority.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.issuer.locality == ['Mountain View']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.issuer.locality == ['Mountain View']"
]
}
```
### `conn.tls.client.issuer.organization`
Name of the organization that issued the certificate.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.issuer.organization == ['Example CA']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.issuer.organization == ['Example CA']"
]
}
```
### `conn.tls.client.issuer.organizational_unit`
Division of the organization responsible for the certificate.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.issuer.organizational_unit == ['Certification Authority Division']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.issuer.organizational_unit == ['Certification Authority Division']"
]
}
```
### `conn.tls.client.issuer.postal_code`
Postal code of the issuing authority.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.issuer.postal_code == ['94043']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.issuer.postal_code == ['94043']"
]
}
```
### `conn.tls.client.issuer.province`
Province or state of the issuing authority.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.issuer.province == ['California']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.issuer.province == ['California']"
]
}
```
### `conn.tls.client.issuer.street_address`
Street address of the issuing authority.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.issuer.street_address == ['1234 Encryption Way']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.issuer.street_address == ['1234 Encryption Way']"
]
}
```
### `conn.tls.client.pem`
Full PEM-encoded client certificate of the TLS connection, with `\n` used for newlines.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.pem.starts_with('-----BEGIN CERTIFICATE-----')"
- "conn.tls.client.pem.ends_with('-----END CERTIFICATE-----')"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.pem.starts_with('-----BEGIN CERTIFICATE-----')",
"conn.tls.client.pem.ends_with('-----END CERTIFICATE-----')"
]
}
```
### `conn.tls.client.san`
Subject alternative names of the client certificate.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.san == 'DNS:www.example.com, DNS:example.com, IP Address:192.168.1.1'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.san == 'DNS:www.example.com, DNS:example.com, IP Address:192.168.1.1'"
]
}
```
### `conn.tls.client.san.dns_names`
DNS names in the subject alternative names.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.san.dns_names == ['www.example.com', 'example.com']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.san.dns_names == ['www.example.com', 'example.com']"
]
}
```
### `conn.tls.client.san.email_addresses`
Email addresses in the subject alternative names.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.san.email_addresses == ['ngrok-email1@example.com', 'ngrok-email2@example.com']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.san.email_addresses == ['ngrok-email1@example.com', 'ngrok-email2@example.com']"
]
}
```
### `conn.tls.client.san.ip_addresses`
IP addresses in the subject alternative names.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.san.ip_addresses == ['192.168.1.1']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.san.ip_addresses == ['192.168.1.1']"
]
}
```
### `conn.tls.client.san.uris`
URIs in the subject alternative names.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.san.uris == ['https://example.com/example']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.san.uris == ['https://example.com/example']"
]
}
```
### `conn.tls.client.serial_number`
Unique identifier for the certificate.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.serial_number == 'b53017e79d4a5208b314a55d3574e0a8'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.serial_number == 'b53017e79d4a5208b314a55d3574e0a8'"
]
}
```
### `conn.tls.client.signature_algorithm`
Algorithm used to sign the certificate.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.signature_algorithm == 'SHA256-RSA'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.signature_algorithm == 'SHA256-RSA'"
]
}
```
### `conn.tls.client.subject`
The entity to whom the certificate is issued as a string roughly following the RFC 2253 Distinguished Names syntax.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.subject == 'CN=www.example.com'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.subject == 'CN=www.example.com'"
]
}
```
### `conn.tls.client.subject.common_name`
Common name of the subject, usually the domain name.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.subject.common_name == 'www.example.com'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.subject.common_name == 'www.example.com'"
]
}
```
### `conn.tls.client.subject.country`
Country names where the subject of the certificate is located.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.subject.country == ['US']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.subject.country == ['US']"
]
}
```
### `conn.tls.client.subject.locality`
Locality or city where the subject is located.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.subject.locality == ['Mountain View']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.subject.locality == ['Mountain View']"
]
}
```
### `conn.tls.client.subject.organization`
Name of the organization to which the subject belongs.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.subject.organization == ['Example Corp']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.subject.organization == ['Example Corp']"
]
}
```
### `conn.tls.client.subject.organizational_unit`
Division of the organization to which the subject belongs.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.subject.organizational_unit == ['Web Services']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.subject.organizational_unit == ['Web Services']"
]
}
```
### `conn.tls.client.subject.postal_code`
Postal code where the subject is located.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.subject.postal_code == ['94043']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.subject.postal_code == ['94043']"
]
}
```
### `conn.tls.client.subject.province`
Province or state where the subject is located.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.subject.province == ['California']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.subject.province == ['California']"
]
}
```
### `conn.tls.client.subject.street_address`
Street address where the subject is located.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.subject.street_address == ['1234 Secure Blvd']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.subject.street_address == ['1234 Secure Blvd']"
]
}
```
### `conn.tls.client.validity.not_after`
Expiration date and time when the certificate is no longer valid.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.validity.not_after == timestamp('2023-01-01T00:00:00Z')"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.validity.not_after == timestamp('2023-01-01T00:00:00Z')"
]
}
```
### `conn.tls.client.validity.not_before`
Start date and time when the certificate becomes valid.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.client.validity.not_before == timestamp('2020-01-01T00:00:00Z')"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.client.validity.not_before == timestamp('2020-01-01T00:00:00Z')"
]
}
```
## Connection TLS Server Variables
The following variables are available under the `conn.tls.server` namespace:
| Name | Type | Description |
| - | - | - |
| [`conn.tls.server.extensions`](#conntlsserverextensions) | `[]Extension` | Additional information added to the certificate. |
| [`conn.tls.server.extensions[i].id`](#conntlsserverextensionsiid) | `string` | The identifier that specifies the type of extension. |
| [`conn.tls.server.extensions[i].critical`](#conntlsserverextensionsicritical) | `bool` | True if the extension is critical. |
| [`conn.tls.server.extensions[i].value`](#conntlsserverextensionsivalue) | `[]byte` | The data for the extension. |
| [`conn.tls.server.issuer`](#conntlsserverissuer) | `string` | The issuing authority of the certificate as a string roughly following the RFC 2253 Distinguished Names syntax. |
| [`conn.tls.server.issuer.common_name`](#conntlsserverissuercommon-name) | `string` | Common name of the issuing authority, usually the domain name. |
| [`conn.tls.server.issuer.country`](#conntlsserverissuercountry) | `[]string` | Country names where the issuing authority is located. |
| [`conn.tls.server.issuer.locality`](#conntlsserverissuerlocality) | `[]string` | Locality or city of the issuing authority. |
| [`conn.tls.server.issuer.organization`](#conntlsserverissuerorganization) | `[]string` | Name of the organization that issued the certificate. |
| [`conn.tls.server.issuer.organizational_unit`](#conntlsserverissuerorganizational-unit) | `[]string` | Division of the organization responsible for the certificate. |
| [`conn.tls.server.issuer.postal_code`](#conntlsserverissuerpostal-code) | `[]string` | Postal code of the issuing authority. |
| [`conn.tls.server.issuer.province`](#conntlsserverissuerprovince) | `[]string` | Province or state of the issuing authority. |
| [`conn.tls.server.issuer.street_address`](#conntlsserverissuerstreet-address) | `[]string` | Street address of the issuing authority. |
| [`conn.tls.server.san`](#conntlsserversan) | `string` | Subject alternative names of the ngrok server's leaf TLS certificate. |
| [`conn.tls.server.san.dns_names`](#conntlsserversandns-names) | `[]string` | DNS names in the subject alternative names of the ngrok server's leaf TLS certificate. |
| [`conn.tls.server.san.email_addresses`](#conntlsserversanemail-addresses) | `[]string` | Email addresses in the subject alternative names of the ngrok server's leaf TLS certificate. |
| [`conn.tls.server.san.ip_addresses`](#conntlsserversanip-addresses) | `[]string` | IP addresses in the subject alternative names of the ngrok server's leaf TLS certificate. |
| [`conn.tls.server.san.uris`](#conntlsserversanuris) | `[]string` | URIs in the subject alternative names of the ngrok server's leaf TLS certificate. |
| [`conn.tls.server.serial_number`](#conntlsserverserial-number) | `string` | Unique identifier for the certificate. |
| [`conn.tls.server.signature_algorithm`](#conntlsserversignature-algorithm) | `string` | Algorithm used to sign the certificate. |
| [`conn.tls.server.subject`](#conntlsserversubject) | `string` | The entity to whom the certificate is issued as a string roughly following the RFC 2253 Distinguished Names syntax. |
| [`conn.tls.server.subject.common_name`](#conntlsserversubjectcommon-name) | `string` | Common name of the subject, usually the domain name. |
| [`conn.tls.server.subject.country`](#conntlsserversubjectcountry) | `[]string` | Country names where the subject of the certificate is located. |
| [`conn.tls.server.subject.locality`](#conntlsserversubjectlocality) | `[]string` | Locality or city where the subject is located. |
| [`conn.tls.server.subject.organization`](#conntlsserversubjectorganization) | `[]string` | Name of the organization to which the subject belongs. |
| [`conn.tls.server.subject.organizational_unit`](#conntlsserversubjectorganizational-unit) | `[]string` | Division of the organization to which the subject belongs. |
| [`conn.tls.server.subject.postal_code`](#conntlsserversubjectpostal-code) | `[]string` | Postal code where the subject is located. |
| [`conn.tls.server.subject.province`](#conntlsserversubjectprovince) | `[]string` | Province or state where the subject is located. |
| [`conn.tls.server.subject.street_address`](#conntlsserversubjectstreet-address) | `[]string` | Street address where the subject is located. |
| [`conn.tls.server.validity.not_after`](#conntlsservervaliditynot-after) | `timestamp` | Expiration date and time when the certificate is no longer valid. |
| [`conn.tls.server.validity.not_before`](#conntlsservervaliditynot-before) | `timestamp` | Start date and time when the certificate becomes valid. |
### `conn.tls.server.extensions`
Additional information added to the certificate.
```yaml policy.yml theme={null}
expressions:
- "size(conn.tls.server.extensions) > 0"
```
```json policy.json theme={null}
{
"expressions": [
"size(conn.tls.server.extensions) > 0"
]
}
```
### `conn.tls.server.extensions[i].id`
The identifier that specifies the type of extension.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.extensions[0].id == '2.5.29.15'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.extensions[0].id == '2.5.29.15'"
]
}
```
### `conn.tls.server.extensions[i].critical`
True if the extension is critical.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.extensions[0].critical"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.extensions[0].critical"
]
}
```
### `conn.tls.server.extensions[i].value`
The data for the extension.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.extensions[0].value == b' '"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.extensions[0].value == b'\u0003\u0002\u0005 '"
]
}
```
### `conn.tls.server.issuer`
The issuing authority of the certificate as a string roughly following the RFC 2253 Distinguished Names syntax.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.issuer == 'CN=E1,O=Let's Encrypt,C=US'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.issuer == 'CN=E1,O=Let's Encrypt,C=US'"
]
}
```
### `conn.tls.server.issuer.common_name`
Common name of the issuing authority, usually the domain name.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.issuer.common_name == 'exampleca.com'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.issuer.common_name == 'exampleca.com'"
]
}
```
### `conn.tls.server.issuer.country`
Country names where the issuing authority is located.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.issuer.country == ['US']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.issuer.country == ['US']"
]
}
```
### `conn.tls.server.issuer.locality`
Locality or city of the issuing authority.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.issuer.locality == ['Mountain View']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.issuer.locality == ['Mountain View']"
]
}
```
### `conn.tls.server.issuer.organization`
Name of the organization that issued the certificate.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.issuer.organization == ['Example CA']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.issuer.organization == ['Example CA']"
]
}
```
### `conn.tls.server.issuer.organizational_unit`
Division of the organization responsible for the certificate.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.issuer.organizational_unit == ['Certification Authority Division']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.issuer.organizational_unit == ['Certification Authority Division']"
]
}
```
### `conn.tls.server.issuer.postal_code`
Postal code of the issuing authority.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.issuer.postal_code == ['94043']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.issuer.postal_code == ['94043']"
]
}
```
### `conn.tls.server.issuer.province`
Province or state of the issuing authority.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.issuer.province == ['California']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.issuer.province == ['California']"
]
}
```
### `conn.tls.server.issuer.street_address`
Street address of the issuing authority.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.issuer.street_address == ['1234 Encryption Way']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.issuer.street_address == ['1234 Encryption Way']"
]
}
```
### `conn.tls.server.san`
Subject alternative names of the server certificate of the ngrok server's leaf TLS certificate.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.san == 'DNS:www.example.com, DNS:example.com, IP Address:192.168.1.1'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.san == 'DNS:www.example.com, DNS:example.com, IP Address:192.168.1.1'"
]
}
```
### `conn.tls.server.san.dns_names`
DNS names in the subject alternative names of the ngrok server's leaf TLS certificate.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.san.dns_names == ['ngrok-dns.com', 'ngrok-dns2.com']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.san.dns_names == ['ngrok-dns.com', 'ngrok-dns2.com']"
]
}
```
### `conn.tls.server.san.email_addresses`
Email addresses in the subject alternative names of the ngrok server's leaf TLS certificate.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.san.email_addresses == ['ngrok-email1@example.com', 'ngrok-email2@example.com']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.san.email_addresses == ['ngrok-email1@example.com', 'ngrok-email2@example.com']"
]
}
```
### `conn.tls.server.san.ip_addresses`
IP addresses in the subject alternative names of the ngrok server's leaf TLS certificate.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.san.ip_addresses == ['192.168.1.1']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.san.ip_addresses == ['192.168.1.1']"
]
}
```
### `conn.tls.server.san.uris`
URIs in the subject alternative names of the ngrok server's leaf TLS certificate.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.san.uris == ['https://example.com/example']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.san.uris == ['https://example.com/example']"
]
}
```
### `conn.tls.server.serial_number`
Unique identifier for the certificate.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.serial_number == 'b53017e79d4a5208b314a55d3574e0a8'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.serial_number == 'b53017e79d4a5208b314a55d3574e0a8'"
]
}
```
### `conn.tls.server.signature_algorithm`
Algorithm used to sign the certificate.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.signature_algorithm == 'SHA256-RSA'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.signature_algorithm == 'SHA256-RSA'"
]
}
```
### `conn.tls.server.subject`
The entity to whom the certificate is issued as a string roughly following the RFC 2253 Distinguished Names syntax.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.subject == 'CN=www.example.com'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.subject == 'CN=www.example.com'"
]
}
```
### `conn.tls.server.subject.common_name`
Common name of the subject, usually the domain name.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.subject.common_name == 'ngrok-server.example.com'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.subject.common_name == 'ngrok-server.example.com'"
]
}
```
### `conn.tls.server.subject.country`
Country names where the subject of the certificate is located.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.subject.country == ['US']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.subject.country == ['US']"
]
}
```
### `conn.tls.server.subject.locality`
Locality or city where the subject is located.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.subject.locality == ['Mountain View']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.subject.locality == ['Mountain View']"
]
}
```
### `conn.tls.server.subject.organization`
Name of the organization to which the subject belongs.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.subject.organization == ['Example Corp']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.subject.organization == ['Example Corp']"
]
}
```
### `conn.tls.server.subject.organizational_unit`
Division of the organization to which the subject belongs.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.subject.organizational_unit == ['Web Services']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.subject.organizational_unit == ['Web Services']"
]
}
```
### `conn.tls.server.subject.postal_code`
Postal code where the subject is located.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.subject.postal_code == ['94043']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.subject.postal_code == ['94043']"
]
}
```
### `conn.tls.server.subject.province`
Province or state where the subject is located.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.subject.province == ['California']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.subject.province == ['California']"
]
}
```
### `conn.tls.server.subject.street_address`
Street address where the subject is located.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.subject.street_address == ['1234 Secure Blvd']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.subject.street_address == ['1234 Secure Blvd']"
]
}
```
### `conn.tls.server.validity.not_after`
Expiration date and time when the certificate is no longer valid.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.validity.not_after > timestamp('2023-01-01T00:00:00Z')"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.validity.not_after > timestamp('2023-01-01T00:00:00Z')"
]
}
```
### `conn.tls.server.validity.not_before`
Start date and time when the certificate becomes valid.
```yaml policy.yml theme={null}
expressions:
- "conn.tls.server.validity.not_before < timestamp('2020-01-01T00:00:00Z')"
```
```json policy.json theme={null}
{
"expressions": [
"conn.tls.server.validity.not_before < timestamp('2020-01-01T00:00:00Z')"
]
}
```
## Connection Kubernetes Pod Variables
The following variables are available under the `conn.k8s.pod` namespace. They are populated on connections to endpoints with a `kubernetes` binding. They are not available on public or internal endpoints.
If pod identity cannot be resolved, the metadata variables will not be set and `conn.k8s.pod.metadata.error_code` will be populated instead. See [`conn.k8s.pod.metadata.error_code`](#connk8spoderror-code) for details.
| Name | Type | Description |
| - | - | - |
| [`conn.k8s.pod.id`](#connk8spodid) | `string` | The unique identifier (UID) of the originating pod. |
| [`conn.k8s.pod.metadata.name`](#connk8spodname) | `string` | The name of the originating pod. |
| [`conn.k8s.pod.metadata.namespace`](#connk8spodnamespace) | `string` | The namespace the originating pod belongs to. |
| [`conn.k8s.pod.metadata.annotations`](#connk8spodannotations) | `map(string, string)` | A map of pod annotations prefixed with `k8s.ngrok.com/`. |
| [`conn.k8s.pod.metadata.error_code`](#connk8spoderror-code) | `string` | An error code set when pod identity could not be resolved. |
| [`conn.k8s.pod.metadata.error_message`](#connk8spoderror-message) | `string` | A human-readable error message providing additional detail when `conn.k8s.pod.metadata.error_code` is set. |
### `conn.k8s.pod.id`
The unique identifier (UID) of the originating pod. Maximum size: 36 bytes.
```yaml policy.yml theme={null}
expressions:
- "conn.k8s.pod.id == '4b2c1a0e-7f3d-11ee-b962-0242ac120002'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.k8s.pod.id == '4b2c1a0e-7f3d-11ee-b962-0242ac120002'"
]
}
```
### `conn.k8s.pod.metadata.name`
The name of the originating pod. Maximum size: 255 bytes.
```yaml policy.yml theme={null}
expressions:
- "conn.k8s.pod.metadata.name in ['worker-a', 'worker-b']"
```
```json policy.json theme={null}
{
"expressions": [
"conn.k8s.pod.metadata.name in ['worker-a', 'worker-b']"
]
}
```
### `conn.k8s.pod.metadata.namespace`
The namespace the originating pod belongs to. Maximum size: 63 bytes.
```yaml policy.yml theme={null}
expressions:
- "conn.k8s.pod.metadata.namespace != 'payments'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.k8s.pod.metadata.namespace != 'payments'"
]
}
```
### `conn.k8s.pod.metadata.annotations`
A map of pod annotations prefixed with `k8s.ngrok.com/`. Only annotations with the `k8s.ngrok.com/` prefix are included. The combined size of all included annotations must not exceed 1024 bytes. If the limit is exceeded, `conn.k8s.pod.metadata.error_code` will be set to `ERR_NGROK_28000` and a truncated annotation map being returned.
```yaml policy.yml theme={null}
expressions:
- "conn.k8s.pod.metadata.annotations['k8s.ngrok.com/environment'] == 'production'"
```
```json policy.json theme={null}
{
"expressions": [
"conn.k8s.pod.metadata.annotations['k8s.ngrok.com/environment'] == 'production'"
]
}
```
### `conn.k8s.pod.metadata.error_code`
An error code set when pod identity could not be resolved. When this variable is set, the `conn.k8s.pod` metadata variables will not be populated.
| Error code | Description |
| - | - |
| `ERR_NGROK_28000` | The combined size of one or more pod identity variables exceeded the allowed limit. |
| `ERR_NGROK_28001` | Pod identity metadata could not be found for this connection. |
It is recommended to check this variable at the start of any policy that relies on pod identity. See [Restricting Access by Kubernetes Pod Identity](/docs/gateway/k8s/guides/how-to/pod-identity) for guidance on handling missing identity.
```yaml policy.yml theme={null}
expressions:
- "conn.k8s.pod.metadata.error_code == ''"
```
```json policy.json theme={null}
{
"expressions": [
"conn.k8s.pod.metadata.error_code == ''"
]
}
```
### `conn.k8s.pod.metadata.error_message`
A human-readable error message providing additional detail when `conn.k8s.pod.metadata.error_code` is set. Intended for troubleshooting and diagnostic purposes.
```yaml policy.yml theme={null}
expressions:
- "conn.k8s.pod.metadata.error_message != ''"
```
```json policy.json theme={null}
{
"expressions": [
"conn.k8s.pod.metadata.error_message != ''"
]
}
```