A host alias provides the publicly visible DNS name of the virtual host on the Router and optionally includes the port number. The combination of host alias name and port number for the virtual host must be unique for all virtual hosts in the Edge installation. That means multiple virtual hosts can use the same port number if they have different host aliases.
You must create a DNS entry and CNAME record that matches the host alias, and the host alias must match the string that the client passes in the Host header.
The port number in HostAliases is optional. If you specify the port as part of the host alias, you must also specify the same port by using the Port element. Or, you can specify two HostAliases elements, one with the port number and one without.
You can have multiple HostAlias definitions in the same virtual host definition, corresponding to multiple DNS entries for the virtual host, but not for multiple ports. If you want multiple ports, create multiple virtual host definitions with different ports.
You can include the * wildcard character in the host alias. The * wildcard character can only be at the start (preceding the first .) of the host alias, and cannot be mixed with other characters. For example *.example.com. The TLS cert for the virtual host must have a matching wildcard in the CN name of the cert. For example, *.example.com. Using a wildcard in a virtual host alias lets API proxies handle calls addressed to multiple subdomains such as alpha.example.com, beta.example.com, or live.example.com. Using a wildcard alias also helps you use fewer virtual hosts per environment to stay within product limits, since a virtual host with a wild card counts as only one virtual host.
For Cloud: If you have an existing virtual host that uses a port other than 443, you cannot add or remove a host alias.
For Private Cloud: If you are setting the host alias by using the IP addresses of your Routers, and not DNS entries, add a separate host alias for each Router, specifying the IP address of each Router and port of the virtual host.
interfaces
array
Edge for Private Cloud only.
List of network interfaces that you want the port to be bound to. If you omit this element, the port is bound on all interfaces.
listenOptions
array
Private Cloud 4.18.01 and later and for Edge Cloud by contacting Apigee Support.
If you use an ELB in TCP pass-thru mode to handle requests to the Edge Routers, the Router treats the IP address of the ELB as the client IP instead of the actual client IP. If the Router requires the true client IP, enable proxy_protocol on the ELB so that it passes the client IP in the TCP packet. On the Router, you must also set the listenOption on the virtual host to proxy_protocol. Because the ELB is in TCP pass-thru mode, you typically terminate TLS on the Router. Therefore, you usually only configure the virtual host to use proxy_protocol when you also configure it to use TLS.
The default value for listenOptions is an empty string. To later unset listenOptions, update the virtual host and omit the listenOptions property from the payload.
Port number used by the virtual host. Ensure that the port is open on the Edge Router.
If you specify a port in a hostAliases element, then the port number specified by port must match it.
For Cloud: You must specify port 443 when creating a virtual host. If omitted, by default the port is set to 443. If you have an existing virtual host that uses a port other than 443, you cannot change the port.
For Private Cloud releases 4.16.01 through 4.17.05: When creating a virtual host, you specify the Router port used by the virtual host. For example, port 9001. By default, the Router runs as the user apigee which does not have access to privileged ports, typically ports 1024 and below. If you want to create a virtual host that binds the Router to a protected port then you have to configure the Router to run as a user with access to those ports. See Setting up a virtual host for more.
For Private Cloud releases prior to 4.16.01: A Router can listen to only one HTTPS connection per virtual host, on a specific port, with the specified cert. Therefore, multiple virtual hosts cannot use the same port number if TLS termination occurs on the Router at the specified port.
baseUrl
string
Base URL that overrides the URL displayed by the Edge UI for an API proxy deployed to the virtual host. Useful when you have an external load balancer in front of the Edge Routers. See Configuring TLS access to an API for the Private Cloud for more.
The value of BaseUrl must include the protocol (that is, http:// or https://).
oCSPStapling
string
Flag that specifies whether the OCSP (Online Certificate Status Protocol) client is enabled. The OSCP sends a status request to an OCSP responder to determine if the TLS certificate is valid. The response indicates if the TLS certificate is valid and not revoked.
When enabled, OCSP stapling allows Edge, acting as the TLS server for one-way TLS, to query the OCSP responder directly and then cache the response. Edge then returns this response to the TLS client, or staples it, as part of TLS handshaking. See Enable OCSP Stapling on Your Server for more.
TLS must be enabled to enable OCSP stapling. Set to on to enable. Defaults to off.
retryOptions
array
Edge for Public Cloud and Edge for Private Cloud 4.18.01 and later.
Configuration that determines how the Router reacts for this virtual host when the Message Processor goes down.
You can specify multiple values. Valid values include:
off: Disables retry and the virtual host returns a failure code upon a request.
http_599(Default): If the Router receives an HTTP 599 response from the Message Processor, the Router forwards the request to the next Message Processor. HTTP 599 is a special response code that is generated by a Message Processor when it is being shut down. The Message Processor tries to complete all existing requests, but for any new requests it responds with HTTP 599 to signal to the Router to retry the request on the next Message Processor.
error: If an error occurred while establishing a connection with the Message Processor, passing a request to it, or reading the response header from it, the Router forwards the request to the next Message Processor.
timeout: If a timeout occurs while establishing a connection with the Message Processor, passing a request to it, or reading the response header from it, the Router forwards the request to the next Message Processor.
invalid_header: If the Message Processor returned an empty or invalid response, the Router forwards the request to the next Message Processor.
http_XXX: If the Message Processor returned a response with HTTP code XXX, the Router forwards the request to the next Message Processor.
If you specify multiple values, the Router uses a logical OR to combine them.
sSLInfo
object
SSL information.
useBuiltInFreeTrailCert
string
Edge for Public Cloud only.
Flag that specifies whether to use the Apigee freetrial cert and key. If you have a paid Edge for Cloud account and do not yet have a TLS cert and key, you can create a virtual host that uses the Apigee freetrial cert and key. That means you can create the virtual host without first creating a keystore.
The Apigee freetrial cert is defined for a domain of *.apigee.net. Therefore, the HostAlias of the virtual host must also be in the form *.apigee.net.
Flag that specifies whether to enable the capture of TLS connection information by Edge. This information will be made available as flow variables in an API proxy. See Accessing TLS connection information in an API proxy for more.
ClientProperties
string
Flag that specifies whether to enable the capture of client cert details captured by Edge in two-way TLS. This information will be made available as flow variables in an API proxy. See Accessing TLS connection information in an API proxy for more.
properties
object
Edge Cloud and for Private Cloud 4.17.01 and later.
List of properties.
Virtual hosts let multiple domain names connect to the same host. A virtual host on Edge defines the domains and ports on which an API proxy is exposed, and, by extension, the URL that apps use to access an API proxy. A virtual host also defines whether the API proxy is accessed by using the HTTP protocol, or by the encrypted HTTPS protocol.
The request body content used to create a virtual host depends on whether you are using Edge for the Cloud or Edge for the Private Cloud. If you are using Edge for the Private Cloud, then it also depends on which version of Edge for the Private Cloud you are using. For a complete list of all options for the request body, see Virtual host property reference.
For example, a subset of request body properties are valid only for specific Edge for Private Cloud versions, as follows:
ciphers and protocols properties are valid on Edge for Private Cloud version 4.15.07 and earlier
properties array is valid on Edge for Private Cloud version 4.17.01 and later
baseUrl property is valid on Edge for Private Cloud version 4.17.05 and later
retryOptions and listenOptions properties are valid on Edge for Private Cloud version 4.18.01 and later
Note: As of Edge for Private Cloud version 4.16.01, you must create a host alias when you create a virtual host. Also, the combination of host alias name and port number for the virtual host must be unique for all virtual hosts in the Edge installation.
For a general introduction to creating virtual hosts, see About virtual hosts. For information about your specific version of Edge, see:
When you create a new API proxy, Edge automatically configures its ProxyEndpoint to use all available virtual hosts. If you create a new API proxy that should not be accessible over a particular virtual host, then you must edit the API proxy to remove that virtual host from its ProxyEndpoint.
If you created any API proxies before requesting the virtual host, then you must edit the API proxy to add the new virtual hosts to its ProxyEndpoint. Otherwise, the API proxy is not accessible by the virtual host.
See Configuring an API proxy to use a virtual host.
Every environment has at least one virtual host that defines the HTTP settings for connection with the Apigee organization. All API proxies in an environment share the same virtual hosts. By default, two virtual hosts are available for each environment: default and secure.
You must specify the complete description of the virtual host in the request body, not just the elements that you want to change. You can get the current virtual host properties, as described in Get a virtual host.
The request body used to create a virtual host depends on whether you are using Edge for the Cloud or Edge for the Private Cloud. If you are using Edge for the Private Cloud, then it also depends on which version of Edge for the Private Cloud you are using. For a complete list of all options for the request body, see Virtual host property reference.
For example, a subset of request body properties are valid only for specific Edge for Private Cloud versions, as follows:
ciphers and protocols properties are valid on Edge for Private Cloud version 4.15.07 and earlier
properties array is valid on Edge for Private Cloud version 4.17.01 and later
baseUrl property is valid on Edge for Private Cloud version 4.17.05 and later
retryOptions and listenOptions properties are valid on Edge for Private Cloud version 4.18.01 and later
Note: As of Edge for Private Cloud version 4.16.01, you must create a host alias when you create a virtual host. Also, the combination of host alias name and port number for the virtual host must be unique for all virtual hosts in the Edge installation.
For a general introduction to creating virtual hosts, see About virtual hosts. For information about your specific version of Edge, see:
DEPRECATED: This API is being deprecated and will be removed in a future release.
Cloud customers can now create and update a virtual host, not just modify the TLS properties of the virtual host. Therefore, this API has been deprecated. Cloud customers can now use the following APIs with virtual hosts:
Update the TLS configuration properties for a virtual host for Edge in the Cloud. For example, enable one-way or two-way TLS or specify the keystore/truststore used by the virtual host.
Only paid Edge Cloud accounts can make modifications to the TLS configuration of virtual hosts. Edge trial accounts cannot modify the TLS configuration of virtual hosts. Trial accounts must upgrade to a paid account to enable this feature.