Résolution de l'erreur « Impossible de se connecter au noyau Kopano » de l'application Web Kopano

Pour résoudre rapidement l'erreur « Impossible de se connecter à Kopano Core » dans une application web Kopano, il est essentiel d'identifier la couche défaillante parmi les trois suivantes : Kopano Core lui-même , le point de terminaison WebApp-to-Core ou la couche PHP-MAPI utilisée par l'application web pour communiquer avec Core. Redémarrer l'ensemble des services peut parfois sembler résoudre le problème, mais cela masque la cause et complique le diagnostic des pannes récurrentes.

La documentation officielle de l'application Web de Kopano indique que celle-ci dépend de Kopano Core php-mapiet DEFAULT_SERVERque son paramètre détermine son mode de connexion. Les options documentées incluent le socket Unix local, HTTP sur le port 236 et HTTPS sur le port 237. Consultez la documentation de configuration de l'application Web de Kopano et le manuel d'administration de Kopano Core .

Note importante concernant la version : les manuels d’administration publics de Kopano disponibles au moment de la rédaction sont plus anciens que de nombreuses distributions Linux actuelles. Les noms des paquets, les versions de PHP, les wrappers de services et l’emplacement des journaux peuvent donc différer sur votre installation. Le modèle de connexion et les options de configuration décrits ci-dessous sont basés sur la documentation publiée par Kopano, mais il est recommandé de vérifier les chemins d’accès locaux et les versions des paquets avant de modifier un serveur de production.

Quelle solution devriez-vous essayer en premier ?

Commencez par le symptôme qui correspond le mieux à votre organisme plutôt que d'appliquer tous les changements en même temps.

1. Kopano Core est-il réellement en cours d'exécution ?

Vérifiez le processus serveur avant de modifier la configuration de l'application Web. Sur une distribution basée sur systemd, utilisez :

sudo systemctl status kopano-server

Si l'unité est défaillante ou inactive, consultez son journal récent avant de la redémarrer :

sudo journalctl -u kopano-server -n 100 --no-pager

Recherchez les erreurs de connexion à la base de données, les échecs d'analyse de la configuration, les problèmes d'autorisation, les fichiers manquants ou les erreurs de démarrage. La documentation de Kopano Core indique que les modifications de configuration nécessitent généralement le redémarrage du composant concerné, par exemple avec `npm install` systemctl restart kopano-<component>. Elle précise également /etc/kopano/server.cfgque `npm install` est le fichier de configuration habituel pour Kopano Core kopano-server. Consultez la section « Configurer les composants KC » .

Choisissez cette option lorsque : le service est manifestement hors service, plante après le démarrage, ou d’autres outils Kopano ne peuvent pas non plus communiquer avec Core. Réparer WebApp en premier lieu ne ferait que traiter un symptôme en aval.

Compromis : le redémarrage est la méthode de récupération la plus rapide, mais si le processus échoue à nouveau immédiatement, il est indispensable de consulter les journaux système. Sur les systèmes de production, il est donc crucial de capturer les détails de l’échec avant de redémarrer afin de ne pas perdre les preuves les plus importantes.

2. L'application Web pointe-t-elle vers le point de terminaison Kopano Core correct ?

Dans l'application Web, le paramètre clé se trouve DEFAULT_SERVERdans config.php. Le manuel officiel de l'application Web de Kopano documente ces exemples :

define("DEFAULT_SERVER", "default:");
define("DEFAULT_SERVER", "file:///var/run/kopano/server.sock");
define("DEFAULT_SERVER", "http://localhost:236/kopano");
define("DEFAULT_SERVER", "https://localhost:237/kopano");

La configuration par défaut documentée correspond à la socket locale file:///var/run/kopano/server.sock. C'est généralement le choix le plus simple lorsque WebApp et Core s'exécutent sur la même machine. S'ils s'exécutent sur des machines distinctes, une socket Unix locale ne convient pas ; vous avez besoin d'un point de terminaison HTTP ou HTTPS accessible. La documentation de Kopano relative à l'optimisation des performances décrit la connexion d'un hôte WebApp à un serveur Kopano distinct via le port 236, ou le port 237 pour SSL. Consultez la section « Optimisation des performances de Kopano et configuration d'un serveur partagé » .

Socket Unix local : généralement l’option la moins gourmande en ressources sur un hôte donné, elle évite d’exposer un service TCP uniquement pour l’accès local à une application web. En contrepartie, le socket doit exister et le processus du serveur web doit pouvoir l’utiliser.

HTTP sur le port 236 : plus facile à tester sur différents hôtes et adapté aux réseaux internes de confiance lorsque votre architecture de sécurité le permet. En contrepartie, le trafic n’est pas chiffré au niveau de la couche transport Kopano.

