Set the Host header and path prefix for an origin

Choose the Host header a connector sends and the path it prepends, so the origin serves the right site and directory.

Last updated

View as Markdown Agent setup

You can set the Host header a connector sends to its origin, and a path it prepends to every request, from Azion Console, the Azion CLI, or the API. Both settings apply to a connector of type http. The examples use httpbin.org as the origin, because it answers with the request it received, so each setting shows in its response. Replace it with the host name of your origin.

Select the interface you use. The prerequisites and every task on this page follow that choice.

Prerequisites

  • A connector of type http, and a workload whose application points a rule at the connector with the Set Connector behavior. To create both, refer to Connectors quickstart.
  • The workload domain, or a domain of your own, that the workload answers on.
  • The Azion CLI, installed and authorized.
  • The ID of your connector.

Send the origin’s own host name

By default, host is ${host}, which sends the host the client requested. Keep the default for an origin that serves several virtual hosts and reads each request under its public name. Set a literal value when the origin answers only under its own name. The connector then sends that name for every request.

The CLI updates a connector from a file that carries the whole connector: its name, type, attributes.addresses, and the connection options you set. A file with connection_options alone fails with Failed to decode the given 'json' file. Copy your connector’s current values into the file, then change host.

To set the host name with the Azion CLI, save the connector as connector.json:

JSON
01{
02 "name": "my-connector",
03 "type": "http",
04 "attributes": {
05 "addresses": [{"address": "httpbin.org"}],
06 "connection_options": {"transport_policy": "force_https", "host": "httpbin.org"}
07 }
08}

Then update the connector from the file. Replace <connector-id> with the ID of your connector:

azion update connector --connector-id <connector-id> --type http --file connector.json
Updated Connector with ID <connector-id>

The connector now sends Host: httpbin.org to the origin.

To set the host name with the API, send a PATCH request with only the key you change. A PATCH merges it into the stored connector:

Shell
01curl --request PATCH \
02 --url https://api.azion.com/v4/workspace/connectors/<connector-id> \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data '{"attributes":{"connection_options":{"host":"httpbin.org"}}}'

The API answers 202 with "state": "pending" and the full connector. connection_options.host reads httpbin.org, and the other connection options keep their values. An empty host is refused with 400 and 10018 This field may not be blank.

To set the host name in Azion Console:

Open the connector

Access Azion Console > Connectors, then select your connector.

Enter the host name

In Host, enter httpbin.org.

Select Save

Azion Console shows Connector has been updated. The Console refuses a value that is not a host name, an IP address, or a variable, with Host must be a valid hostname, IP address, or variable.

To send the client’s host again, set the value back to ${host}.

Prepend a path

The path goes in front of the path the client requested, so the origin serves content from one of its directories. With /anything, a request for /get reaches the origin as /anything/get. With /secure, a request for https://<your-domain>/index.html reaches the origin as /secure/index.html. The prefix never appears in the client’s URL. The value starts with /, and the default is no prefix.

For a bucket of Object Storage, a connector of type storage carries its own prefix instead. For more information, refer to Connector settings.

To set the path with the Azion CLI, add path_prefix to the whole connector in connector.json:

JSON
01{
02 "name": "my-connector",
03 "type": "http",
04 "attributes": {
05 "addresses": [{"address": "httpbin.org"}],
06 "connection_options": {"transport_policy": "force_https", "host": "httpbin.org", "path_prefix": "/anything"}
07 }
08}

Then update the connector from the file:

azion update connector --connector-id <connector-id> --type http --file connector.json
Updated Connector with ID <connector-id>

To read the connection options back:

azion describe connector --connector-id <connector-id> --format json

The output carries the new path and the host name from the file:

Text
01 "connection_options": {
02 "dns_resolution": "both",
03 "following_redirect": false,
04 "host": "httpbin.org",
05 "http_version_policy": "http1_1",
06 "path_prefix": "/anything",
07 "real_ip_header": "X-Real-IP",
08 "real_port_header": "X-Real-PORT",
09 "transport_policy": "force_https"
10 },

path_prefix carries /anything, and host carries the name from the file.

To set the path with the API, send a PATCH request with path_prefix alone:

Shell
01curl --request PATCH \
02 --url https://api.azion.com/v4/workspace/connectors/<connector-id> \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data '{"attributes":{"connection_options":{"path_prefix":"/anything"}}}'

The API answers 202 with "state": "pending" and the full connector, where connection_options.path_prefix reads /anything. A value without the leading slash, such as anything, is refused with 400 and 28009 Invalid path format. Must be a valid path.

To set the path in Azion Console:

Open the connector

Access Azion Console > Connectors, then select your connector.

Enter the path

In Path, enter /anything.

Select Save

Azion Console shows Connector has been updated. A path without the leading slash is refused with Path must start with a forward slash (/).

Verify what the origin receives

A connector change needs no new deployment. It reaches traffic over several minutes, and each data center applies it at its own moment. For more information, refer to How Connectors works.

To see the request the origin received, send a request through your workload. Replace <workload-domain> with the workload domain or your own domain:

curl -s -D - https://<workload-domain>/get

httpbin.org answers with the request it received, as JSON. Two fields show the connector’s settings: headers.Host is the Host header, and url carries the path the origin received. With host at ${host} and the path prefix /anything, the response reads:

Text
01HTTP/2 200
02…
03server: gunicorn/19.9.0
04…
05 "headers": {
06 …
07 "Host": "<workload-domain>",
08 …
09 },
10 …
11 "url": "https://<workload-domain>/anything/get"
12}

url carries /anything/get, so the connector prepends the path prefix. headers.Host carries the workload domain, the host the client requested. With host at httpbin.org, headers.Host reads httpbin.org instead. Send the request several times: an answer with the previous values comes from a data center that has not applied the change yet.

Next steps

Connector settingsEvery connection option, its API field, its default, and its limits.How Connectors worksHow the Host header, the path prefix, and the protocol shape the request the origin receives.Sign origin requests with HMACServe a private bucket of an S3-compatible origin, with the bucket name as the path.Troubleshoot ConnectorsFix a connector whose origin refuses requests or answers with an error.