Configuration d' TLS ou d' HTTPS pour l'intégration avec ITM V6 (version préliminaire publique)

Présentation

Par défaut, les agents ITM communiquent avec l'agent hôte d' Instana via le protocole HTTP sur le port 42699 (port par défaut utilisé par les agents ITM pour communiquer avec Instana ). Pour garantir la sécurité des communications, vous pouvez configurer des connexions TLS / HTTPS entre les agents ITM et l'agent hôte Instana.

La mise en place d' HTTPS. nécessite la configuration de certificats des deux côtés :

1. Instana Côté agent hôte : configurez les certificats d' TLS (.crt et .key les fichiers) pour activer le service HTTPS sur le port 42699.
2. Côté agent ITM : configurez les fichiers de trousseau GSK (Global Security Kit) de l' IBM, de manière à ce qu'ils reconnaissent le certificat de l'agent hôte Instana.

L'agent hôte d' Instana utilise des fichiers de certificats au format texte standard (.crt et .key), tandis que les agents ITM nécessitent des fichiers de base de données de trousseau GSK au format IBM (.kdb et .sth). Ce guide fournit des instructions détaillées pour la création et la configuration de ces deux formats de certificat.

Prérequis

Avant de commencer, assurez-vous de remplir les conditions suivantes :

• Installez et exécutez l'agent hôte d' Instana.
• Agents ITM ( V6 ) mis à jour avec la version 6.3.0.7-TIV-ITM_TEMA-IF0008 ou une version ultérieure. Cette version est requise pour la prise en charge d' HTTPS.
• Installez OpenSSL sur le système sur lequel vous générez les certificats.
• Assurez-vous que les commandes GSKit d' IBM sont disponibles (elles sont généralement incluses dans les installations d'ITM).
• Téléchargez et décompressez le pack de configuration ITM « V6 ».

Étape 1 : Configurer l' TLS ation sur l'agent hôte Instana

Commencez par activer l' TLS ation sur l'agent hôte Instana afin d'accepter les connexions HTTPS sur le port 42699.

Création de certificats d' TLS

Vous pouvez soit créer un certificat auto-signé, soit obtenir un certificat auprès de votre autorité de certification (CA).

Option A : Créer un certificat auto-signé

Utilisez les commandes suivantes pour créer un certificat auto-signé :

# Create a private key
openssl genrsa -out tls.key 2048

# Create a certificate signing request (CSR)
# Replace 'instana.example.com' with your Instana host agent's hostname
openssl req -new -key tls.key -out tls.csr -subj "/CN=instana.example.com"

# Create a self-signed certificate valid for 365 days
openssl x509 -req -days 365 -in tls.csr -signkey tls.key -out tls.crt

Option B : Utiliser un certificat émis par votre autorité de certification

Si vous disposez déjà d'un certificat délivré par votre autorité de certification :

1. Assurez-vous de disposer à la fois du fichier de certificat (.crt ou .pem) et du fichier de clé privée (.key). Les fichiers .pem et sont .crt tous deux au format texte et peuvent être utilisés indifféremment.
2. Vérifiez que le nom commun (CN) du certificat correspond au nom d'hôte de votre agent d' Instana :

   openssl x509 -in your-cert.crt -noout -subject

Installation de certificats sur l'agent hôte d' Instana

1. Copiez les fichiers de certificat sur l'agent hôte d' Instana :
   • <agent_installation>/etc/certs/tls.crt
   • <agent_installation>/etc/certs/tls.key
2. Une fois les certificats ajoutés, redémarrez l'agent pour initialiser les connexions réseau.
3. Vérifiez que l'agent est à l'écoute sur HTTPS :

   # This should show a TLS handshake
   openssl s_client -connect localhost:42699 -showcerts

   Le résultat affiche la chaîne de certificats et indique que la connexion a été établie avec succès.

Pour plus d'informations sur la configuration d' TLS sur l'agent hôte d' Instana, consultez la section « Configuration du chiffrement d' TLS pour le point de terminaison de l'agent ».

Étape 2 : Créer des fichiers de trousseau GSK « IBM » pour les agents ITM

Les agents ITM utilisent le format Global Security Kit (GSK) d' IBM pour les certificats, ce qui nécessite la création d'une base de données de trousseau de clés (.kdb) et d'un fichier de stockage (.sth).

Localisation des commandes GSKit d' IBM

IBM GSKit est généralement inclus dans les installations ITM. Les exemples suivants utilisent des chemins d'accès de type « Linux ». Pour les autres systèmes de type Unix ( AIX ), adaptez les chemins d'accès en fonction de votre installation ITM.

Emplacements courants des commandes GSKit :

• Linux: /opt/IBM/ITM/<arch>/gs/bin/gsk8capicmd_64
• Windows : C:\IBM\ITM\GSK8_x64\bin\gsk8capicmd_64.exe (pour les systèmes 32 bits, utilisez GSK8 à la place de GSK8_x64)

Avant d'utiliser les commandes GSKit sur Linux, définissez le chemin d'accès à la bibliothèque :