HTTPS sur le port 237 : recommandé pour les échanges chiffrés entre l’application web et le serveur. Cela implique la configuration et la validation de certificats. La documentation de configuration spécifique de Kopano montre comment l’application web utilise HTTPS DEFAULT_SERVERet, dans certains cas, des certificats clients. Voir les configurations spécifiques du serveur pour Kopano .

3. Si vous utilisez un socket Unix, existe-t-il et le serveur web peut-il y accéder ?

Pour un déploiement sur le même hôte, vérifiez le socket lui-même :

ls -l /var/run/kopano/server.sock
file /var/run/kopano/server.sock
ss -xl | grep kopano

Si le fichier est absent, ne créez pas de fichier portant ce nom. Le socket est créé par le serveur Kopano en cours d'exécution. L'absence d'un socket est donc généralement due au démarrage du noyau, à une modification du chemin du socket ou à une erreur de configuration.

Si le socket existe, vérifiez son propriétaire et son mode d'accès. L'utilisateur du serveur web doit pouvoir y accéder via son chemin d'accès. Selon votre distribution, le compte du serveur web peut être `username` www-data, apache`username` ou un autre utilisateur spécifique au service. Évitez de résoudre les erreurs d'autorisation avec des modes d'accès trop généraux comme chmod 777`open` ; cela augmente l'exposition des permissions et celles-ci risquent d'être écrasées lors de la prochaine recréation du socket par le service.

Il est préférable d'aligner l'application Web avec l'emplacement du socket généré par Kopano, puis d'utiliser les permissions de groupe ou de service prévues par la distribution. Si votre serveur a été personnalisé, comparez la configuration du noyau avec le point de terminaison de l'application Web avant de modifier le propriétaire.

4. Que se passe-t-il si le noyau est sain mais que l'application Web indique toujours qu'elle ne peut pas se connecter ?

Vérifiez ensuite PHP-MAPI. Kopano indique explicitement que WebApp en dépend php-mapi. La vérification de la configuration de WebApp peut également tester la disponibilité de PHP et de PHP-MAPI. Consultez la documentation de WebApp Config.php .

Une vérification rapide en ligne de commande est :

php -m | grep -i mapi

Ce test présente toutefois une limitation importante : l’interface de ligne de commande PHP peut ne pas utiliser la même configuration qu’Apache PHP, PHP-FPM ou une autre intégration de serveur web. Un résultat positif en ligne de commande prouve uniquement que l’environnement de ligne de commande reconnaît le module.

Les vérifications complémentaires utiles comprennent :

php --ini
php -i | grep -i mapi

Comparez ensuite cette configuration avec celle utilisée par votre serveur web ou votre pool FPM. Si le paquet est manquant ou si les versions sont incompatibles, installez le paquet Kopano Core/PHP-MAPI correspondant depuis le dépôt prévu pour votre distribution et votre version de Kopano. N'utilisez pas plusieurs versions de PHP-MAPI différentes simplement pour faire apparaître l'extension php -m.

Choisissez cette option lorsque : kopano-server le système est sain, le point de terminaison est correct et accessible, mais l’application Web échoue lors de ses vérifications de connexion ou de configuration côté PHP.

Compromis : la réinstallation ou la mise à niveau des paquets peut s’avérer la solution adéquate en cas d’incompatibilité des fichiers binaires, mais elle modifie davantage le système que la simple correction d’un point de terminaison. Il est donc essentiel de vérifier au préalable les versions des paquets et de planifier les mises à niveau en production en conséquence.

Faut-il redémarrer Apache, PHP-FPM ou le serveur Kopano ?

Redémarrez le composant dont la configuration ou le module a été modifié.

• Si vous avez effectué une modification /etc/kopano/server.cfg, redémarrez kopano-server.
• Si vous avez installé ou activé une extension PHP, redémarrez la couche de service PHP utilisée par WebApp, telle qu'Apache ou le service PHP-FPM correspondant.
• Si vous avez uniquement modifié le fichier de configuration PHP de l'application Web, un redémarrage complet de Kopano Core n'est généralement pas nécessaire, sauf si le point de terminaison Core lui-même a également été modifié.

La commande exacte du service web varie selon la distribution et le package PHP. Il peut s'agir systemctl restart apache2, par exemple systemctl restart httpd, de `php-fpm`, ou d'une unité PHP-FPM versionnée. Utilisez le nom du service tel qu'il apparaît sur votre hébergeur plutôt que de copier une commande sans discernement.

Qu’en est-il des serveurs Core distants et des pare-feu ?

