Virtual host property reference

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation.
info

Virtual host representation

The XML object that you use to define a virtual host is based on your version of Edge: Cloud or Private Cloud.

If you are a Private Cloud customer, then you must ensure that you use the correct XML for your version of Edge.

Cloud and Private Cloud 4.17.01 and later

<VirtualHost name="vhostName">
    <Port>portNumber</Port>
    <BaseUrl>http://myCo.com</BaseUrl>
    <OCSPStapling>offOn</OCSPStapling>
    <HostAliases>
        <HostAlias>hostAlias</HostAlias>
    </HostAliases>
    <Interfaces>
        <!-- Private Cloud only -->
        <Interface>interfaceName</Interface>
    </Interfaces>
    <RetryOptions>
        <RetryOption>option</RetryOption>
    </RetryOptions>
    <ListenOptions>
        <ListenOption>option</ListenOption>
    </ListenOptions>
    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
        <IgnoreValidationErrors>trueFalse</IgnoreValidationErrors>
    </SSLInfo>
    <!-- UseBuiltInFreeTrialCert is for Edge Cloud only -->
    <UseBuiltInFreeTrialCert>trueFalse</UseBuiltInFreeTrialCert>
    <PropagateTLSInformation>
        <!-- PropagateTLSInformation is Alpha in the Cloud only -->
        <ConnectionProperties>trueFalse</ConnectionProperties>
        <ClientProperties>trueFalse</ClientProperties>
    </PropagateTLSInformation>
    <Properties>
        <Property name="proxy_read_timeout">timeout</Property>
        <Property name="keepalive_timeout">timeout</Property>
        <Property name="proxy_request_buffering">onOff</Property>
        <Property name="proxy_buffering">onOff</Property>
        <!-- ssl_protocols is Private Cloud only -->
        <Property name="ssl_protocols">protocolList</Property>
        <Property name="ssl_ciphers">cipherList</Property>
    </Properties>
</VirtualHost>

Private Cloud 4.16.01 through 4.16.09

<VirtualHost name="vhostName">
    <Port>portNumber</Port>
    <HostAliases>
        <HostAlias>hostAlias</HostAlias>
    </HostAliases>
    <Interfaces>
        <Interface>interfaceName</Interface>
    </Interfaces>
    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
        <IgnoreValidationErrors>trueFalse</IgnoreValidationErrors>
    </SSLInfo>
</VirtualHost>

Private Cloud 4.15.07 and earlier

<VirtualHost name="vhostName">
    <Port>portNumber</Port>
    <HostAliases>
        <HostAlias>hostAlias</HostAlias>
    </HostAliases>
    <Interfaces>
        <Interface>interfaceName</Interface>
    </Interfaces>
    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>keystore</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>truststore</TrustStore>
        <IgnoreValidationErrors>trueFalse</IgnoreValidationErrors>
        <Ciphers>
             <Cipher>cipher</Cipher>
             <Cipher>cipher</Cipher>
         </Ciphers>
         <Protocols>
             <Protocol>protocol</Protocol>
             <Protocol>protocol</Protocol>
         </Protocols>
    </SSLInfo>
</VirtualHost>

Virtual host configuration properties

The following table lists the properties that you use to configure a virtual host:

Properties Description Default Required
VirtualHost

Specifies the name of the virtual host. You use that name to reference the virtual host when configuring an API proxy.

The characters that you can use in the name attribute are restricted to: A-Z0-9._\-$%.

None Yes
Port

Specifies the port number used by the virtual host. Ensure that the port is open on the Edge Router.

If you specify a port in a hostalias 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.

None Yes
BaseUrl 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 (i.e., "http://" or "https://").

None No
OCSPStapling

An OCSP (Online Certificate Status Protocol) client 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. The default value is off.

off No
HostAliases
HostAlias

The publicly visible DNS name of the virtual host on the Router, optionally including 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 HostAlias 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 HostAlias 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 wildcard 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.

None Yes
Interfaces Available for Edge for Private Cloud only.
Interface

Specifies the network interfaces that you want port to be bound to. If you omit this element, the port is bound on all interfaces.

For example, to specify to bind the port only to en0:

<Interfaces>
  <Interface>en0</Interface>
</Interfaces>

Determine the interfaces available on your system by running the "ifconfig -a" command.

None All interfaces
RetryOptions Available for Edge Cloud and for Private Cloud 4.18.01 and later.
RetryOption

Configure how the Router reacts for this virtual host when the Message Processor goes down.

You can specify multiple values by using <RetryOption>. 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.

For example:

<RetryOptions>
  <RetryOption>http_599</RetryOption>
  <RetryOption>error</RetryOption>
  <RetryOption>timeout</RetryOption>
  <RetryOption>invalid_header</RetryOption>
</RetryOptions>
ListenOptions Available for Private Cloud 4.18.01 and later and for Edge Cloud by making a request to Apigee Edge Support.
ListenOption

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 <ListenOption> is an empty string.

For example:

<ListenOptions>
  <ListenOption>proxy_protocol</ListenOption>
</ListenOptions>

To later unset <ListenOption>, update the virtual host and omit the <ListenOptions> tag from the update.

SSLInfo
Enabled

Enables one-way TLS/SSL. You must have defined a keystore containing the cert and private key.

For Cloud: You must have a cert signed by a trusted entity, such as Symantec or VeriSign. You cannot use a self-signed cert, or leaf certificates signed by a self-signed CA.

For Cloud: If your existing virtual host is configured to use a port other than 443, you cannot change the TLS setting. That means you cannot change the TLS setting from enabled to disabled, or from disabled to enabled.