export LD_LIBRARY_PATH=/opt/IBM/ITM/<arch>/gs/lib64:$LD_LIBRARY_PATH

Vérifiez que la commande GSKit est disponible :

/opt/IBM/ITM/<arch>/gs/bin/gsk8capicmd_64 -help

Création des fichiers de trousseau de clés

1. Créez un keyfiles répertoire dans votre pack de configuration :

   cd /path/to/instana-v6-configuration-pack
   mkdir keyfiles
   cd keyfiles

2. Définissez le chemin d'accès à la commande GSKit (à adapter en fonction de votre installation d'ITM) :

   GSK_CMD=/opt/IBM/ITM/<arch>/gs/bin/gsk8capicmd_64

3. Créer une nouvelle base de données de trousseau à l'aide d'un fichier de sauvegarde :

   $GSK_CMD -keydb -create -db keyfile.kdb -pw password -type cms -stash

   Important : remplacez « mot de passe » par un mot de passe fort. Le fichier stash crypte ce mot de passe, mais veillez à choisir un mot de passe sécurisé, conformément aux politiques de sécurité de votre organisation.
   Remarque : cette -stash option crée le fichier keyfile.sth de cache qui stocke le mot de passe sous forme chiffrée. Cela permet aux agents ITM d'accéder au trousseau de clés sans avoir à saisir de mot de passe.
