Documentation de référence sur les propriétés des hôtes virtuels

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X.
en savoir plus

Représentation de l'hôte virtuel

L'objet XML que vous utilisez pour définir un hôte virtuel est basé sur votre version d'Edge: Cloud ou Private Cloud.

Si vous êtes un client de cloud privé, vous devez vous assurer d'utiliser le bon XML pour votre version d'Edge.

Cloud et Private Cloud 4.17.01 et versions ultérieures

<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>

Cloud privé de 4.16.01 à 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 et versions antérieures

<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>

Propriétés de configuration de l'hôte virtuel

Le tableau suivant répertorie les propriétés que vous utilisez pour configurer un hôte virtuel:

Propriétés Description Par défaut Obligatoire
VirtualHost

Spécifie le nom de l'hôte virtuel. Vous utilisez ce nom pour référencer l'hôte virtuel lors de la configuration d'un proxy d'API.

Seuls les caractères suivants sont autorisés dans l'attribut "name" : A-Z0-9._\-$%.

Aucun Oui
Port

Spécifie le numéro de port utilisé par l'hôte virtuel. Assurez-vous que le port est ouvert sur Edge Router.

Si vous spécifiez un port dans un élément hostalias, le numéro de port spécifié par <Port> doit lui correspondre.

Pour le cloud: vous devez spécifier le port 443 lors de la création d'un hôte virtuel. Si cette valeur est omise, le port est défini par défaut sur 443. Si vous disposez d'un hôte virtuel existant qui utilise un port autre que 443, vous ne pouvez pas modifier le port.

Pour les versions de cloud privé 4.16.01 à 4.17.05:lors de la création d'un hôte virtuel, vous spécifiez le port de routeur utilisé par l'hôte virtuel. (par exemple, le port 9001). Par défaut, le routeur s'exécute sous le nom d'utilisateur "apigee" qui n'a pas accès aux ports privilégiés, généralement les ports 1024 et inférieurs. Si vous souhaitez créer un hôte virtuel qui lie le routeur à un port protégé, vous devez configurer le routeur pour qu'il s'exécute en tant qu'utilisateur ayant accès à ces ports. Consultez la section Configurer un hôte virtuel pour en savoir plus.

Pour les versions de cloud privé antérieures à la version 4.16.01:un routeur ne peut écouter qu'une seule connexion HTTPS par hôte virtuel, sur un port spécifique, avec le certificat spécifié. Par conséquent, plusieurs hôtes virtuels ne peuvent pas utiliser le même numéro de port en cas d'arrêt TLS sur le routeur au niveau du port spécifié.

Aucun Oui
BaseUrl Remplace l'URL affichée par l'interface utilisateur Edge pour un proxy d'API déployé sur l'hôte virtuel. Utile lorsque vous disposez d'un équilibreur de charge externe devant les routeurs de périphérie. Pour en savoir plus, consultez la page Configurer l'accès TLS à une API pour le cloud privé.

La valeur de BaseUrl doit inclure le protocole (par exemple, "http://" ou "https://").

Aucun Non
OCSPStapling

Un client OCSP (Online Certificate Status Protocol) envoie une requête d'état à un répondeur OCSP pour déterminer si le certificat TLS est valide. La réponse indique si le certificat TLS est valide et non révoqué.

Lorsque cette option est activée, l'agrafage OCSP permet à Edge, qui joue le rôle de serveur TLS pour le protocole TLS unidirectionnel, d'interroger directement le répondeur OCSP, puis de mettre en cache la réponse. Edge renvoie ensuite cette réponse au client TLS ou l'agrafe, dans le cadre du handshake TLS. Pour en savoir plus, consultez la section Activer l'agrafage OCSP sur votre serveur.

TLS doit être activé pour permettre l'agrafage OCSP. Définissez la valeur sur on pour l'activer. La valeur par défaut est off.

désactivé Non
HostAliases
HostAlias

Nom DNS visible publiquement de l'hôte virtuel sur le routeur, incluant éventuellement le numéro de port. La combinaison du nom d'alias d'hôte et du numéro de port de l'hôte virtuel doit être unique pour tous les hôtes virtuels de l'installation Edge. Cela signifie que plusieurs hôtes virtuels peuvent utiliser le même numéro de port s'ils ont des alias d'hôte différents.

Vous devez créer une entrée DNS et un enregistrement CNAME correspondant à l'alias d'hôte. Celui-ci doit correspondre à la chaîne que le client transmet dans l'en-tête Host.

Le numéro de port dans HostAlias est facultatif. Si vous spécifiez le port dans l'alias d'hôte, vous devez également spécifier le même port à l'aide de l'élément <Port>. Vous pouvez également spécifier deux éléments HostAlias, l'un avec le numéro de port et l'autre sans.