Si l'application Web et Kopano Core sont séparés, vérifiez d'abord le routage et le listener configuré avant d'incriminer l'application Web. La documentation de Kopano décrit l'accès HTTP sur le port 236 et l'accès SSL sur le port 237. Un déploiement distant ajoute donc plusieurs sources de défaillance qu'un déploiement local sur socket Unix ne présente pas : règles de pare-feu, liaison du listener, DNS, certificats TLS, proxys inverses et politique réseau intermédiaire.

Pour un point de terminaison HTTP, vous pouvez au moins vérifier si un écouteur TCP est accessible depuis l'hôte de l'application Web :

nc -vz core.example.net 236

Pour HTTPS, vérifiez séparément le point de terminaison TLS à l'aide d'un outil conforme à votre politique de certificats. Une connexion TCP réussie ne garantit pas le succès de l'authentification de l'application Web ni des opérations MAPI, mais une connexion échouée prouve que PHP-MAPI ne peut pas atteindre le service configuré à cette adresse et sur ce port.

Si vous utilisez un proxy inverse, veuillez noter que la documentation de Kopano exige que le chemin du proxy et le mappage du serveur soient cohérents avec l'URL utilisée par l'application web. Le manuel officiel de Kopano Core mentionne également les considérations relatives au protocole HTTP/1.1 pour le proxy du trafic Kopano. Consultez la section Configuration des composants de Kopano Core .

Un ordre de diagnostic pratique qui minimise les changements inutiles

1. Vérifiez kopano-serverl'état. En cas d'échec, commencez par réparer le noyau.
2. Consultez les journaux principaux. Les problèmes de base de données ou de configuration doivent être résolus avant que l'application Web puisse se connecter.
3. Vérifiez DEFAULT_SERVER. Confirmez qu'il correspond à un socket local ou au point de terminaison HTTP/HTTPS distant correct.
4. Testez le socket ou l'écouteur réseau lui-même. Cela permet de distinguer les problèmes de transport des problèmes PHP.
5. Vérifiez PHP-MAPI dans l'environnement d'exécution web. Ne vous fiez pas uniquement à l'environnement PHP en ligne de commande.
6. Redémarrez uniquement les services concernés. Ensuite, testez à nouveau l'application Web et consultez les journaux si l'erreur persiste.

Cette méthode est plus sûre que de commencer par la réinstallation des paquets, car elle préserve les données et donne du sens à chaque test. Elle évite également l'erreur inverse : redémarrer WebApp ou Apache à répétition alors que Kopano Core ne parvient pas à démarrer.

Quand la modification de DEFAULT_SERVER n'est-elle pas la bonne solution ?

Ne modifiez pas la configuration DEFAULT_SERVERsimplement parce que la page de connexion affiche une erreur de connexion. Si la valeur actuelle pointe correctement vers l'instance Core souhaitée, la modifier peut masquer le problème initial ou rediriger les utilisateurs vers le mauvais serveur.

Par exemple, remplacer ` default:<socket>` par `<socket>` http://localhost:236/kopanon'est pas intrinsèquement une mise à niveau. Cela modifie le protocole de transport, passant du socket local par défaut documenté au protocole TCP. Si cela peut s'avérer utile pour le débogage ou pour une topologie nécessitant TCP, cela modifie également la sécurité et la surface d'exploitation. Dans une configuration sur le même hôte, il est souvent plus simple de corriger le socket manquant ou inaccessible que d'ouvrir un autre écouteur.

Que faire si l'erreur persiste ?

À ce stade, recueillez des preuves des deux côtés de la relation :

• DEFAULT_SERVERla valeur exacte , après suppression des identifiants et des secrets ;
• systemctl status kopano-serveret les entrées récentes du journal du serveur Kopano ;
• les informations relatives à la propriété du socket ou à l'écouteur distant ;
• la version PHP et l'extension MAPI chargée dans l'environnement d'exécution du serveur Web ;
• Journal des erreurs WebApp/PHP relatif à une tentative de connexion infructueuse.

La documentation de l'application web de Kopano indique que la journalisation des erreurs PHP est activée via les paramètres PHP config.phpet déconseille l'affichage direct des erreurs, car cela peut corrompre les réponses JSON. Les journaux côté serveur constituent donc une meilleure source de diagnostic. Consultez les paramètres de journalisation officiels de l'application web avant d'augmenter le niveau de détail.

Une fois que vous avez déterminé si l'échec provient du démarrage du noyau, du transport, des permissions, de PHP-MAPI ou du réseau distant, appliquez la correction la plus simple adaptée à cette couche. Cette approche est plus fiable que de considérer l'erreur « Impossible de se connecter au noyau Kopano » comme un problème unique nécessitant une solution universelle.