# Connector settings A [connector](/en/documentation/platform/connectors/) is the object that holds where and how an application reaches an origin, the server that holds your content. Its type, `http`, `storage`, or `live_ingest`, sets which settings the connector carries. Azion Console and the Azion API write the same object, so each table on this page names the Console label beside the API field. API fields are written as paths inside the request body, such as `attributes.connection_options.host`. --- ## Connector object The JSON body below is a complete connector of type `http` with one address, every connection option at its default except `transport_policy` and `host`, and [Load Balancer](/en/documentation/platform/connectors/#load-balancer) and [Origin Shield](/en/documentation/platform/connectors/#origin-shield) off: ```json { "name": "my-connector", "active": true, "type": "http", "attributes": { "addresses": [ { "address": "origin.example.com", "http_port": 80, "https_port": 443, "active": true } ], "connection_options": { "dns_resolution": "both", "transport_policy": "force_https", "http_version_policy": "http1_1", "host": "origin.example.com", "path_prefix": "", "following_redirect": false, "real_ip_header": "X-Real-IP", "real_port_header": "X-Real-PORT" }, "modules": { "load_balancer": { "enabled": false }, "origin_shield": { "enabled": false } } } } ``` The API path is `/v4/workspace/connectors`, and one connector is `/v4/workspace/connectors/{connector_id}`. A `POST` that creates a connector answers `202` with `"state": "pending"` and the full object, defaults included. A `PATCH` merges the keys you send into the stored object. A `PUT` replaces it: a `PUT` without `connection_options` resets every connection option to its default. For every operation, refer to the [Azion API](https://api.azion.com/). The Azion CLI takes the same JSON body from a file: `azion create connector --type http --file my-connector.json` prints `Created Connector with ID `. A change to a connector takes effect without a new deployment. It reaches Azion's distributed infrastructure in several minutes, and data centers apply it at different times. An application sends requests to a connector through a rule with the `Set Connector` behavior. To write that rule, refer to [Rules Engine for Applications](/en/documentation/platform/applications/rules-engine/). --- ## General The general fields name the connector and set its type. The API requires `name`, `type`, and `attributes` on every connector. | Console | API field | Type | Default | Description | | ------------------------------------------------------------------------------ | --------- | ------- | ------- | ------------------------------------------------------------------------------------ | | **Name** | `name` | string | none | Required. 1 to 255 characters. | | **Connector Type**, with the cards *HTTP*, *Object Storage*, and *Live Ingest* | `type` | enum | none | Required. `http`, `storage`, or `live_ingest`. Sets which fields `attributes` takes. | | none | `active` | boolean | `true` | `true` or `false`. | A connector of type `http` takes the fields in Addresses, Connection options, Load Balancer, and Origin Shield. A connector of type `storage` takes the fields in Storage, and a connector of type `live_ingest` takes the field in Live Ingest. --- ## Addresses The addresses of a connector of type `http` are the origin servers it connects to. Each item of `attributes.addresses` holds one address with its ports, its state, and its role in load balancing. The Console section **Address Management** writes them. | Console | API field | Type | Default | Description | | -------------------------------------------- | ---------------------------------------------------------- | ------- | --------- | -------------------------------------------------------------------------------------------------------------- | | **Address** | `attributes.addresses[].address` | string | none | Required. An IPv4 address, an IPv6 address, or a hostname, up to 255 characters, with no protocol and no port. | | **HTTP Port** | `attributes.addresses[].http_port` | integer | `80` | 1 to 65535. The port for HTTP connections to this address. | | **HTTPS Port** | `attributes.addresses[].https_port` | integer | `443` | 1 to 65535. The port for HTTPS connections to this address. | | **Active** | `attributes.addresses[].active` | boolean | `true` | `false` takes the address out of rotation. | | **Server Role**, with *Primary* and *Backup* | `attributes.addresses[].modules.load_balancer.server_role` | enum | `primary` | `primary` or `backup`. The role of the address in load balancing. | | **Weight** | `attributes.addresses[].modules.load_balancer.weight` | integer | `1` | 1 to 100. Higher weights allocate more traffic to this address. | A connector holds one address unless Load Balancer is on. Two addresses with Load Balancer off are refused with `28004`. With Load Balancer on, a connector holds up to 15 addresses, and a 16th is refused with `28011`. For every bound in one place, refer to [Connectors limits](/en/documentation/platform/connectors/limits/). An address with a protocol or a port, such as `https://origin.example.com` or `origin.example.com:443`, is refused with `28001`. The Console shows `Address must be a valid IPv4, IPv6, or hostname, without protocol or port.` Set the ports in **HTTP Port** and **HTTPS Port**, and a path in `path_prefix`. An address reads back `"modules": null` until you send its Load Balancer fields. An address sent with only `weight` reads back `server_role` as `primary`, and one sent with only `server_role` reads back `weight` as `1`. A `backup` address is refused under the *IP Hash* method with `28005`. The Console shows `Backup role is not available when the load balancing method is IP Hash.` and `Backup role is not supported with IP Hash. Change this address to Primary or select another method.` A weight outside the range shows `Weight must be between 1 and 100` in the Console. --- ## Connection options The connection options of a connector of type `http` set how the connector talks to its addresses: the `Host` header, the path, the protocol, the IP version, and the headers that carry the client's address. They sit in `attributes.connection_options`. | Console | API field | Type | Default | Description | | ------------------------------------------------------------------------------- | --------------------------------------------------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Host** | `attributes.connection_options.host` | string | `${host}` | 1 to 255 characters. The `Host` header sent to the origin. `${host}` sends the host the client requested, and a literal value is sent as is. An empty value is refused with `10018`. | | **Path** | `attributes.connection_options.path_prefix` | string | `""`, no prefix | Up to 255 characters, starting with `/`. Prepended to the request path. A value without the leading slash is refused with `28009`. | | **Transport Protocol Policy**, with *Preserve*, *Force HTTPS*, and *Force HTTP* | `attributes.connection_options.transport_policy` | enum | `preserve` | `preserve` keeps the scheme the client used. `force_https` connects to the origin over HTTPS only, and `force_http` over HTTP only. | | **DNS Resolution Policy**, with *IPv4 and IPv6* and *Force IPv4* | `attributes.connection_options.dns_resolution` | enum | `both` | `both` connects over IPv4 or IPv6. `force_ipv4` connects over IPv4 only. | | none | `attributes.connection_options.http_version_policy` | enum | `http1_1` | The HTTP version to the origin. `http1_1`, HTTP/1.1, is the only value. | | **Following Redirect** | `attributes.connection_options.following_redirect` | boolean | `false` | `true` follows the HTTP redirects the origin returns. | | **Real IP Header** | `attributes.connection_options.real_ip_header` | string | `X-Real-IP` | 1 to 100 characters. The name of the header that carries the client IP address to the origin. | | **Real Port Header** | `attributes.connection_options.real_port_header` | string | `X-Real-PORT` | 1 to 100 characters. The name of the header that carries the client port to the origin. | The `host` value decides which name the origin sees. For example, with the default `${host}`, a client that requests `www.example.com` makes the connector send `Host: www.example.com`. With `"host": "origin.example.com"`, the connector sends `Host: origin.example.com` for every request. An origin that routes requests by name may not answer to the client's host, so send the origin's own name as a literal value. The Console validates **Host** with `Host must be a valid hostname, IP address, or variable.` The `path_prefix` value goes in front of the path the client requested. With `/anything`, a request for `/get` reaches the origin as `/anything/get`. For **Path**, the Console reads "Use '/' for the root path." and validates the field with `Path must start with a forward slash (/)`. By default, the origin receives the client IP address in `X-Real-IP` and the client port in `X-Real-PORT`. Renaming `real_ip_header` changes the header name: with `X-Client-Real-IP`, the origin receives `X-Client-Real-IP` and no `X-Real-IP`. Some origins drop `X-Real-IP` themselves. To add the client IP to a header with a rule instead, refer to [Send the client IP to the origin in a header](/en/documentation/support/original-ip-header/). --- ## Load Balancer Load Balancer distributes requests across the addresses of a connector of type `http`. In the Console, the **Load Balancer** switch in the **Modules** section turns it on, and the **Method**, **Max Retries**, **Connection Timeout**, and **Read/Write Timeout** fields appear. In the API, the fields sit in `attributes.modules.load_balancer`. | Console | API field | Type | Default | Description | | ------------------------------------------------------------------ | ------------------------------------------------------------ | ---------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | **Load Balancer** | `attributes.modules.load_balancer.enabled` | boolean | `false` | `true` enables Load Balancer on the connector and allows up to 15 addresses. | | **Method**, with *Round Robin*, *Least Connections*, and *IP Hash* | `attributes.modules.load_balancer.config.method` | enum | `round_robin` | `round_robin`, `least_conn`, or `ip_hash`. `ip_hash` refuses `backup` addresses. | | **Max Retries** | `attributes.modules.load_balancer.config.max_retries` | integer | `0` in the API, `3` in the Console | 0 to 20. The number of retry attempts on a connection failure. | | **Connection Timeout** | `attributes.modules.load_balancer.config.connection_timeout` | integer, seconds | `60` seconds in the API, `30` seconds in the Console | 1 to 300 seconds. The maximum time to wait for the connection to the origin. | | **Read/Write Timeout** | `attributes.modules.load_balancer.config.read_write_timeout` | integer, seconds | `120` seconds in the API, `60` seconds in the Console | 1 to 600 seconds. The maximum time to wait for data to be read or written on the open connection to the origin. | With `enabled` set to `true`, `config` must carry at least one key, or the API refuses the request with `28014`. A key you leave out takes the API default. For example, `"config": {"method": "round_robin"}` reads back with `max_retries` `0`, `connection_timeout` `60`, and `read_write_timeout` `120`. When you turn on **Load Balancer** in the Console, the form fills in *Round Robin*, `3`, `30`, and `60` instead. The retries and the two timeouts exist only with Load Balancer on. A connector without Load Balancer has no configurable timeout. For the timeouts that apply then, refer to [How Connectors works](/en/documentation/platform/connectors/how-it-works/). For how each method chooses an address, refer to [Balancing methods](/en/documentation/platform/connectors/load-balancer/balancing-methods/). --- ## Origin Shield Origin Shield protects the origin of a connector of type `http` in two ways. Origin IP ACL lets your origin accept only Azion's published addresses, and HMAC signs each request the connector sends to the origin. In the API, the fields sit in `attributes.modules.origin_shield`. | Console | API field | Type | Default | Description | | ------------------- | --------------------------------------------------------------------------- | ------- | ------------------ | ---------------------------------------------------------------------------------- | | **Origin Shield** | `attributes.modules.origin_shield.enabled` | boolean | `false` | `true` enables Origin Shield on the connector. | | **Origin IP ACL** | `attributes.modules.origin_shield.config.origin_ip_acl.enabled` | boolean | `false` | `true` turns on Origin IP ACL. | | **HMAC** | `attributes.modules.origin_shield.config.hmac.enabled` | boolean | `false` | `true` signs each request to the origin with the credentials below. | | **Type**, read-only | `attributes.modules.origin_shield.config.hmac.config.type` | enum | `aws4_hmac_sha256` | The signing scheme. | | **Region** | `attributes.modules.origin_shield.config.hmac.config.attributes.region` | string | none | Required. 1 to 255 characters. A region that the object storage provider supports. | | **Service** | `attributes.modules.origin_shield.config.hmac.config.attributes.service` | string | `s3` | 1 to 255 characters. Required in the Console. | | **Access Key** | `attributes.modules.origin_shield.config.hmac.config.attributes.access_key` | string | none | Required. 1 to 255 characters. | | **Secret Key** | `attributes.modules.origin_shield.config.hmac.config.attributes.secret_key` | string | none | Required. 1 to 255 characters. The Console renders it as a password field. | With `enabled` set to `true`, `config` must carry at least one key, and with `hmac.enabled` set to `true`, `hmac.config` must be present. Otherwise the API refuses the request with `28014`. Turning HMAC off removes the stored credentials, so you enter them again when you turn it back on. The HMAC credentials belong to an account at the object storage provider that holds the private content. For example, a connector that reads a private bucket through the S3 endpoint `s3.us-east-005.azionstorage.net` sends `region` `us-east-005`, `service` `s3`, and a credential scoped to that bucket. With HMAC off, that endpoint answers `401`. For how Origin IP ACL and HMAC protect the origin, refer to [Origin IP ACL and HMAC](/en/documentation/platform/connectors/origin-shield/origin-ip-acl-and-hmac/). --- ## Storage A connector of type `storage` reads from an [Object Storage bucket](/en/documentation/platform/object-storage/buckets-and-objects/) in your account. It carries two attributes and no addresses or connection options. | Console | API field | Type | Default | Description | | ----------------------------------------------------------------------------- | ------------------- | ------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Bucket selector, *Select a Bucket*, with the **Create Object Storage** button | `attributes.bucket` | string | none | Required. Up to 255 characters. The name of an existing bucket. A bucket that does not exist is refused with `28007`. | | **Prefix** | `attributes.prefix` | string | `null` when omitted | Optional in the API, required in the Console. 1 to 255 characters, such as `images/`. Filters the objects within the bucket. An empty string is refused with `10018`. | The bucket selector lists the buckets of your account, and **Create Object Storage** creates a bucket without leaving the form. In the API, leave `prefix` out to store `null`, and never send it empty. For example, this body creates a connector of type `storage` for the objects under `images/`: ```json { "name": "my-connector", "type": "storage", "attributes": { "bucket": "my-bucket", "prefix": "images/" } } ``` --- ## Live Ingest A connector of type `live_ingest` belongs to [Live Ingest](/en/documentation/platform/connectors/#live-ingest). It carries one attribute, `region`, and no addresses or connection options. | Console | API field | Type | Default | Description | | ---------- | ------------------- | ---- | ------- | ----------------------------------------------------------------------------- | | **Region** | `attributes.region` | enum | none | Required. `us-east-1`, `us-east-2`, `br-east-1`, `br-east-2`, or `br-east-3`. | A request without `region` is refused with `10059`, and a value outside the list with `10039`. A `bucket` sent with this type is accepted and not stored. For example, this body creates a connector of type `live_ingest` in `br-east-1`: ```json { "name": "my-connector", "type": "live_ingest", "attributes": { "region": "br-east-1" } } ``` For how Live Ingest works, refer to [Ingestion and delivery](/en/documentation/platform/connectors/live-ingest/ingestion-and-delivery/). --- ## Errors The API refuses each request below with HTTP `400` and creates or changes nothing. The code and the message are in the response's `errors` array, with a `source.pointer` to the field. | Code | Message | Cause | What to do | | ------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `28001` | `Invalid address format. Must be a valid IPv4, IPv6, or CNAME.` | An address carries a protocol or a port, such as `https://origin.example.com` or `origin.example.com:443`. | Send the hostname or IP address alone, and set the ports in `http_port` and `https_port`. | | `28004` | `To use more than one address, you must enable the Load Balancer module.` | The connector has two or more addresses and Load Balancer is off, on create or when you turn Load Balancer off. | Enable Load Balancer on the connector, or keep one address. | | `28011` | `When the Load Balancer module is enabled, you can use up to 15 addresses.` | The connector has 16 or more addresses. | Keep 15 addresses or fewer. | | `28005` | `Backup addresses are not allowed when using 'ip_hash' as load balance method.` | An address has `server_role` `backup` and the method is `ip_hash`. | Set the address to `primary`, or choose `round_robin` or `least_conn`. | | `28014` | `Module configuration must be provided when 'enabled' is true.` | Load Balancer or Origin Shield has `enabled` `true` with no `config`, an empty one, or `null`; or HMAC is on without `hmac.config`. | Send `config` with at least one key, or `hmac.config` with the credentials. | | `28009` | `Invalid path format. Must be a valid path.` | `path_prefix` does not start with `/`. | Start the value with `/`, such as `/anything`. | | `28007` | `Invalid bucket name Storage Connector.` | `bucket` names a bucket that does not exist in the account. | Create the bucket first, or send the name of an existing one. | | `28000` | `Cannot delete an Connector referenced by another resource. References: EdgeApplicationRuleEngine - id: ` | A `DELETE` targets a connector that a rule still points at; the message names the rule. | Point the rule at another connector, or delete the rule, then repeat the `DELETE`. | | `10018` | `This field may not be blank.` | `host` or `prefix` is an empty string. | Send a value, or leave `prefix` out. | | `10059` | `This field is required.` | A connector of type `live_ingest` has no `region`. | Send `region` with one of the five values. | | `10039` | `"preserve" is not a valid choice.` | An enum field holds a value outside its list; the message quotes the value, such as `"http2"` for `http_version_policy` or `"eu-west-1"` for `region`. | Send a value from the field's list. | | `10050` | `Ensure this value is greater than or equal to 1.` | `weight` is `0`. | Send a weight from 1 to 100. | | `10068` | `Ensure this value is less than or equal to 100.` | A number is above its maximum; the message names it: `100` for `weight`, `20` for `max_retries`, `300` for `connection_timeout`, `600` for `read_write_timeout`. | Send a value inside the field's range. | | `10046` | `Ensure this field has no more than 255 characters.` | `name` is longer than 255 characters. | Shorten the name to 255 characters or fewer. | The Azion CLI prints the same message inside its own error. For `28000`, that is `Error: Failed to delete the Connector: [...]`. --- ## Related resources - [How Connectors works](/en/documentation/platform/connectors/how-it-works.md): The path a request follows from a rule to the connector and its origin, and the timeouts that apply without Load Balancer. - [Connectors limits](/en/documentation/platform/connectors/limits.md): Every bound on a connector and its addresses, with what happens past each one. - [Balancing methods](/en/documentation/platform/connectors/load-balancer/balancing-methods.md): How Round Robin, Least Connections, and IP Hash choose an address, and how weight and server role change the choice. - [Rules Engine for Applications](/en/documentation/platform/applications/rules-engine.md): The Set Connector behavior that sends an application's requests to a connector.