Vous pouvez avoir plusieurs définitions HostAlias dans la même définition d'hôte virtuel, correspondant à plusieurs entrées DNS pour l'hôte virtuel, mais pas pour plusieurs ports. Si vous souhaitez disposer de plusieurs ports, créez plusieurs définitions d'hôte virtuel avec des ports différents.

Vous pouvez inclure le caractère générique "*" dans l'alias d'hôte. Le caractère générique "*" ne peut se trouver qu'au début (avant le premier point) de l'alias d'hôte et ne peut pas être mélangé avec d'autres caractères. Exemple : *.example.com. Le nom CN du certificat TLS de l'hôte virtuel doit comporter un caractère générique correspondant. Exemple : *.example.com. L'utilisation d'un caractère générique dans un alias d'hôte virtuel permet aux proxys d'API de gérer les appels adressés à plusieurs sous-domaines tels que alpha.example.com, beta.example.com ou live.example.com. L'utilisation d'un alias générique vous permet également de réduire le nombre d'hôtes virtuels par environnement afin de respecter les limites du produit, car un hôte virtuel avec un caractère générique ne compte que pour un seul hôte virtuel.

Pour le cloud: si vous disposez d'un hôte virtuel existant qui utilise un port autre que le port 443, vous ne pouvez pas ajouter ni supprimer d'alias d'hôte.

Pour le cloud privé:si vous définissez l'alias d'hôte en utilisant les adresses IP de vos routeurs, et non les entrées DNS, ajoutez un alias d'hôte distinct pour chaque routeur, en spécifiant l'adresse IP de chaque routeur et son port de l'hôte virtuel.

Aucun Oui
Interfaces Disponible pour Edge for Private Cloud uniquement.
Interface

Spécifie les interfaces réseau auxquelles vous souhaitez que port soit lié. Si vous omettez cet élément, le port est lié à toutes les interfaces.

Par exemple, pour spécifier de lier le port uniquement à en0:

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

Déterminez les interfaces disponibles sur votre système en exécutant la commande "ifconfig -a".

Aucun Toutes les interfaces
RetryOptions Disponible pour Edge Cloud et pour le cloud privé 4.18.01 et versions ultérieures.
RetryOption

Configurez la réaction du routeur pour cet hôte virtuel en cas de panne du processeur de messages.

Vous pouvez spécifier plusieurs valeurs à l'aide de <RetryOption>. Les valeurs valides sont les suivantes:

off Désactive la nouvelle tentative, et l'hôte virtuel renvoie un code d'échec lors d'une requête.
http_599 (Par défaut) Si le routeur reçoit une réponse HTTP 599 du processeur de messages, il transmet la requête au processeur de messages suivant.

HTTP 599 est un code de réponse spécial généré par un processeur de messages lorsqu'il est arrêté. Le processeur de messages tente de traiter toutes les requêtes existantes, mais pour toute nouvelle requête, il renvoie le code HTTP 599 pour indiquer au routeur qu'il doit relancer la requête sur le processeur de messages suivant.

error Si une erreur s'est produite lors de l'établissement d'une connexion avec le processeur de messages, de la transmission d'une requête au processeur de messages ou de la lecture de l'en-tête de réponse, le routeur transmet la requête au processeur de messages suivant.
timeout Si un délai d'inactivité se produit lors de l'établissement d'une connexion avec le processeur de messages, de la transmission d'une requête au processeur de messages ou de la lecture de l'en-tête de réponse, le routeur transmet la requête au processeur de messages suivant.
invalid_header Si le processeur de messages renvoie une réponse vide ou non valide, le routeur transmet la requête au processeur de messages suivant.
http_XXX Si le processeur de messages renvoie une réponse avec le code HTTP XXX, le routeur transmet la requête au processeur de messages suivant.

Si vous spécifiez plusieurs valeurs, le routeur utilise un opérateur logique OR pour les combiner.

Exemple :

<RetryOptions>
  <RetryOption>http_599</RetryOption>
  <RetryOption>error</RetryOption>
  <RetryOption>timeout</RetryOption>
  <RetryOption>invalid_header</RetryOption>
</RetryOptions>
ListenOptions Disponible pour le cloud privé 4.18.01 et les versions ultérieures et pour Edge Cloud sur demande auprès de l'assistance Apigee Edge.
ListenOption

Si vous utilisez un ELB en mode pass-thru TCP pour gérer les requêtes adressées aux routeurs périphériques, le routeur traite l'adresse IP de l'ELB comme l'adresse IP du client, et non comme l'adresse IP réelle du client. Si le routeur nécessite la véritable adresse IP du client, activez proxy_protocol sur ELB pour qu'il transmette l'adresse IP client dans le paquet TCP. Sur le routeur, vous devez également définir le paramètre <ListenOption> de l'hôte virtuel sur proxy_protocol. Comme ELB est en mode pass-thru TCP, vous interrompez généralement le protocole TLS sur le routeur. Par conséquent, vous ne configurez généralement l'hôte virtuel pour utiliser proxy_protocol que lorsque vous le configurez également pour utiliser TLS.

