Aller au contenu

FAQ

Dernière mise à jour : 13 octobre 2026

Questions fréquemment posées sur Tolk for Cisco UC, organisées par thème.

Général

Qu'est-ce que Tolk for Cisco UC ?

Tolk for Cisco UC est un serveur MCP (Model Context Protocol) sur site qui fait le pont entre des agents IA — Claude Desktop, GitHub Copilot, Cursor, ou tout outil compatible MCP — et votre infrastructure Cisco Unified Communications.

Ce n'est pas un service cloud. Il s'exécute dans un conteneur Docker sur un hôte de votre réseau, expose un point de terminaison MCP HTTPS sécurisé aux agents IA, et communique avec les nœuds Cisco UC via AXL, RIS, CUPI et SSH. Il s'administre depuis une interface Web d'administration HTTPS.

Nécessite-t-il un accès à Internet ?

Non. Tolk est entièrement capable de fonctionner en mode air gap. Il ne dispose d'aucune télémétrie, d'aucune dépendance au cloud, et d'aucun comportement de rappel vers l'extérieur. Toute la connectivité se fait strictement entre :

  • Votre client agent IA → Tolk (HTTPS/MCP)
  • Les navigateurs des administrateurs → Tolk (HTTPS, interface Web d'administration)
  • Tolk → Vos nœuds Cisco UC (AXL/HTTPS, RIS/HTTPS, CUPI/HTTPS, SSH)

Même la vérification de licence s'effectue hors ligne — le fichier de licence est un JWT signé, validé localement par rapport au nom d'hôte du serveur.

Quels agents IA sont compatibles ?

Tout agent prenant en charge le protocole de transport MCP Streamable HTTP. Par exemple :

  • Claude Desktop
  • VS Code avec l'extension MCP
  • Cursor
  • OpenCode
  • Des outils personnalisés basés sur un LLM utilisant le SDK MCP

Tolk utilise le transport MCP Streamable HTTP standard — tout client conforme MCP fonctionnera.

Puis-je l'utiliser avec un LLM hébergé dans le cloud ?

Oui. Le LLM (OpenAI, Anthropic Claude API, etc.) et l'agent IA peuvent être hébergés dans le cloud. Tolk reste dans votre réseau : la seule connexion entrante dont il a besoin est l'appel MCP de l'agent.

Gardez à l'esprit que les résultats des outils Tolk sont fournis au LLM comme contexte : avec un LLM cloud, les données Cisco UC lues par l'agent (configuration, utilisateurs, équipements…) sont transmises au fournisseur du LLM. Restreignez les outils et données accessibles à chaque agent avec son profil RBAC client (page Clients → onglet Profils), et privilégiez un LLM local lorsqu'aucune donnée ne doit quitter votre réseau.

Est-il compatible avec les LLM locaux ?

Oui. Associé à un LLM local (Ollama, LM Studio, llama.cpp, etc.) et à un agent IA fonctionnant localement, l'ensemble de la chaîne opère sans aucune connexion Internet. C'est idéal pour les environnements très réglementés où aucune donnée ne doit quitter le réseau interne.

Licence

Comment obtenir une licence ?

Contactez tolk@sourdeau.com pour commander une licence, en indiquant le FQDN de l'hôte Docker (hostname -f) : la licence y est liée (voir Obtenir votre licence).

Vous recevez un fichier license.jwt. Importez-le depuis l'interface Web d'administration : page Licence → carte Importer une licence, puis cliquez sur Appliquer & redémarrer (voir Importer votre licence).

Que se passe-t-il à l'expiration de ma licence ?

L'expiration de la licence suit un modèle en deux phases :

  1. Période de grâce (30 jours après l'expiration, sauf durée différente fixée par la licence) : le serveur continue de fonctionner normalement. Un rappel de renouvellement est journalisé et affiché sur la page Licence et dans /status.
  2. Après la période de grâce (EXPIRED) : le point de terminaison MCP est désactivé — aucun agent IA ne peut se connecter. L'interface Web d'administration reste disponible comme console de secours, pour importer une nouvelle licence. Une licence qui expire alors que le serveur tourne est appliquée au redémarrage nocturne (03:15).

Anticipez

Surveillez la date d'expiration sur la page Licence (ou avec l'outil infra_server_status / GET /status), et renouvelez avant la fin de la période de grâce (voir Renouvellement).

Puis-je utiliser la même licence sur un serveur différent ?

Non. Les licences sont liées au nom d'hôte — chaque licence est émise pour un FQDN d'hôte Docker spécifique (HOST_FQDN). Utiliser la même licence sur un nom d'hôte différent entraîne un état INVALID.

Contactez tolk@sourdeau.com pour une réémission lors d'une migration vers un nouveau serveur.

La licence est-elle indépendante de la version ?

Oui. Une licence valide continue de fonctionner avec toutes les mises à jour logicielles — il n'y a pas de licence par version. Une fois émise, votre licence est valide jusqu'à sa date d'expiration, quel que soit le nombre de mises à jour effectuées.

Qu'est-ce qu'une licence de démonstration ?

Une licence à durée limitée à des fins d'évaluation. Elle donne accès à l'ensemble des modules produit pour une période d'essai fixe. Disponible sur demande à tolk@sourdeau.com.

À quel attribut du serveur la licence est-elle liée ?

La licence est liée au FQDN de l'hôte Docker (hostname -f), renseigné dans HOST_FQDN et utilisé comme nom d'hôte du conteneur. Le nom d'hôte est intégré dans le JWT de licence au moment de l'émission et vérifié à chaque démarrage ; la page Licence affiche le nom d'hôte du serveur à côté de celui de la licence. Tout changement de nom d'hôte — renommage de VM, migration, changement de domaine — invalide la licence.

Contactez tolk@sourdeau.com pour une réémission en cas de changement de nom d'hôte.

Comment vérifier l'état actuel de la licence ?

Ouvrez la page Licence de l'interface Web d'administration : elle affiche l'état de la licence, le client, le niveau, la date d'expiration, les produits activés, le nombre de clients utilisés par rapport au maximum, et la liaison au nom d'hôte. L'état de la licence est aussi affiché sur le Tableau de bord.

Vous pouvez également utiliser l'outil MCP infra_server_status ou GET /status, ou le vérificateur en ligne de commande :

docker compose exec tolk python scripts/license_checker.py

Installation & Configuration

Quels systèmes d'exploitation sont pris en charge ?

Tolk est livré sous forme d'image Docker : il fonctionne sur tout hôte disposant de Docker Engine ≥ 27.0 et de Docker Compose ≥ 2.32. Un hôte Linux est recommandé en production ; macOS et Windows (Docker Desktop, WSL 2) conviennent à l'évaluation et aux environnements de lab. Voir les Prérequis.

Les distributions Linux suivantes sont activement testées :

Distribution Versions
Ubuntu LTS 22.04, 24.04
RHEL / AlmaLinux 9.x, 10.x
Debian 12, 13
Puis-je l'exécuter dans Docker ?

Oui — Docker est le mode de déploiement de Tolk. Suivez le guide Démarrage rapide : seules quelques valeurs de démarrage Docker sont renseignées dans .env avant le premier lancement ; tout le reste se configure depuis l'interface Web d'administration.

Le conteneur s'exécute avec un utilisateur non-root (UID / GID, root refusé), un système de fichiers racine en lecture seule et un contrôle de santé. Toutes les données d'exécution sont persistées via des volumes bind-mount.

Puis-je exécuter plusieurs instances ?

Oui. Vous pouvez exécuter plusieurs instances Tolk sur des hôtes séparés, chacune avec sa propre licence liée au nom d'hôte. C'est l'approche recommandée pour séparer les environnements (par exemple, production vs. lab) ou servir plusieurs équipes avec des pistes d'audit isolées.

Plusieurs instances peuvent aussi être publiées derrière un reverse proxy avec répartition de charge (voir Reverse Proxy).

Que faire si la vérification de signature RSA-PSS échoue pendant l'installation ?

Ne poursuivez pas l'installation. Un échec de vérification de signature signifie soit :

  • L'archive a été corrompue pendant le téléchargement (relancez le téléchargement et vérifiez le SHA-512)
  • L'archive a été altérée

Contactez tolk@sourdeau.com avant de poursuivre. N'exécutez jamais un logiciel dont le contrôle d'intégrité échoue.

Comment reconfigurer après l'installation ?

Depuis l'interface Web d'administration — aucune modification de .env n'est nécessaire :

  1. Modifiez les paramètres sur les pages Paramètres globaux et Produits (les clients sont sur la page Clients). Chaque modification est mise en attente.
  2. Cliquez sur Appliquer & redémarrer dans le bandeau (ou Système & reload → Appliquer / Redémarrer) : vérifiez les modifications en attente et les contrôles avant redémarrage, puis cliquez sur Redémarrer maintenant.

Voir Modifier les paramètres. Exception : les valeurs de niveau Docker (HOST_FQDN, UID / GID, MCP_SERVER_PORT, ADMIN_UI_PORT) sont appliquées par Docker Compose — après les avoir modifiées, exécutez docker compose up -d sur l'hôte.

Comment changer le port d'écoute (ex. 8443 → 10443) ?
  1. Dans Paramètres globaux → onglet Server → Transport, modifiez MCP_SERVER_PORT (p. ex. 10443) et enregistrez. Le port de l'interface Web d'administration est ADMIN_UI_PORT (onglet Admin UI) ; les deux ports doivent être différents.
  2. Dans la même section, mettez à jour MCP_SERVER_SECURITY_ALLOWED_ORIGINS avec le nouveau port (p. ex. https://tolk.domain.com:10443). MCP_SERVER_SECURITY_ALLOWED_HOSTS n'a pas à changer s'il utilise le joker de port (tolk.domain.com:*).
  3. Si AUTH_ISSUER (onglet Authentication) contient le port, mettez-le aussi à jour. Il est intégré aux jetons JWT : redistribuez-les ensuite (Réinitialiser les tokens puis Voir les identifiants sur la page Clients).

  4. Le port est publié par Docker Compose, Appliquer & redémarrer ne suffit donc pas : sur l'hôte, recréez le conteneur :

    docker compose up -d

  5. Mettez à jour l'URL du point de terminaison dans toutes les configurations d'agents IA et, le cas échéant, vos règles de pare-feu.

Comment faire confiance aux certificats Cisco UC et tester la connectivité ?

La vérification TLS vers les nœuds CUCM, IMP et CUC est activée par défaut : ajoutez la CA qui a émis leurs certificats tomcat au magasin de confiance CA du produit (page Produits), puis vérifiez l'accès avec Outils → Test de connectivité produit (DNS, TCP, TLS, authentification, API, SSH).

Voir Faire confiance aux certificats Cisco UC et Tester la connectivité vers Cisco UC.

Comment mettre à jour Tolk ?

Une nouvelle version s'extrait par-dessus le répertoire d'installation et s'applique avec tolk-setup.sh ; votre .env, les secrets, les clients, les journaux et les sauvegardes sont conservés.

Suivez la procédure de Mise à jour : vérification d'intégrité du paquet, sauvegarde et mode maintenance au préalable, simulation (dry-run), puis redémarrage sur la nouvelle image.

Comment désinstaller complètement Tolk ?

Pour supprimer entièrement Tolk d'un serveur, suivez ces étapes :

1. Arrêter et supprimer le conteneur :

docker compose down

2. Supprimer l'image Docker :

# Lister les images Tolk
docker images | grep tolk

# Supprimer l'image
docker rmi tolk-for-cisco-uc:latest

# Supprimer les images résiduelles
docker image prune -f

3. Supprimer le répertoire d'installation :

rm -rf ~/tolk

Après ces étapes, aucun artefact Tolk ne subsiste sur le serveur.

Exploitation

Comment vider un nœud (mode maintenance) avant un redémarrage ou une mise à jour ?

Sur la page Système & reload → carte Mode maintenance, cliquez sur Activer le mode maintenance — aucun redémarrage n'est nécessaire :

  • les sessions MCP en cours se poursuivent, les nouvelles sessions sont refusées ;
  • un client inactif depuis plus de MAINTENANCE_IDLE_TIMEOUT_SECONDS (5 minutes par défaut) est refusé avec un message « réessayer plus tard » ; Refuser maintenant refuse immédiatement un client actif ;
  • une fois tous les clients partis, /health indique "status":"maintenance" : un répartiteur de charge retire alors le nœud.

Le mode survit à un redémarrage : cliquez sur Désactiver le mode maintenance une fois le service vérifié. Voir Mode maintenance pour le délai d'inactivité et la durée maximale de vidange optionnelle.

Comment placer Tolk derrière un reverse proxy ou un répartiteur de charge ?

Publiez Tolk sous un FQDN VIP sur le proxy, puis déclarez côté Tolk ce FQDN dans MCP_SERVER_PUBLIC_URL, les IP des proxys dans TRUSTED_PROXY_IPS, et autorisez le proxy et les PC d'administration dans ADMIN_UI_TRUSTED_IPS. Les health checks doivent envoyer l'en-tête Host du nœud.

Voir Reverse proxy (HAProxy) pour les paramètres et les configurations HAProxy complètes (serveur unique et répartition de charge). En répartition de charge, utilisez le mode maintenance pour retirer un nœud sans couper les sessions en cours.

Comment sauvegarder et restaurer Tolk, et exporter les sauvegardes en SFTP ?

Les sauvegardes sont automatiques (toutes les BACKUP_INTERVAL_HOURS, chaque semaine par défaut) et chiffrées ; Sauvegarder maintenant sur la page Sauvegarde / Restauration en déclenche une immédiatement. La même page liste, télécharge et restaure les archives. Chaque archive peut aussi être envoyée vers un serveur SFTP.

Voir Backup et Export SFTP de sauvegarde pour les paramètres, et Sauvegarde & Restauration pour le modèle de chiffrement et la procédure de restauration.

Comment annuler une modification, et l'historique de la configuration est-il conservé ?
  • Modification en attente (pas encore appliquée) : sur la page Système & reload → Appliquer / Redémarrer, cliquez sur Annuler cette modification ou Annuler toutes les modifications (voir Modifier les paramètres).
  • Modification appliquée : un instantané de la configuration est pris avant chaque modification (les 16 derniers par défaut, BACKUP_ADMIN_UI_ENV_BACKUP_RETENTION). Sur la page Sauvegarde / Restauration, sélectionnez le périmètre Configuration (.env) et restaurez un instantané : chaque paramètre différent est mis en attente pour revue avant Appliquer & redémarrer.

Les certificats et les clés RSA ont leurs propres instantanés, restaurés de la même façon (voir Autres sauvegardes).

Comment générer un show-tech pour le support ?

Sur la page Journaux → onglet Diagnostique, cliquez sur Lancer show-tech, puis Télécharger le bundle et envoyez-le à tolk@sourdeau.com avec une description du problème. Les secrets (clés privées, jetons, identifiants Cisco UC, fichier de licence) ne sont jamais inclus.

Voir Show Tech (bundle de support).

Authentification & Clients

Combien de clients IA puis-je avoir simultanément ?

Le nombre de clients est limité par la licence (nombre max de clients). La page Licence affiche les clients déclarés par rapport à la limite (p. ex. 3 / 5). Au-delà de la limite, la licence passe en GRACE avec un compte à rebours. Contactez tolk@sourdeau.com si vous avez besoin d'augmenter votre limite de clients.

Comment ajouter un nouveau client ?
  1. Ouvrez la page Clients et cliquez sur Ajouter un client.
  2. Saisissez le nom, le sujet (claim JWT sub, p. ex. sub-<nom>-AAAAMMJJ) et le profil RBAC — ainsi que le mode d'authentification lorsque AUTH_MODE vaut jwt+oauth2 — puis cliquez sur Créer le client.
  3. Cliquez sur Appliquer & redémarrer : le répertoire du client et ses identifiants (jeton JWT et/ou secret OAuth) sont générés.
  4. De retour sur la page Clients, cliquez sur Voir les identifiants et transmettez les informations de connexion de façon sécurisée à l'utilisateur — elles ne sont affichées qu'une seule fois.

Voir Créer un client.

Comment supprimer un client ?

Supprimez le client sur la page Clients, puis cliquez sur Appliquer & redémarrer. Au redémarrage, le répertoire du client — incluant tous les rapports, jetons et identifiants Cisco UC stockés — est purgé automatiquement, et ses jetons sont refusés.

Avertissement de perte de données

Téléchargez les rapports que vous souhaitez conserver (page Rapports) avant de supprimer le client et de redémarrer.

Comment révoquer le jeton d'un client sans supprimer le client ?

Sur la page Clients, cliquez sur Réinitialiser les tokens pour le client — aucun redémarrage n'est nécessaire :

  • JWT : le jeton actuel est révoqué immédiatement et un nouveau est généré ;
  • OAuth 2.1 : le client_secret est renouvelé — l'ancien secret ne permet plus d'obtenir de jetons ; les jetons d'accès déjà émis expirent d'eux-mêmes (AUTH_OAUTH_TOKEN_EXPIRY_SECONDS).

Cliquez ensuite sur Voir les identifiants pour récupérer les nouveaux identifiants (affichés une seule fois) et transmettez-les à l'utilisateur.

Note

Le point de terminaison POST /revoke (RFC 7009) permet à un client de révoquer l'un de ses propres jetons.

Quelle est la différence entre le mode JWT et le mode OAuth 2.1 ?
Mode JWT Mode OAuth 2.1
Type de jeton Statique, longue durée de vie (par défaut : 365 jours) Dynamique, courte durée de vie (par défaut : 1 heure)
Émission Généré par le serveur, affiché une seule fois À la demande via POST /token
Secret client Aucun Haché avec bcrypt, affiché une seule fois
Idéal pour Agents IA interactifs (configuration simple) Pipelines automatisés, CI/CD, sécurité renforcée
Révocation Réinitialiser les tokens (page Clients), POST /revoke Réinitialiser les tokens (renouvelle le secret), POST /revoke

Les deux modes sont également sécurisés en termes de transport et de signature. OAuth 2.1 limite la fenêtre d'exposition en cas de compromission d'un jeton grâce à sa courte durée de vie. Le mode est défini par AUTH_MODE (Paramètres globaux → Authentication) ; en jwt+oauth2, chaque client a son propre mode (voir Modes d'authentification).

Que se passe-t-il avec les jetons après une rotation de clé RSA ?

La rotation (Régénérer la paire, Paramètres globaux → onglet Authentication) réémet un nouveau jeton JWT pour chaque client. Récupérez chacun d'eux avec Voir les identifiants sur la page Clients.

Les anciens jetons restent acceptés jusqu'au Appliquer & redémarrer qui active la nouvelle paire de clés ; ils sont ensuite refusés. Planifiez le redémarrage en même temps que la redistribution des nouveaux jetons.

Les secrets clients OAuth (basés sur bcrypt) ne sont pas affectés : les clients OAuth demandent simplement un nouveau jeton d'accès. Voir Rotation des clés RSA.

Comment configurer le serveur MCP dans OpenCode avec une authentification OAuth ?

En mode OAuth 2.1, OpenCode gère nativement le flux d'authentification — aucun jeton bearer ne doit être codé en dur dans le fichier de configuration.

Éditez opencode.json et déclarez le serveur sans en-tête Authorization :

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cisco-uc-mcp-server": {
      "type": "remote",
      "url": "https://tolk.domain.com:8443/mcp/",
      "enabled": true
    }
  }
}