4. Copiez le certificat de l'agent hôte d' Instana (créé à l'étape 1) dans le répertoire actuel. Vous devrez transférer le tls.crt fichier depuis le système de l'agent hôte Instana vers le système sur lequel vous créez les fichiers de trousseau de clés :

   # Example: Copy the certificate from the Instana host agent
   # name the file instana-host-agent.crt

5. Importez le certificat de l'agent hôte d' Instana dans le trousseau de clés en tant que certificat d'autorité de certification (CA) de confiance :

   $GSK_CMD -cert -add -db keyfile.kdb -pw password -label "Instana_Host_Agent_Cert" -file instana-host-agent.crt -format ascii -trust enable

   Remarque : si l'importation échoue, vérifiez que le fichier de certificat est au format ASCII/ PEM et que le chemin d'accès au fichier est correct.
   Remarque : cet -trust enable indicateur marque ce certificat comme fiable, ce qui permet aux agents ITM d'accepter les connexions provenant de l'agent hôte Instana.
6. Vérifiez le contenu du trousseau :

   $GSK_CMD -cert -list -db keyfile.kdb -pw password

   La sortie répertorie les certificats présents dans le trousseau, y compris « Instana_Host_Agent_Cert ».

7. (Facultatif) Supprimer le fichier de certificat après l'importation :

   rm instana-host-agent.crt

   Remarque : une fois le certificat importé dans le trousseau, le fichier du certificat d'origine n'est plus nécessaire et peut être supprimé pour des raisons de sécurité.
8. Vérifiez que le répertoire « keyfiles » contient au moins les fichiers suivants :
   • keyfile.kdb - La base de données des trousseaux de clés
   • keyfile.sth - Le fichier de cache contenant le mot de passe chiffré
   • keyfile.rdb - Base de données des demandes (créée automatiquement)
   Remarque : vous pouvez également voir un keyfile.crl fichier (liste de révocation de certificats), qui est créé automatiquement par GSKit mais qui n'est pas indispensable au fonctionnement de base d' TLS.

Étape 3 : Configurer les agents ITM pour qu'ils utilisent HTTPS

Maintenant que vous avez créé les fichiers de trousseau de clés, configurez les agents ITM pour qu'ils utilisent HTTPS.

1. Mettez à jour le env.properties fichier dans le pack de configuration :

   protocol=https
   hostname=instana.example.com
   tenantid=id-mycluster-account
   port=42699

   Important : assurez-vous que le nom d'hôte correspond au nom commun (CN) figurant dans le certificat de l'agent hôte d' Instana. En cas de non-correspondance, les agents ITM ne parviendront pas à établir une connexion sécurisée.
2. Vérifiez la structure keyfiles des répertoires :

   ls -la keyfiles/

   Le répertoire contient :

   keyfile.kdb
   keyfile.sth
   keyfile.rdb

3. Exécutez le script de configuration comme décrit dans la section « Intégration avec IBM ITM V6 » :

   Configuration locale :

   ./agent2server_itm.sh -i /opt/IBM/ITM -c dual -e env.properties

   Configuration à distance :

   # First, transfer the keyfiles directory to the remote system
   tacmd putfile -m kvm-011235:LZ -s /path/to/configpack/keyfiles/keyfile.kdb -d /tmp/configpack/keyfiles/keyfile.kdb
   tacmd putfile -m kvm-011235:LZ -s /path/to/configpack/keyfiles/keyfile.sth -d /tmp/configpack/keyfiles/keyfile.sth
   tacmd putfile -m kvm-011235:LZ -s /path/to/configpack/keyfiles/keyfile.rdb -d /tmp/configpack/keyfiles/keyfile.rdb
   
   # Then run the configuration script
   tacmd executecommand -m kvm-011235:LZ -c "nohup /bin/sh -c 'sleep 10; /tmp/configpack/agent2server_itm.sh -i /opt/IBM/ITM -c dual -e /tmp/configpack/env.properties > /tmp/output' &" -w /tmp/configpack

   Le script déploiera automatiquement les fichiers de trousseau de clés du keyfiles répertoire vers $CANDLEHOME/keyfiles_icam/ sur les systèmes des agents ITM.

Vérification de l'utilisation d' HTTPS par l'agent ITM

Une fois que vous avez configuré les agents ITM pour l' HTTPS, vérifiez qu'ils utilisent bien la connexion sécurisée :

Consultez les fichiers de configuration de l'agent ITM pour vérifier les paramètres du protocole :

# Check the agent's environment file for the protocol setting
grep -i "https" $CANDLEHOME/config/*.environment

Le résultat affiche des entrées indiquant le protocole HTTPS. Vérifiez également les journaux de l'agent ITM pour voir s'ils contiennent des messages liés à « SSL » ou « TLS » lors de l'établissement de la connexion.

Dépannage des connexions à l' HTTPS

Si les agents ITM ne parviennent pas à se connecter via HTTPS, procédez comme suit pour résoudre le problème :

Non-correspondance entre le nom d'hôte et le certificat

Symptôme : les agents ITM ne parviennent pas à se connecter, et des erreurs de type « SSL » ou « TLS » apparaissent dans les journaux.

Solution : Assurez-vous que le nom d'hôte dans env.properties correspond au nom commun (CN) figurant dans le certificat de l'agent hôte de l' Instana :

# Check the CN in the certificate
openssl x509 -in /opt/instana/agent/etc/certs/tls.crt -noout -subject

# Compare with the hostname in env.properties
grep hostname env.properties

Problèmes liés à la confiance dans les certificats

Symptôme : les agents ITM signalent des erreurs de validation de certificat.

Solution : Vérifiez que le certificat de l'agent hôte d' Instana est correctement importé dans le trousseau de clés ITM :

$GSK_CMD -cert -list -db keyfile.kdb -pw password

La liste comprend « Instana_Host_Agent_Cert ». Si ce n'est pas le cas, réimportez le certificat en suivant l'étape 2.

Erreurs du journal de l'agent ITM

Symptôme : Échecs de connexion sans message d'erreur précis.

Solution : Vérifiez les journaux de l'agent ITM pour voir s'il y a des erreurs de type SSL / TLS :

# Linux/AIX
tail -f $CANDLEHOME/logs/<short_hostname>_<product_code>_*.log

# Windows
type  %CANDLEHOME%\TMAITM6_x64\logs\<short_hostname>_<product_code>_*.log

Recherchez les messages contenant les termes « SSL », « TLS », « certificate » ou « handshake ».

Tester la configuration de l'agent hôte Instana TLS

Problème : vous ne savez pas si l'agent hôte d' Instana est correctement configuré pour TLS.

Solution : Utilisez la commande « OpenSSL » pour vérifier la configuration de l'agent hôte Instana sur TLS :

openssl s_client -connect instana.example.com:42699 -showcerts

Une connexion établie s'affichera comme suit :

• La chaîne de certificats
• « Vérification du code de retour : 0 (OK) » ou « Vérification du code de retour : 18 (certificat auto-signé) » pour les certificats auto-signés
• « Messages de lecture de la poignée de main SSL »

Droits d'accès aux fichiers du porte-clés

Problème : les agents ITM ne parviennent pas à lire les fichiers de trousseau de clés.

Solution : Vérifiez que les fichiers du trousseau sont accessibles à l'utilisateur de l'agent ITM :

ls -l $CANDLEHOME/keyfiles_icam/

Les fichiers doivent disposer au minimum de droits de lecture pour l'utilisateur de l'agent ITM. Sinon, modifiez les droits d'accès :

chmod 644 $CANDLEHOME/keyfiles_icam/keyfile.kdb
chmod 644 $CANDLEHOME/keyfiles_icam/keyfile.sth
chmod 644 $CANDLEHOME/keyfiles_icam/keyfile.rdb

Connectivité du réseau

Symptôme : délais d'attente de connexion ou erreurs « connexion refusée ».

Solution : Vérifiez la connectivité réseau et les règles du pare-feu :

# Test connectivity to the Instana host agent
telnet instana.example.com 42699

# Or use nc (netcat)
nc -zv instana.example.com 42699

Veillez à ce que :

• Le port 42699 est ouvert sur le système hôte de l'agent d' Instana.
• Les règles de pare-feu autorisent le trafic provenant des systèmes des agents ITM vers l'agent hôte d' Instana, sur le port 42699.
• DNS La résolution fonctionne correctement pour ce nom d'hôte.

Rubriques connexes

• Intégration avec IBM ITM V6 - Documentation principale sur l'intégration.
• Configuration du chiffrement « TLS » pour le terminal de l'agent - Instana configuration de l'agent hôte TLS.