docs: explain Cleanmgr package workflow
This commit is contained in:
PierreCsn committed
1 parent
424509aac8
commit
c654d018bf
1 file changed
+111
-62
@@ -1,78 +1,127 @@
|
|||||||
# comi-cleanmgr - sources de paquet WAPT
|
# Comitari Cleanmgr Profiles — paquet WAPT
|
||||||
|
|
||||||
Paquet de configuration de **N profils cleanmgr Windows**, destine a etre personnalise
|
Ce paquet prépare des profils pour l’outil de nettoyage Windows intégré **Cleanmgr** (`cleanmgr.exe`). Il permet de choisir les catégories de nettoyage, de les enregistrer sous plusieurs identifiants, puis de contrôler leur configuration avec l’audit WAPT.
|
||||||
avec **Lancer update-package** depuis la console WAPT. Pas de suppression de fichiers lors
|
|
||||||
de l'installation : seuls les parametres des profils sont deposes dans le registre.
|
|
||||||
|
|
||||||
## Update-package : approche native WAPT
|
> **Le paquet n’effectue pas le nettoyage.** Son installation configure des valeurs dans le Registre Windows. Les fichiers ne sont supprimés que si un administrateur lance ensuite Cleanmgr avec l’identifiant du profil.
|
||||||
|
|
||||||
Le code est adapte des conventions utilisees dans le paquet public officiel
|
## Le fonctionnement en bref
|
||||||
[`tis-waptagent-logo-template` 1.1-15](https://wapt.tranquil.it/store/en/details/tis-waptagent-logo-template_1.1-15_windows_5.1_PROD.wapt) :
|
|
||||||
|
|
||||||
- `waptguihelper.message_dialog(...)` : introduction et validation.
|
Le paquet comporte deux étapes qui se déroulent à des endroits différents :
|
||||||
- `waptguihelper.input_dialog(...)` : nombre de profils, categories additionnelles.
|
|
||||||
- `waptguihelper.grid_dialog(..., waptguihelper.GRT_ALL, MetaData)` : tableau editable des IDs/noms et grilles de categories (booleens).
|
|
||||||
- `control.inc_build()` puis `control.save_control_to_wapt()` : incrementation native du build WAPT lors d'un changement.
|
|
||||||
- Garde pour `params['install_with_luti']` ou `params['running_as_luti']` : pas d'interface sur les builds automatiques LUTI.
|
|
||||||
|
|
||||||
Les helpers `ask_control_package` et `ask_control_version` de l'exemple de Tranquil IT
|
1. **Préparer le paquet dans la console WAPT.** L’action `update-package` ouvre un assistant graphique et enregistre les profils dans `profiles.json`, dans les sources du paquet.
|
||||||
sont **definis dans le fichier de l'exemple** ; ce ne sont pas des API standard.
|
2. **Déployer le paquet sur les postes.** `setup.py` traduit ce fichier en valeurs `StateFlagsNNNN` dans le Registre. L’installation ne lance pas Cleanmgr.
|
||||||
Ici, comme le nom du paquet ne change pas et que seule sa configuration change,
|
|
||||||
`control.inc_build()` est suffisant.
|
|
||||||
|
|
||||||
## Utilisation
|
L’audit WAPT vérifie ensuite que les valeurs du Registre correspondent aux profils embarqués. Il ne vérifie pas qu’un nettoyage a été lancé ni qu’il s’est terminé.
|
||||||
|
|
||||||
1. Extraire l'archive comme sources WAPT, puis ouvrir le paquet dans la **console WAPT sur Windows**.
|
## Créer ou modifier les profils
|
||||||
2. Depuis le depot prive, cliquer **Lancer update-package**.
|
|
||||||
3. Saisir N (1 a 50), puis renseigner **dans une seule grille** les IDs `0..9999`
|
|
||||||
et les noms des N profils.
|
|
||||||
4. Pour chacun, cocher les categories dans la grille interactive. Les `VolumeCaches`
|
|
||||||
personnalises sont disponibles dans un champ facultatif.
|
|
||||||
5. Confirmer le recapitulatif : cela reecrit `profiles.json`, incremente le numero
|
|
||||||
de build de `WAPT/control` et enregistre le controle.
|
|
||||||
6. Construire, **signer** et publier le paquet selon le flux de travail habituel,
|
|
||||||
puis l'installer sur les postes.
|
|
||||||
7. Exemples d'execution (locale, admin ou action distante autorisee) :
|
|
||||||
|
|
||||||
```cmd
|
Cette opération se fait sur le poste d’administration où la console WAPT et les sources du paquet sont disponibles, pas dans une session utilisateur des postes ciblés.
|
||||||
cleanmgr.exe /sagerun:4101
|
|
||||||
cleanmgr.exe /sagerun:4102
|
|
||||||
```
|
|
||||||
|
|
||||||
`update_package()` s'execute **sur le poste de l'administrateur**, pas sur les endpoints.
|
1. Ouvrir les sources du paquet dans la console WAPT et lancer **Update package**.
|
||||||
Les postes ne voient jamais de fenetres de configuration : `setup.py` lit seulement
|
2. Indiquer le nombre de profils à créer ou conserver : de **1 à 50**. Pour un paquet vierge, l’assistant propose deux profils.
|
||||||
`profiles.json` a l'installation.
|
3. Dans la grille, donner à chaque profil un identifiant entier unique de `0` à `9999` et un nom.
|
||||||
|
4. Pour chaque profil, cocher les catégories de nettoyage. Les nouveaux profils commencent avec une sélection limitée aux fichiers temporaires, aux miniatures, au cache de shaders Direct3D et aux fichiers d’optimisation de distribution.
|
||||||
|
5. Si nécessaire, saisir des sous-clés `VolumeCaches` personnalisées, séparées par des virgules. Elles doivent respecter les caractères et la longueur acceptés par l’assistant.
|
||||||
|
6. Lire le récapitulatif, notamment les avertissements sur les catégories sensibles, puis confirmer l’enregistrement.
|
||||||
|
|
||||||
## Fonctionnement agent
|
Si l’assistant est annulé ou si le récapitulatif n’est pas confirmé, il ne modifie pas `profiles.json`. Lorsqu’une configuration différente est confirmée, l’assistant écrit ce fichier, incrémente le build dans `WAPT/control` et enregistre le contrôle WAPT. Il ne change pas le numéro de version majeure/mineure.
|
||||||
|
|
||||||
- Configuration en `HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\VolumeCaches`.
|
Ensuite, construire et signer le paquet avec le flux WAPT habituel, puis le publier dans le dépôt approprié. Les postes reçoivent le paquet construit; ils ne voient pas l’assistant graphique.
|
||||||
- `StateFlagsNNNN` REG_DWORD a `2` (categorie activee) ou `0` (categorie desactivee).
|
|
||||||
- Trace des IDs et de la configuration dans `HKLM\SOFTWARE\Comitari\CleanmgrProfiles`.
|
|
||||||
- `audit()` verifie les flags : `OK`, `WARNING` si categorie selectionnee absente de ce Windows,
|
|
||||||
`ERROR` si registre non conforme.
|
|
||||||
- `uninstall()` efface les valeurs de profil gerees sans toucher aux autres IDs.
|
|
||||||
- Les profils supprimes lors d'une evolution du paquet voient leurs flags nettoyes.
|
|
||||||
|
|
||||||
## Precautions
|
### Exemple de configuration embarquée
|
||||||
|
|
||||||
- Ne **jamais** reutiliser un ID attribue a un autre administrateur : le paquet prend
|
Les clés de catégories sont les noms techniques des sous-clés Windows, et non les libellés traduits affichés dans l’assistant.
|
||||||
le controle des `StateFlagsNNNN` de l'ID utilise.
|
|
||||||
- Certaines categories n'existent pas sous toutes les versions de Windows.
|
|
||||||
- `Previous Installations` et `Update Cleanup` peuvent limiter le retour en arriere ;
|
|
||||||
`Recycle Bin` supprime le contenu de la corbeille.
|
|
||||||
- Le comportement sous SYSTEM peut differer de celui dans une session utilisateur.
|
|
||||||
- L'action integree **Lancer CleanMgr** de WAPT Enterprise n'est pas prouvee comme
|
|
||||||
prenant en charge les profils `4101/4102` personnalises.
|
|
||||||
- Aucune tache planifiee ou nettoyage n'est lance automatiquement par ce paquet.
|
|
||||||
- L'interface graphique n'a pas ete testee sur une console WAPT Windows reelle.
|
|
||||||
La logique a ete testee via des doubles Python des helpers, de la console et du registre.
|
|
||||||
|
|
||||||
## Contenu
|
```json
|
||||||
|
{
|
||||||
|
"schema_version": 1,
|
||||||
|
"profiles": [
|
||||||
|
{
|
||||||
|
"id": 4101,
|
||||||
|
"name": "Entretien standard",
|
||||||
|
"categories": [
|
||||||
|
"Temporary Files",
|
||||||
|
"Thumbnail Cache",
|
||||||
|
"D3D Shader Cache",
|
||||||
|
"Delivery Optimization Files"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
- `WAPT/control` : metadonnees WAPT (minimum WAPT 2.4).
|
Le paquet valide le schéma, le nombre de profils, l’unicité et la plage des identifiants, le nom des profils et les clés de catégories avant d’écrire dans le Registre.
|
||||||
- `update_package.py` : assistant interactif de configuration, utilisant les helpers WAPT.
|
|
||||||
- `profiles.json` : donnees des profils embarquees.
|
|
||||||
- `setup.py` : application des profils sur les machines Windows, `audit`, `uninstall`.
|
|
||||||
|
|
||||||
Sources uniquement ; archive non signee, non compilable directement en `.wapt`
|
## Ce que fait l’installation sur un poste
|
||||||
sans la console et la chaine de signature WAPT.
|
|
||||||
|
`setup.py` lit `profiles.json`, puis énumère les sous-clés de :
|
||||||
|
|
||||||
|
```text
|
||||||
|
HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\VolumeCaches
|
||||||
|
```
|
||||||
|
|
||||||
|
Pour chaque profil et chaque catégorie présente sur ce poste, il écrit une valeur `REG_DWORD` `StateFlagsNNNN` :
|
||||||
|
|
||||||
|
- `2` pour une catégorie sélectionnée dans le profil ;
|
||||||
|
- `0` pour une catégorie disponible mais non sélectionnée.
|
||||||
|
|
||||||
|
`NNNN` correspond à l’identifiant du profil, complété par des zéros si nécessaire. L’installation enregistre aussi la configuration déployée dans `HKLM\SOFTWARE\Comitari\CleanmgrProfiles`. Cette trace permet à une mise à jour de retirer les drapeaux associés aux identifiants de profils qui ne figurent plus dans la nouvelle configuration.
|
||||||
|
|
||||||
|
Les catégories choisies qui n’existent pas sur une version donnée de Windows sont signalées dans la sortie d’installation. L’installation continue, puis l’audit WAPT retourne `WARNING` pour ces catégories absentes.
|
||||||
|
|
||||||
|
## Lancer un nettoyage
|
||||||
|
|
||||||
|
Le lancement est une action distincte, à planifier et autoriser selon les règles de l’organisation. Par exemple, pour le profil `4101` :
|
||||||
|
|
||||||
|
```cmd
|
||||||
|
cleanmgr.exe /sagerun:4101
|
||||||
|
```
|
||||||
|
|
||||||
|
**Cette commande peut supprimer les données des catégories activées.** Testez d’abord le profil sur un poste de test et vérifiez précisément sa sélection. Le paquet ne lance pas cette commande, ne crée pas de tâche planifiée et ne choisit pas à quel moment elle sera exécutée.
|
||||||
|
|
||||||
|
Les profils sont basés sur les catégories présentes dans `VolumeCaches`; leur disponibilité et leur effet dépendent de la version et de l’état de Windows. L’exécution dans le contexte `SYSTEM` peut aussi différer d’une exécution dans une session utilisateur.
|
||||||
|
|
||||||
|
## Catégories et précautions
|
||||||
|
|
||||||
|
L’assistant regroupe les catégories connues en quatre groupes. Ces étiquettes aident à la revue, mais ne remplacent pas la validation de l’effet de nettoyage sur le poste cible.
|
||||||
|
|
||||||
|
| Groupe affiché | Exemples de clés | À vérifier |
|
||||||
|
|---|---|---|
|
||||||
|
| Standard | `Temporary Files`, `Thumbnail Cache`, `D3D Shader Cache`, `Delivery Optimization Files` | Contrôler que les applications peuvent régénérer les données supprimées. |
|
||||||
|
| Maintenance | `Windows Defender`, `Windows Error Reporting Files`, `Setup Log Files`, `Windows Upgrade Log Files` | Les journaux et fichiers de diagnostic peuvent être utiles pour un dépannage. |
|
||||||
|
| Diagnostic | `System error memory dump files`, `System error minidump files`, `Memory Dump Files` | La suppression retire des éléments pouvant aider à analyser un plantage. |
|
||||||
|
| Sensible | `Update Cleanup`, `Previous Installations`, `Recycle Bin`, `Windows ESD installation files`, `Device Driver Packages` | Certaines suppressions peuvent empêcher un retour arrière ou vider la corbeille. |
|
||||||
|
|
||||||
|
Ne réutilisez pas un identifiant déjà employé par une autre configuration Cleanmgr ou un autre outil : le paquet gère les valeurs `StateFlagsNNNN` de l’identifiant utilisé et peut donc les modifier.
|
||||||
|
|
||||||
|
## Audit WAPT
|
||||||
|
|
||||||
|
L’audit lit la configuration déployée et compare les valeurs `StateFlagsNNNN` attendues avec celles du Registre :
|
||||||
|
|
||||||
|
- **`OK`** : profils suivis et drapeaux conformes pour les catégories disponibles ;
|
||||||
|
- **`WARNING`** : une catégorie sélectionnée n’est pas présente sur cette version de Windows ;
|
||||||
|
- **`ERROR`** : configuration absente ou invalide, aucune catégorie `VolumeCaches` disponible, ou drapeaux manquants/incorrects.
|
||||||
|
|
||||||
|
L’audit est en lecture seule. Il ne répare pas une configuration divergente et ne déclenche pas de nettoyage. Une erreur doit être diagnostiquée avant de relancer une installation de paquet.
|
||||||
|
|
||||||
|
## Mise à jour et désinstallation
|
||||||
|
|
||||||
|
- **Ajouter ou modifier un profil :** relancer `update-package`, construire une nouvelle version et la déployer. Lors de l’installation, les drapeaux de chaque identifiant configuré sont réécrits selon le nouveau fichier.
|
||||||
|
- **Retirer un profil :** supprimer cet identifiant de la configuration avec l’assistant, construire et déployer la mise à jour. À l’installation, le paquet supprime les drapeaux qu’il suivait pour les identifiants retirés. Aucun nettoyage de fichiers n’est lancé.
|
||||||
|
- **Désinstaller le paquet :** le script supprime les drapeaux des profils enregistrés dans sa trace, puis la valeur de suivi. Il ne supprime aucun fichier utilisateur ni fichier temporaire. Si cette trace est absente ou illisible, le script ne peut pas déterminer quels drapeaux retirer.
|
||||||
|
|
||||||
|
## Limites et informations de paquet
|
||||||
|
|
||||||
|
- Les catégories disponibles varient selon Windows; les clés personnalisées doivent exister sur le poste pour être prises en compte.
|
||||||
|
- L’action intégrée **Lancer CleanMgr** de WAPT Enterprise n’est pas documentée ici comme compatible avec les identifiants personnalisés. La commande `cleanmgr.exe /sagerun:<identifiant>` est un exemple d’exécution explicite, à valider dans l’environnement cible.
|
||||||
|
- La fenêtre graphique d’`update-package` doit être utilisée depuis une console WAPT compatible. En mode de génération LUTI, le script ne présente pas l’interface et conserve `profiles.json` tel quel.
|
||||||
|
- Le dépôt source ne contient pas de `profiles.json` initial. Pour créer un paquet déployable à partir d’un clone vierge, compléter la configuration avec **Update package** avant la construction.
|
||||||
|
- Les métadonnées de `WAPT/control` sont encore celles du squelette du dépôt (`version 0-0`, mainteneur `root`, minimum WAPT et cible OS non renseignés). Elles doivent être renseignées selon la politique de packaging avant publication d’un paquet destiné au parc.
|
||||||
|
- L’interface n’a pas été validée dans une console WAPT Windows réelle; ce README décrit le flux observé dans les scripts du dépôt.
|
||||||
|
|
||||||
|
## Fichiers du paquet
|
||||||
|
|
||||||
|
- `WAPT/control` : métadonnées WAPT, à compléter avant publication.
|
||||||
|
- `update_package.py` : assistant graphique qui génère `profiles.json` dans les sources.
|
||||||
|
- `profiles.json` : configuration embarquée générée par l’assistant.
|
||||||
|
- `setup.py` : installation des drapeaux, audit de conformité et retrait des drapeaux suivis à la désinstallation.
|
||||||
Reference in new issue
Block a user