false No
ClientAuthEnabled Enables two-way, or client, TLS between Edge (server) and the app (client) making the request. Enabling two-way TLS requires that you set up a truststore on Edge that contains the cert from the TLS client. false No
KeyStore

The name of the keystore on Edge.

Apigee recommends that you use a reference to specify the keystore name so that you can change the keystore without having to restart Routers. See Options for configuring TLS for more.

None Yes if Enabled is true
KeyAlias The alias specified when you uploaded the cert and private key to the keystore. You must specify the alias name literally; you cannot use a reference. See Options for configuring TLS for more. None Yes if Enabled is true
TrustStore

The name of the truststore on Edge that contains the certificate or certificate chain used for two-way TLS. Required if <ClientAuthEnabled> is true.

Apigee recommends that you use a reference to specify the truststore name so that you can change the truststore without having to restart Routers. See Options for configuring TLS for more.

None No
IgnoreValidationErrors

If true, specifies to ignore TLS certificate errors. This is similar to the "-k" option to cURL.

This option is valid when configuring TLS for Target Servers and Target Endpoints, and when configuring virtual hosts that use 2-way TLS.

When used with a target endpoint/target server, if the backend system uses SNI and returns a cert with a subject Distinguished Name (DN) that does not match the hostname, there is no way to ignore the error and the connection fails.

false No
Ciphers

For Edge for Private Cloud version 4.15.07 and earlier only.

Specifies the ciphers supported by the virtual host. If no ciphers are specified, then all ciphers available for the JVM will be permitted.

To restrict ciphers, add the following elements:

<Ciphers>
  <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</Cipher>
  <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</Cipher>
</Ciphers>
All supported by the JVM No
Protocols

For Edge for Private Cloud version 4.15.07 and earlier only.

Specifies the protocols supported by the virtual host. If no protocols are specified, then all protocols available for the JVM will be permitted.

To restrict protocols, add the following elements:

<Protocols>
  <Protocol>TLSv1</Protocol>
  <Protocol>TLSv1.2</Protocol>
  <Protocol>SSLv2Hello</Protocol>
</Protocols>
All supported by the JVM No
UseBuiltInFreeTrialCert Available for Edge Cloud only.
UseBuiltInFreeTrialCert

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 free trial cert and key. That means you can create the virtual host without first creating a keystore.

The Apigee free trial cert is defined for a domain of *.apigee.net. Therefore, the <HostAlias> of the virtual host must also be in the form *.apigee.net.

See Defining a virtual host that uses the Apigee free trial cert and key.

false No
PropagateTLSInformation Available in Alpha for Edge Cloud only.
ConnectionProperties

Enables the capture of TLS connection information by Edge. This information is then available as flow variables in an API proxy. See Accessing TLS connection information in an API proxy for more.

false No
ClientProperties

Enables the capture of client cert details captured by Edge in two-way TLS. This information is then available as flow variables in an API proxy. See Accessing TLS connection information in an API proxy for more.

false No
Properties Available for Edge Cloud and for Private Cloud 4.17.01 and later.
proxy_read_timeout

Sets the timeout duration, in seconds, between Message Processors and the Router. The Router drops the connection and returns an HTTP 504 response if it does not get a response from the Message Processor before this duration expires.

The value of proxy_read_timeout should be greater than the target timeout value used by the Message Processor. This ensures that the Router does not timeout before the Message Processor has had time to return a response. The default target timeout for the Message Processor is 55 seconds, 55000 milliseconds, as defined by the conf_http_HTTPTransport.io.timeout.millis token for the Message Processor.

57 No
keepalive_timeout

Sets the timeout duration, in seconds, between the client and the Router when the client makes a request that contains the Keep-Alive header. The Router keeps the connection open until the duration expires.

The Router will not close the connection if it is currently waiting for a response from the Message Processor. The timeout begins only after the Router returns the response to the client.

65 No
ssl_ciphers

Sets the ciphers supported by the virtual host, overriding the defaults ciphers set on the Router.

Specify a colon-delimited list of ciphers, in the form:

<Property name="ssl_ciphers">HIGH:!aNULL:!MD5:!DH+3DES:!kEDH;</Property>

For information on the syntax and values allowed by this token, see https://www.openssl.org/docs/man1.0.2/man1/ciphers.html. Note that this token uses the OpenSSL cipher names, such as AES128-SHA256, and not the Java/JSSE cipher names, such as TLS_RSA_WITH_AES_128_CBC_SHA256.

HIGH:!aNULL:

!MD5:

!DH+3DES:

!kEDH

No
ssl_protocols

Available for Edge for Private Cloud only.

Sets the TLS protocols supported by the virtual host, as a space delimited list, overriding the defaults protocols set on the Router.

Note: If two virtual hosts share the same port, they must set ssl_protocols to the same protocols. Meaning, virtual hosts sharing the same port must support the exact same protocols.

Specify a space-delimited list of TLS protocols, in the form:

<Property name="ssl_protocols">TLSv1 TLSv1.2</Property>
TLSv1 TLSv1.1 TLSv1.2 No
proxy_request_buffering

Enables (on) or disables (off) buffering of the request body. When buffering is on, the Router buffers the entire request body before sending it to the Message Processor. If there is an error, the Router can retry a different Message Processor.

If off, buffering is disabled and the request body is sent to the Message Processor immediately as it is received. If there is an error, the Router does not retry the request to another Message Processor.

on No
proxy_buffering Enables (on) or disables (off) buffering of the response. When buffering is on, the Router buffers the response. When buffering is off, the response is passed to the client synchronously, immediately as it is received by the Router. on No