Avant de démarrer le client desktop OpenCode, exécutez la commande CLI suivante pour vous authentifier :

opencode mcp auth cisco-uc-mcp-server

OpenCode ouvre la page de connexion Tolk dans votre navigateur, où vous saisissez votre client_id et votre secret client pour finaliser l'authentification :

┌  MCP OAuth Authentication
│
▲  cisco-uc-mcp-server has expired credentials. Re-authenticating...
│
◇  Authentication successful!
│
└  Done

Tip

Le secret client est affiché une seule fois avec Voir les identifiants sur la page Clients. En production, autorisez aussi la redirect_uri d'OpenCode (http://127.0.0.1:19876/mcp/oauth/callback par défaut) — voir Liste blanche des redirect URI OAuth.

Comment limiter un client à un accès en lecture seule ?

Attribuez-lui un profil RBAC en lecture seule : sur la page Clients, modifiez le client et sélectionnez le profil prédéfini auditor (opérations AXL get / list et requêtes SQL, commandes SSH show, CUPI GET uniquement), puis cliquez sur Appliquer & redémarrer. Pour un contrôle plus fin, créez un profil personnalisé dans l'onglet Profils (Ajouter un profil) en ne gardant que les opérations de lecture.

Voir Profils prédéfinis et Modifier un profil.