La valeur par défaut de <ListenOption> est une chaîne vide.

Exemple :

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

Pour désactiver <ListenOption> ultérieurement, mettez à jour l'hôte virtuel et omettez la balise <ListenOptions> de la mise à jour.

SSLInfo
Activées

Active le protocole TLS/SSL à sens unique. Vous devez avoir défini un keystore contenant le certificat et la clé privée.

Pour le cloud: vous devez disposer d'un certificat signé par une entité de confiance telle que Symantec ou VeriSign. Vous ne pouvez pas utiliser de certificat autosigné ni de certificats feuilles signés par une autorité de certification autosignée.

Pour le cloud: si votre hôte virtuel existant est configuré pour utiliser un port autre que le port 443, vous ne pouvez pas modifier le paramètre TLS. Cela signifie que vous ne pouvez pas modifier le paramètre TLS pour le désactiver ou le désactiver.

false Non
ClientAuthEnabled Active le protocole TLS bidirectionnel (client) entre Edge (serveur) et l'application (client) à l'origine de la requête. L'activation du protocole TLS bidirectionnel nécessite que vous configuriez un magasin de confiance sur Edge contenant le certificat du client TLS. false Non
KeyStore

Nom du keystore sur Edge.

Apigee vous recommande d'utiliser une référence pour spécifier le nom du keystore, afin de pouvoir le modifier sans avoir à redémarrer les routeurs. Pour en savoir plus, consultez la section Options de configuration de TLS.

Aucun Oui si "Activé" est défini sur "true"
KeyAlias Alias spécifié lors de l'importation du certificat et de la clé privée dans le keystore. Vous devez spécifier le nom de l'alias de manière littérale ; vous ne pouvez pas utiliser de référence. Pour en savoir plus, consultez la section Options de configuration de TLS. Aucun Oui si "Activé" est défini sur "true"
TrustStore

Nom du magasin de confiance sur Edge contenant le certificat ou la chaîne de certificats utilisé pour le protocole TLS bidirectionnel. Obligatoire si <ClientAuthEnabled> est "true".

Apigee vous recommande d'utiliser une référence pour spécifier le nom du magasin de confiance, afin de pouvoir le modifier sans avoir à redémarrer les routeurs. Pour en savoir plus, consultez la section Options de configuration de TLS.

Aucun Non
IgnoreValidationErrors

Si la valeur est "true", les erreurs de certificat TLS doivent être ignorées. Cette méthode est semblable à l'option "-k" de cURL.

Cette option est valide lors de la configuration du protocole TLS pour les serveurs cibles et les points de terminaison cibles, ainsi que lors de la configuration d'hôtes virtuels qui utilisent le protocole TLS bidirectionnel.

Lorsqu'il est utilisé avec un point de terminaison cible ou un serveur cible, si le système backend utilise SNI et renvoie un certificat dont le nom distinctif (DN) de l'objet ne correspond pas au nom d'hôte, il est impossible d'ignorer l'erreur et la connexion échoue.

false Non
Algorithmes de chiffrement

Pour Edge for Private Cloud version 4.15.07 et antérieures uniquement.

Spécifie les algorithmes de chiffrement compatibles avec l'hôte virtuel. Si aucun chiffrement n'est spécifié, tous les algorithmes de chiffrement disponibles pour la JVM seront autorisés.

Pour limiter les algorithmes de chiffrement, ajoutez les éléments suivants:

<Ciphers>
  <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</Cipher>
  <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</Cipher>
</Ciphers>
Toutes sont prises en charge par la JVM Non
Protocoles

Pour Edge for Private Cloud version 4.15.07 et antérieures uniquement.

Spécifie les protocoles acceptés par l'hôte virtuel. Si aucun protocole n'est spécifié, tous les protocoles disponibles pour la JVM seront autorisés.

Pour restreindre les protocoles, ajoutez les éléments suivants:

<Protocols>
  <Protocol>TLSv1</Protocol>
  <Protocol>TLSv1.2</Protocol>
  <Protocol>SSLv2Hello</Protocol>
</Protocols>
Toutes sont prises en charge par la JVM Non
UseBuiltInFreeTrialCert Disponible pour Edge Cloud uniquement.
UseBuiltInFreeTrialCert

