Mettre à jour les index d'un TosDJ existant
Sur cette page
Les index d’un annuaire TosDJ sont créés par le setup, à partir du profil choisi. Quand une version de TOSIAM ajoute un index à un profil, seules les nouvelles installations le reçoivent : remplacer les binaires d’un annuaire existant ne modifie pas sa configuration. Cette page décrit comment ajouter les index manquants à un annuaire déjà installé, serveur en marche.
Quand appliquer la procédure#
| Version | Index ajouté | Profils | Ce qu’il accélère |
|---|---|---|---|
| 3.38.0 | Aucun | – | – |
La 3.38.0 n’ajoute pas d’index ; elle en retire deux. Ses préversions ajoutaient un index sur coreTokenType pour la liste des sessions : il n’est plus utile, la liste cherche désormais les sessions par leur handle, déjà indexé.
La procédure est sans risque à rejouer : elle ajoute ce qui manque et ignore ce qui existe déjà. Elle s’applique donc telle quelle à chaque montée de version, sans avoir à savoir quels index ont changé.
1. Préparer les fichiers d’index#
Les définitions d’index sont livrées dans lib/tst-ldif.jar de la distribution TosDJ. Prenez le fichier de la nouvelle version :
INSTALL_DIR=~/tosdj/install
unzip -p "$INSTALL_DIR"/lib/tst-ldif.jar ldif/sfha/cts-indices.ldif \
| sed 's/@DB_NAME@/userRoot/g' > index-cts.ldif
unzip -p "$INSTALL_DIR"/lib/tst-ldif.jar ldif/opendj/opendj_user_index.ldif \
| sed 's/@DB_NAME@/userRoot/g' > index-user.ldifuserRoot est le nom du backend créé par le setup. Les fichiers à appliquer dépendent du profil du serveur :
| Profil | Fichiers |
|---|---|
cts | index-cts.ldif |
config | index-user.ldif puis index-cts.ldif |
user | index-user.ldif |
2. Créer les index manquants#
Appliquez chaque fichier séparément : index-cts.ldif ne se termine pas par une ligne vide, et le contenu d’un fichier concaténé à sa suite serait rattaché à sa dernière entrée.
for f in index-cts.ldif; do # fichiers du profil, voir le tableau
"$INSTALL_DIR"/bin/ldapmodify -h "$(hostname -f)" -p 1389 \
-D "cn=Directory Manager" -j ~/tosdj/pwd.txt \
--defaultAdd --continueOnError -f "$f"
done~/tosdj/pwd.txt est un fichier qui contient le mot de passe de cn=Directory Manager ; supprimez-le après la procédure. --continueOnError passe les index déjà présents : chacun produit un message Entry Already Exists, sans conséquence. Seuls les index manquants sont créés.
3. Reconstruire les index#
Un index ajouté à un serveur en marche est dégradé : il existe, mais n’est pas utilisé tant qu’il n’a pas été reconstruit. La reconstruction s’exécute comme une tâche, sans arrêter le serveur, et ne traite que les index dégradés :
"$INSTALL_DIR"/bin/rebuild-index --hostname "$(hostname -f)" --port 4444 \
--bindDN "cn=Directory Manager" --bindPasswordFile ~/tosdj/pwd.txt --trustAll \
--baseDN dc=tosit,dc=org --rebuildDegradedLa commande rend la main quand la tâche est terminée :
Rebuild Index task 20261003185131273 scheduled to start immediately
Rebuild Index task 20261003185131273 has been successfully completedSa durée dépend du nombre d’entrées. Sur un CTS de plusieurs millions de jetons, lancez-la hors période de charge. Jusqu’à la fin de la tâche, les recherches concernées restent non indexées, comme avant la procédure.
4. Vérifier#
L’attribut debugsearchindex demande à TosDJ comment il traiterait une recherche, sans l’exécuter :
"$INSTALL_DIR"/bin/ldapsearch -h "$(hostname -f)" -p 1389 \
-D "cn=Directory Manager" -j ~/tosdj/pwd.txt \
-b "ou=famrecords,ou=openam-session,ou=tokens,dc=tosit,dc=org" \
"(coreTokenString03=shandle:*)" debugsearchindex| Réponse | Signification |
|---|---|
[INDEX:coreTokenString03.substring][COUNT:12] | Index utilisé (ici, 12 sessions ouvertes) |
[INDEX:coreTokenString03.substring][NOT-INDEXED] | Index créé mais pas encore reconstruit : refaire l’étape 3 |
[NOT-INDEXED] seul | Index absent : refaire l’étape 2 |
Limite d’un index d’égalité sur un attribut peu varié#
Un index TosDJ cesse de suivre une valeur quand plus de 4 000 entrées la portent (index-entry-limit). La recherche sur cette valeur redevient alors non indexée, et la réponse de debugsearchindex contient [LIMIT-EXCEEDED].
Un attribut qui ne prend que quelques valeurs, comme coreTokenType (SESSION, OAUTH, SAML2…), se prête donc mal à un index d’égalité : au-delà de 4 000 entrées par valeur l’index ne sert plus, et en deçà toutes les écritures qui portent la même valeur se disputent la même clé d’index.
C’est pourquoi la liste des sessions ne cherche pas par coreTokenType. Elle cherche les jetons dont le handle de session (coreTokenString03) commence par shandle: : l’index a une clé par session, et la recherche reste indexée jusqu’à 100 000 sessions ouvertes. Sur un CTS de 398 000 jetons, la liste de 4 300 sessions répond en 170 ms.
Retirer un index devenu inutile#
À l’inverse, une version peut retirer un index de ses profils. Ni la montée de version ni la commande upgrade ne le suppriment d’un annuaire existant : retirez-le sur chaque serveur.
| Version | Index retiré | Profils | Raison |
|---|---|---|---|
| 3.38.0 | coreTokenDate02 (égalité) | cts, config | Débit d’écriture du Core Token Store |
| 3.38.0 | coreTokenType (égalité), s’il a été ajouté par une préversion de la 3.38.0 ou par cette page avant le 12 octobre 2026 | cts, config | Débit d’écriture du Core Token Store |
Les jetons OAuth2 portent dans coreTokenDate02 l’heure de l’authentification, à la seconde. Tous les jetons des authentifications d’une même seconde partageaient donc une clé d’index, que chaque création et chaque suppression de jeton verrouillait jusqu’à la fin de sa transaction : sous charge, les écritures du Core Token Store faisaient la queue derrière cette clé. Aucune recherche de TOSIAM ne porte sur cet attribut.
Sur un banc d’essai (un annuaire de profil cts, 8 processeurs, 64 connexions), le retrait fait passer le débit de 14 000 à 20 600 écritures par seconde.
De même, toutes les sessions partageaient la clé SESSION de l’index de coreTokenType, que chaque ouverture et chaque fermeture de session verrouillait. La liste des sessions ne s’en sert plus.
Retirez chaque index par la commande suivante, en changeant --index-name :
"$INSTALL_DIR"/bin/dsconfig delete-backend-index \
--backend-name userRoot --index-name coreTokenDate02 \
-h "$(hostname -f)" -p 4444 -X \
-D "cn=Directory Manager" -j ~/tosdj/pwd.txt -nLe retrait est immédiat, serveur en marche, et ne demande ni reconstruction ni redémarrage. La configuration n’est pas répliquée : jouez la commande sur chaque serveur de la topologie.
Conteneurs et Kubernetes#
La procédure est la même, exécutée dans le conteneur. Les images n’ont pas unzip : extrayez les fichiers sur le poste d’administration après avoir copié tst-ldif.jar hors de l’image (docker cp ou kubectl cp), puis envoyez chaque fichier sur l’entrée standard :
kubectl exec -i tosdj-cts-0 -- sh -c 'cat > /tmp/f.ldif; ldapmodify -h localhost -p 1389 \
-D "cn=Directory Manager" -j /run/secrets/tosdj/root-password \
--defaultAdd --continueOnError -f /tmp/f.ldif; rm -f /tmp/f.ldif' < index-cts.ldifAvec Docker, remplacez kubectl exec -i <pod> -- par docker exec -i <conteneur>.
Pour aller plus loin#
- Installer TosDJ : profils,
setupet reconstruction initiale des index. - Scalabilité & haute disponibilité : réplication des annuaires et Core Token Store.
- Sessions & Tokens : ce que contient le Core Token Store.
Mis à jour le