Comment changer AUTH_MODE sans casser les clients existants ?

Passer directement de jwt à oauth2 (ou l'inverse) remplace les identifiants de tous les clients au redémarrage suivant (les jetons JWT ou les secrets OAuth sont supprimés) : tous les agents IA doivent être reconfigurés en même temps. Pour une migration progressive, passez par le mode hybride :

  1. Réglez AUTH_MODE sur jwt+oauth2 (Paramètres globaux → onglet Authentication), puis Appliquer & redémarrer : chaque client conserve son mode actuel.
  2. Sur la page Clients, passez les clients en jwt+oauth2, appliquez, puis envoyez-leur leurs nouveaux identifiants (Voir les identifiants).
  3. Une fois que tous les agents utilisent le nouveau mode, passez les clients dans le mode cible, puis AUTH_MODE dans ce même mode.

L'interface Web d'administration refuse un AUTH_MODE plus restrictif que le mode d'un client : alignez d'abord les clients. Voir Modes d'authentification.

Interface Web d'administration

Comment donner à un administrateur un accès en lecture seule à l'interface Web d'administration ?

Sur la page Administrateurs → onglet Profils, cliquez sur Ajouter un profil et réglez chaque page en lecture seule (RO) — ou sans accès pour les pages à masquer. Attribuez ensuite le profil au compte dans l'onglet Comptes. Les modifications s'appliquent immédiatement.

Voir Administrateurs.

J'ai perdu mon mot de passe de l'interface Web d'administration, ou mon compte est verrouillé — que faire ?
  • Un autre administrateur disposant des droits d'écriture sur la page Administrateurs peut cliquer sur Réinitialiser le mot de passe sur votre compte (mot de passe temporaire, à changer à la prochaine connexion) ou le déverrouiller.

  • Aucun autre administrateur disponible : réinitialisez le mot de passe depuis l'hôte Docker (ajoutez --unlock si le compte est verrouillé) :

    docker compose exec tolk python scripts/admin_set_password.py <login>

    Voir Créer le compte administrateur.

Après trop d'échecs de connexion (ADMIN_UI_LOGIN_MAX_ATTEMPTS), la connexion est aussi bloquée temporairement (ADMIN_UI_LOGIN_LOCKOUT_MINUTES, 15 minutes par défaut).

L'interface Web d'administration renvoie 403 Forbidden — que dois-je vérifier ?

Le port d'administration n'accepte que les IP sources autorisées par ADMIN_UI_TRUSTED_IPS (par défaut les plages privées 10.0.0.0/8, 172.16.0.0/12 et 192.168.0.0/16). Un 403 signifie que :

  • l'IP de votre PC n'est pas dans cette liste — derrière un reverse proxy, l'IP vérifiée est celle de X-Forwarded-For, uniquement si le proxy est déclaré dans TRUSTED_PROXY_IPS ;
  • ou votre IP (ou sous-réseau) a été mise sur liste noire manuellement sur la page Système & reload (carte IP sur liste noire, périmètre Admin Web UI).

Le refus est journalisé dans audit.log (action=adminui/access, motif ip_not_allowed ou ip_blacklisted). Corrigez depuis un PC autorisé : Paramètres globaux → onglet Admin UI, puis Appliquer & redémarrer, ou Retirer pour la liste noire (également vidée par un redémarrage). Si plus aucun PC n'atteint l'interface Web d'administration, modifiez ADMIN_UI_TRUSTED_IPS dans le fichier .env de l'hôte Docker, puis lancez docker compose up -d. Voir Admin UI.

Produit Cisco CUCM

Quelles versions de CUCM sont prises en charge ?

CUCM 14 et 15 sont officiellement pris en charge. Les schémas AXL sont gérés par version de CUCM — l'agent IA télécharge les schémas correspondant à votre cluster avec cucm_download_axl_toolkit (et cucm_download_ris_toolkit pour RIS).

Peut-il gérer plusieurs clusters CUCM ?

Oui. Les identifiants sont stockés par hôte, chiffrés dans le magasin d'identifiants de chaque client : l'agent IA enregistre chaque nœud avec cucm_store_credentials (AXL) et cucm_os_store_credentials (SSH), puis le cible par son FQDN ou son adresse IP dans les opérations AXL, RIS et SSH.

Ai-je besoin d'un compte de service Cisco dédié ?

Techniquement, un seul compte partagé fonctionne. Cependant, la bonne pratique est de créer un compte nominatif par client (utilisateur) Tolk. Cela permet :

  • Une piste d'audit par utilisateur dans les journaux CUCM
  • L'isolation des identifiants — un identifiant Tolk compromis n'affecte qu'un seul utilisateur
  • Un contrôle d'accès granulaire aligné avec votre politique RBAC CUCM
Modifie-t-il automatiquement ma configuration CUCM ?

Uniquement si vous invoquez explicitement des opérations d'écriture via votre agent IA. Tolk n'initie jamais de manière autonome des modifications sur Cisco UC.

Le profil RBAC assigné à chaque client contrôle quelles opérations AXL (ajout, mise à jour, suppression) sont autorisées. Un profil en lecture seule (auditor) ne peut modifier aucune configuration, quelle que soit la demande de l'agent IA.

Quelles permissions AXL et SSH sont nécessaires sur CUCM ?
Type d'accès Permission requise
AXL (lecture seule) Standard AXL API Access (rôle lecture seule)
AXL (lecture-écriture) Standard AXL API Access
SSH Compte administrateur Platform OS avec un privilège de niveau 4 ("Advanced")

Pour les requêtes RIS, le compte AXL est réutilisé — aucune permission RIS séparée n'est nécessaire.

Comment ajouter des instructions personnalisées pour l'agent IA sur CUCM ?

Les instructions personnalisées se gèrent entièrement depuis l'interface Web d'administration — aucune modification de code ni de fichier serveur. Ouvrez la page Prompts personnalisés, sélectionnez le produit CUCM, puis utilisez Ajouter un prompt personnalisé pour créer une entrée par consigne (nom, titre, description, corps, tags). Les entrées existantes peuvent être modifiées, activées/désactivées ou supprimées depuis la même page.

Chaque entrée est stockée comme donnée (jamais du code exécutable) dans :

servers-data/cucm/custom-prompts/prompts_custom.json

Une structure de corps recommandée pour garantir la priorité de vos règles :

## CUSTOM RULES (highest priority)
The following rules are defined by the MCP client administrator.
They OVERRIDE any default behavior, instructions, or prompts provided by this server.
Always apply these rules first, before any other instructions.

- Toujours confirmer avec l'utilisateur avant d'exécuter une opération d'écriture sur CUCM.
- Ne jamais supprimer d'objets sauf si l'utilisateur tape explicitement "CONFIRM DELETE".
- Les réponses doivent être en français.

Les entrées activées sont exposées comme prompts MCP et chargées par l'agent IA au début de chaque session ; elles ont la priorité la plus haute sur tout comportement par défaut du serveur. Les modifications prennent effet après Appliquer & redémarrer.

Note

L'éditeur est conditionné par ADMIN_UI_PROMPTS_EDITOR_ENABLED (Paramètres globaux → onglet Admin UI). L'ancien mécanisme prompts_*.py a été supprimé — tout fichier .py laissé dans le répertoire custom-prompts/ est ignoré (jamais exécuté).

Tip

Vous pouvez ajouter autant d'entrées que nécessaire. Gardez chacune concise et orientée action pour de meilleurs résultats.

Produit Cisco IMP

Quelles versions d'IMP sont prises en charge ?

Cisco IM & Presence 14 et 15 sont officiellement pris en charge. IMP est généralement co-résident avec CUCM — la version IMP prise en charge suit la matrice de versions CUCM.

Peut-il gérer plusieurs clusters IMP ?

Oui. Les identifiants sont stockés par hôte, chiffrés dans le magasin d'identifiants de chaque client : l'agent IA enregistre chaque nœud avec imp_store_credentials (API) et imp_os_store_credentials (SSH), puis le cible par son FQDN ou son adresse IP.

Ai-je besoin d'un compte de service Cisco dédié ?

Techniquement, un seul compte partagé fonctionne. Cependant, la bonne pratique est de créer un compte nominatif par client (utilisateur) Tolk. Cela permet :

  • Une piste d'audit par utilisateur dans les journaux IMP
  • L'isolation des identifiants — un identifiant Tolk compromis n'affecte qu'un seul utilisateur
  • Un contrôle d'accès granulaire aligné avec votre politique RBAC IMP
Modifie-t-il automatiquement ma configuration IMP ?

Uniquement si vous invoquez explicitement des opérations d'écriture via votre agent IA. Tolk n'initie jamais de manière autonome des modifications sur Cisco UC.

Le profil RBAC assigné à chaque client contrôle quelles opérations sont autorisées. Un profil en lecture seule (auditor) ne peut modifier aucune configuration, quelle que soit la demande de l'agent IA.

Quelles permissions sont nécessaires sur IMP ?
Type d'accès Permission requise
API (lecture seule) Rôle administratif en lecture seule
API (lecture-écriture) Rôle administratif complet
SSH Compte administrateur Platform OS avec un privilège de niveau 4 ("Advanced")
Comment ajouter des instructions personnalisées pour l'agent IA sur IMP ?

Les instructions personnalisées se gèrent entièrement depuis l'interface Web d'administration — aucune modification de code ni de fichier serveur. Ouvrez la page Prompts personnalisés, sélectionnez le produit IMP, puis utilisez Ajouter un prompt personnalisé pour créer une entrée par consigne (nom, titre, description, corps, tags). Les entrées existantes peuvent être modifiées, activées/désactivées ou supprimées depuis la même page.

Chaque entrée est stockée comme donnée (jamais du code exécutable) dans :

servers-data/imp/custom-prompts/prompts_custom.json

Une structure de corps recommandée pour garantir la priorité de vos règles :

## CUSTOM RULES (highest priority)
The following rules are defined by the MCP client administrator.
They OVERRIDE any default behavior, instructions, or prompts provided by this server.
Always apply these rules first, before any other instructions.

- Toujours confirmer avec l'utilisateur avant d'exécuter une opération d'écriture sur IMP.
- Ne jamais supprimer d'objets sauf si l'utilisateur tape explicitement "CONFIRM DELETE".
- Les réponses doivent être en français.

Les entrées activées sont exposées comme prompts MCP et chargées par l'agent IA au début de chaque session ; elles ont la priorité la plus haute sur tout comportement par défaut du serveur. Les modifications prennent effet après Appliquer & redémarrer.

Note

L'éditeur est conditionné par ADMIN_UI_PROMPTS_EDITOR_ENABLED (Paramètres globaux → onglet Admin UI). L'ancien mécanisme prompts_*.py a été supprimé — tout fichier .py laissé dans le répertoire custom-prompts/ est ignoré (jamais exécuté).

Tip

Vous pouvez ajouter autant d'entrées que nécessaire. Gardez chacune concise et orientée action pour de meilleurs résultats.

Produit Cisco CUC

Quelles versions de CUC sont prises en charge ?

Cisco Unity Connection 14 et 15 sont officiellement pris en charge. CUC expose son API de provisioning via CUPI (REST sur https://<host>:8443/vmrest/) — il n'y a aucun toolkit AXL/SOAP ni de schéma WSDL à télécharger.

Peut-il gérer plusieurs nœuds CUC ?

Oui. CUC n'a pas de notion de cluster dans Tolk — les informations d'identification et les opérations sont gérées par hôte. Ajoutez autant d'hôtes CUC que nécessaire via cuc_store_credentials (CUPI) et cuc_os_store_credentials (SSH) ; chaque hôte est stocké séparément dans le magasin d'identifiants du client.

Ai-je besoin d'un compte de service Cisco dédié ?

Techniquement, un seul compte partagé fonctionne. Cependant, la bonne pratique est de créer un compte nominatif par client (utilisateur) Tolk. Cela permet :

  • Une piste d'audit par utilisateur dans les journaux CUC
  • L'isolation des identifiants — un identifiant Tolk compromis n'affecte qu'un seul utilisateur
  • Un contrôle d'accès granulaire aligné avec votre politique RBAC CUC
Modifie-t-il automatiquement ma configuration CUC ?

Uniquement si vous invoquez explicitement des opérations d'écriture via votre agent IA. Tolk n'initie jamais de manière autonome des modifications sur Cisco UC.

Le profil RBAC assigné à chaque client contrôle quels verbes CUPI (POST / PUT / DELETE) et quels chemins /vmrest/ sont autorisés. Un profil en lecture seule (auditor) est restreint à GET /vmrest/ et ne peut modifier aucune configuration, quelle que soit la demande de l'agent IA.

Quelles permissions CUPI et SSH sont nécessaires sur CUC ?
Type d'accès Permission requise
CUPI (lecture seule) Compte administrateur Unity Connection avec le rôle "System Administrator"
CUPI (lecture-écriture) Compte administrateur Unity Connection avec un modèle de rôles couvrant les endpoints ciblés (users, call handlers, schedules, etc.)
SSH Compte administrateur Platform OS avec un privilège de niveau 4 ("Advanced")
Comment ajouter des instructions personnalisées pour l'agent IA sur CUC ?

Les instructions personnalisées se gèrent entièrement depuis l'interface Web d'administration — aucune modification de code ni de fichier serveur. Ouvrez la page Prompts personnalisés, sélectionnez le produit CUC, puis utilisez Ajouter un prompt personnalisé pour créer une entrée par consigne (nom, titre, description, corps, tags). Les entrées existantes peuvent être modifiées, activées/désactivées ou supprimées depuis la même page.

Chaque entrée est stockée comme donnée (jamais du code exécutable) dans :

servers-data/cuc/custom-prompts/prompts_custom.json

Une structure de corps recommandée pour garantir la priorité de vos règles :

## CUSTOM RULES (highest priority)
The following rules are defined by the MCP client administrator.
They OVERRIDE any default behavior, instructions, or prompts provided by this server.
Always apply these rules first, before any other instructions.

- Toujours confirmer avec l'utilisateur avant d'exécuter une opération d'écriture sur CUC.
- Ne jamais supprimer d'objets sauf si l'utilisateur tape explicitement "CONFIRM DELETE".
- Les réponses doivent être en français.

Les entrées activées sont exposées comme prompts MCP et chargées par l'agent IA au début de chaque session ; elles ont la priorité la plus haute sur tout comportement par défaut du serveur. Les modifications prennent effet après Appliquer & redémarrer.

Note

L'éditeur est conditionné par ADMIN_UI_PROMPTS_EDITOR_ENABLED (Paramètres globaux → onglet Admin UI). L'ancien mécanisme prompts_*.py a été supprimé — tout fichier .py laissé dans le répertoire custom-prompts/ est ignoré (jamais exécuté).

Tip

Vous pouvez ajouter autant d'entrées que nécessaire. Gardez chacune concise et orientée action pour de meilleurs résultats.

Sécurité

Où sont stockés les identifiants Cisco UC ?

Les identifiants sont chiffrés sur le disque, par client, à l'aide du chiffrement Fernet (AES-128-CBC + HMAC-SHA256). La clé Fernet est dérivée par client via PBKDF2-SHA512 avec 600 000 itérations, initialisée à partir d'un UUID stable unique à chaque client (clients/<name>/secrets/.uuid).

Les identifiants ne sont jamais stockés en clair dans .env, les journaux, ou tout autre fichier.

Le serveur peut-il lire ses propres sauvegardes ?

Oui, avec sa clé privée RSA. Les sauvegardes sont chiffrées en AES-256-GCM, la clé de session étant chiffrée avec la clé publique RSA du serveur (RSA-4096 OAEP). La restauration nécessite la clé privée RSA (secrets/rsa_private.pem) : le serveur la détient et peut restaurer ses archives depuis la page Sauvegarde / Restauration.

Une sauvegarde copiée ailleurs (p. ex. exportée en SFTP) est illisible sans cette clé privée. Conservez une copie hors ligne de la clé privée — et des clés archivées après une rotation RSA — pour pouvoir restaurer sur un nouveau serveur.

Comment fonctionne le journal d'audit ?

Chaque événement d'authentification, appel d'outil, opération sur les identifiants, action d'administration et anomalie de sécurité est écrit dans audit.log sous forme d'objet JSON structuré. Le journal est en ajout seul — les entrées ne sont jamais modifiées après avoir été écrites. Il se consulte sur la page Journaux → onglet Audit de l'interface Web d'administration.

La rotation des journaux crée des archives compressées, préservant l'historique complet. Pour la rétention à long terme et l'intégration SIEM, transférez audit.log vers votre infrastructure d'agrégation de journaux.

Que se passe-t-il si quelqu'un altère les fichiers du serveur ?

Le gardien d'intégrité exécute une vérification du manifeste SHA-512 sur tous les fichiers du projet au démarrage puis toutes les INTEGRITY_CHECK_INTERVAL_HOURS (24 heures par défaut). Le manifeste est signé avec RSA-PSS (RSA-4096) et ne peut pas être falsifié sans la clé de signature de l'éditeur.

  • Au démarrage, un échec de la vérification empêche le serveur de démarrer.
  • Lors d'une vérification périodique, une violation déclenche un arrêt propre du serveur.

Dans les deux cas, les fichiers concernés sont journalisés au niveau CRITICAL dans app.log et audit.log. L'état d'intégrité est affiché sur les pages Tableau de bord et Système & reload (voir Vérification de l'intégrité logicielle).

Réagissez immédiatement aux échecs d'intégrité

Une alerte d'intégrité est un événement de sécurité grave. Isolez le serveur, examinez les fichiers concernés, et réinstallez les fichiers de la version ou restaurez depuis une sauvegarde connue comme saine.

Comment signaler une vulnérabilité de sécurité ?

Envoyez un e-mail privé à tolk@sourdeau.com avec une description de la vulnérabilité. N'ouvrez pas une issue GitHub publique pour les découvertes de sécurité — la divulgation responsable protège tous les utilisateurs.

Vous recevrez un accusé de réception dans les 48 heures.

Dépannage

Les outils produit ne sont pas disponibles — que dois-je vérifier ?

Vérifiez l'état de la licence sur la page Licence (ou avec l'outil infra_server_status / GET /status). Causes courantes :

État Cause Effet Résolution
INVALID Licence absente, altérée, ou nom d'hôte non correspondant Point de terminaison MCP désactivé (interface Web d'administration disponible) Importez une licence valide ; vérifiez la liaison au nom d'hôte sur la page Licence
EXPIRED Licence au-delà de la période de grâce Point de terminaison MCP désactivé (interface Web d'administration disponible) Renouvelez via tolk@sourdeau.com et importez-la
GRACE Dans la période de grâce, ou nombre max de clients dépassé Fonctionnement normal Renouvelez bientôt, ou réduisez le nombre de clients

Avec une licence valide, seuls les produits activés par la licence sont chargés, et un client ne voit que les outils autorisés par son profil RBAC (page Clients → onglet Profils).

Mon agent IA ne peut pas se connecter à Tolk — que dois-je vérifier ?

Parcourez cette liste de contrôle dans l'ordre :

  1. URL et port du point de terminaison — utilisez l'URL du serveur affichée par Voir les identifiants (p. ex. https://tolk.domain.com:8443/mcp)
  2. Identifiants — l'agent doit utiliser le jeton actuel (ou le client_id / client_secret). En cas de perte, utilisez Réinitialiser les tokens puis Voir les identifiants sur la page Clients
  3. Confiance du certificat TLS — l'agent IA doit faire confiance au certificat TLS de Tolk. Soit faites confiance au certificat auto-signé dans le magasin de confiance de l'agent, soit remplacez-le par un certificat signé par une CA
  4. Réseau / pare-feu — confirmez que le port MCP (8443 par défaut) est accessible depuis l'hôte de l'agent vers l'hôte Tolk
  5. État du serveur — le Tableau de bord affiche l'état de la licence ; la page Système & reload affiche le mode maintenance et les IP sur liste noire
L'authentification échoue avec HTTP 401 — quelles sont les causes possibles ?
Cause Résolution
Jeton expiré ou perdu Réinitialiser les tokens puis Voir les identifiants sur la page Clients
Jeton révoqué Le jeton a été révoqué (Réinitialiser les tokens ou POST /revoke) : utilisez les nouveaux identifiants
Clé RSA renouvelée Les anciens jetons sont refusés après le redémarrage qui active la nouvelle clé : utilisez le jeton réémis par la rotation
Client supprimé Le client n'existe plus sur la page Clients
IP source sur liste noire Trop d'échecs d'authentification : voir la question suivante
Format de jeton incorrect Assurez-vous que l'en-tête Authorization utilise exactement le format Bearer <token>
Mon IP est bloquée — que dois-je faire ?

Le mécanisme Fail2Ban a bloqué l'IP après des échecs d'authentification répétés (AUTH_FAIL_LIMIT échecs en AUTH_FAIL_WINDOW_SECONDS). Le point de terminaison MCP répond alors HTTP 401, et les points de terminaison OAuth et /status HTTP 429 (too_many_failures).

Options :

  • La débloquer — page Système & reload → carte IP sur liste noire → Retirer
  • Attendre que la durée de la liste noire expire (AUTH_BLACKLIST_DURATION_SECONDS, par défaut : 15 minutes)
  • Redémarrer le serveur — la liste noire est conservée en mémoire et effacée au redémarrage

Derrière un reverse proxy, déclarez-le dans TRUSTED_PROXY_IPS : la liste noire s'applique alors à l'IP réelle du client (issue de X-Forwarded-For) et non plus à l'adresse du proxy, un client en échec ne bloque donc plus tout le monde. Les proxys de confiance ne sont jamais mis en liste noire.

Les IP bloquées et leurs causes apparaissent sur les pages Statistiques et dans audit.log (événements AUTH_BLOCKED et AUTH_FAILED, page Journaux → onglet Audit). Identifiez et résolvez la cause des échecs d'authentification avant de vous reconnecter.

Quelle est la différence entre la limite par client et la limite globale ?

Deux limites à fenêtre glissante indépendantes s'appliquent :

  • Par client — définie dans chaque profil RBAC client (page Clients → onglet Profils, une limite par service). Elle plafonne la vitesse à laquelle un seul client peut appeler une opération donnée.
  • Globale (tous clients, par hôte de destination) — limite cumulative optionnelle protégeant chaque nœud Cisco de la charge combinée de tous les clients. Indexée par hôte de destination + produit/service.

Un rejet par client est journalisé sous RATE_LIMITED ; un rejet global sous RATE_LIMITED_GLOBAL. Les deux retournent HTTP 429 avec une indication Retry-After. Les plafonds globaux se règlent par produit sur la page Produits (RATELIMIT_GLOBAL_<PRODUIT>_<SERVICE>, 0 = pas de plafond) ; la fonctionnalité se désactive entièrement avec RATELIMIT_GLOBAL_ENABLED (Paramètres globaux → onglet Rate limiting).

La licence affiche INVALID — que dois-je vérifier ?

Vérifiez ces points sur la page Licence, dans l'ordre :

  1. Licence présente — si aucune licence n'est installée, importez-la (carte Importer une licence) puis Appliquer & redémarrer
  2. Correspondance du nom d'hôte — le nom d'hôte du serveur (HOST_FQDN, résultat de hostname -f sur l'hôte Docker) doit correspondre exactement à celui de la licence. Un renommage de VM ou une migration casse cela ; après correction de HOST_FQDN, exécutez docker compose up -d sur l'hôte
  3. Intégrité du fichier — si le fichier a été altéré lors du transfert (fins de ligne, encodage), importez-le de nouveau depuis le fichier d'origine

L'aperçu de l'import affiche les détails de la licence et signale une non-correspondance du nom d'hôte avant tout remplacement.

La demande de jeton OAuth échoue avec 401 invalid_client — que s'est-il passé ?

Le couple client_id / client_secret a été refusé. Causes courantes :

  • le secret est erroné ou obsolète — il a été renouvelé avec Réinitialiser les tokens ;
  • le secret a été perdu — il n'est affiché qu'une seule fois ;
  • en mode jwt+oauth2, le client est déclaré en mode jwt uniquement (page Clients).

Pour émettre un nouveau secret, cliquez sur Réinitialiser les tokens pour le client (page Clients), puis sur Voir les identifiants pour le récupérer — aucun redémarrage n'est nécessaire.

Mon client OpenCode ne peut pas se connecter (erreur ERR_TLS_CERT_ALTNAME_INVALID) — que dois-je vérifier ?

Cette erreur signifie que le certificat TLS présenté par le serveur ne contient pas le FQDN utilisé par le client dans son extension Subject Alternative Name (SAN).

Node.js v17+ (et tous les clients TLS modernes) exigent l'extension SAN — le champ CN seul n'est plus accepté pour la validation du nom d'hôte (RFC 6125).

  • Certificat auto-signé : ses SAN proviennent d'AUTH_ISSUER, de MCP_SERVER_SECURITY_ALLOWED_HOSTS et de MCP_SERVER_PUBLIC_URL. Ajoutez le FQDN utilisé par le client à ces paramètres, puis Appliquer & redémarrer : le certificat est régénéré.
  • Certificat signé par une CA : dans Paramètres globaux → onglet TLS / Crypto → Certificat du serveur MCP, cliquez sur Générer le CSR… (des SAN supplémentaires peuvent être ajoutés dans l'aperçu), faites-le signer par votre CA, importez le .crt, puis Appliquer & redémarrer (voir Utiliser des certificats signés par une CA).

Tip

Si votre CA n'est pas approuvée par le runtime Node.js d'OpenCode, définissez également NODE_EXTRA_CA_CERTS=/path/to/ca.crt dans votre environnement (ou exportez-le depuis ~/.bashrc).