Si vous possédez un compte Edge for Cloud payant et que vous ne disposez pas encore d'un certificat et d'une clé TLS, vous pouvez créer un hôte virtuel qui utilise le certificat et la clé d'essai sans frais Apigee. Cela signifie que vous pouvez créer l'hôte virtuel sans créer d'abord de keystore.

Le certificat d'essai sans frais Apigee est défini pour le domaine *.apigee.net. Par conséquent, le <HostAlias> de l'hôte virtuel doit également être au format *.apigee.net.

Consultez Définir un hôte virtuel qui utilise le certificat et la clé d'essai sans frais Apigee.

false Non
PropagateTLSInformation Disponible en version alpha pour Edge Cloud uniquement.
ConnectionProperties

Active la capture des informations de connexion TLS par Edge. Ces informations sont ensuite disponibles sous forme de variables de flux dans un proxy d'API. Pour en savoir plus, consultez la section Accéder aux informations de connexion TLS dans un proxy d'API.

false Non
ClientProperties

Active la capture des détails du certificat client capturés par Edge avec le protocole TLS bidirectionnel. Ces informations sont ensuite disponibles sous forme de variables de flux dans un proxy d'API. Pour en savoir plus, consultez la section Accéder aux informations de connexion TLS dans un proxy d'API.

false Non
Propriétés Disponible pour Edge Cloud et pour le cloud privé 4.17.01 et versions ultérieures.
proxy_read_timeout

Définit le délai avant expiration, en secondes, entre les processeurs de messages et le routeur. Le routeur abandonne la connexion et renvoie une réponse HTTP 504 s'il ne reçoit pas de réponse du processeur de messages avant l'expiration de ce délai.

La valeur de proxy_read_timeout doit être supérieure à la valeur du délai d'expiration cible utilisée par le processeur de messages. Cela garantit que le routeur n'expire pas avant que le processeur de messages ait eu le temps de renvoyer une réponse. Le délai avant expiration cible par défaut pour le processeur de messages est de 55 secondes, 55 000 millisecondes, comme défini par le jeton conf_http_HTTPTransport.io.timeout.millis pour le processeur de messages.

57 Non
keepalive_timeout

Définit le délai avant expiration, en secondes, entre le client et le routeur lorsque le client effectue une requête contenant l'en-tête Keep-Alive. Le routeur maintient la connexion ouverte jusqu'à l'expiration de la durée.

Le routeur ne fermera pas la connexion s'il attend une réponse du processeur de messages. Le délai avant expiration ne commence qu'une fois que le routeur a renvoyé la réponse au client.

65 Non
ssl_ciphers

Définit les algorithmes de chiffrement compatibles avec l'hôte virtuel, en remplaçant les algorithmes de chiffrement par défaut définis sur le routeur.

Spécifiez une liste d'algorithmes de chiffrement séparés par des deux-points, au format suivant:

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

Pour en savoir plus sur la syntaxe et les valeurs autorisées par ce jeton, consultez la page https://www.openssl.org/docs/man1.0.2/man1/ciphers.html. Notez que ce jeton utilise des noms d'algorithmes de chiffrement OpenSSL, tels que AES128-SHA256, et non des noms d'algorithmes Java/JSSE tels que TLS_RSA_WITH_AES_128_CBC_SHA256.

HIGH:!aNULL:

!MD5:

!DH+3DES:

!kEDH

Non
ssl_protocols

Disponible pour Edge for Private Cloud uniquement.

Définit les protocoles TLS acceptés par l'hôte virtuel sous la forme d'une liste délimitée par des espaces, en remplaçant les protocoles par défaut définis sur le routeur.

Remarque: Si deux hôtes virtuels partagent le même port, ils doivent définir ssl_protocols sur les mêmes protocoles. Cela signifie que les hôtes virtuels partageant le même port doivent être compatibles avec exactement les mêmes protocoles.

Spécifiez une liste de protocoles TLS délimités par des espaces, au format suivant:

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

Active (active) ou désactive (désactivée) la mise en mémoire tampon du corps de la requête. Lorsque la mise en mémoire tampon est activée, le routeur met en mémoire tampon l'intégralité du corps de la requête avant de l'envoyer au processeur de messages. En cas d'erreur, le routeur peut réessayer avec un autre processeur de messages.

Si cette option est désactivée, la mise en mémoire tampon est désactivée et le corps de la requête est envoyé au processeur de messages dès sa réception. En cas d'erreur, le routeur ne relance pas la requête auprès d'un autre processeur de messages.

le Non
proxy_buffering Active (active) ou désactive (désactivée) la mise en mémoire tampon de la réponse. Lorsque la mise en mémoire tampon est activée, le routeur met la réponse en mémoire tampon. Lorsque la mise en mémoire tampon est désactivée, la réponse est transmise au client de manière synchrone, immédiatement dès sa réception par le routeur. le Non