Référence

Référence de la ligne de commande

Chaque commande, chaque option et chaque code de sortie de bws, version 0.5.0. bws --help fait foi et est plus long - cette page est la même surface, mise en forme pour être lue.

Les commandes

Onze commandes. snapshot est un nom et prend un mot après lui. tool est aussi un nom, et seul il liste les outils.

bws list [--query TEXT] [--signatures] [--memory] [--required-by] [--follow-network] [--json] [--timing]
bws show NAME [--full] [--follow-network] [--json] [--timing]
bws stop|start|restart NAME [--dry-run] [--dependents] [--timeout SECONDS] [--json] [--timing]
bws kill NAME [--force] [--restart] [--dry-run] [--dependents] [--timeout SECONDS] [--json] [--timing]
bws start-type NAME automatic|delayed|manual|disabled [--stop] [--dry-run] [--json] [--timing]
bws snapshot create [FILE] [--note TEXT] [--follow-network] [--force] [--json] [--timing]
bws snapshot diff EARLIER LATER [--exit-code] [--json] [--timing]
bws snapshot diff EARLIER --live [--exit-code] [--json] [--timing]
bws history [NAME] [--json] [--timing]
bws tool
bws tool fix
bws tool fix NAME [--dry-run] [--timeout SECONDS] [--json] [--timing]
bws license [--components]
bws --help
bws --version

Une commande mal orthographiée se voit proposer celle que vous vouliez probablement, et l'exécution se termine avec le code 2 au lieu de faire quelque chose de proche de ce que vous avez demandé.

$ bws lst
There is no command lst. Did you mean list?

Ce que fait chaque commande

`list` et `show`

list est la machine entière, affinée par --query. show est une entrée avec tout ce qu'on en sait - la signature, les privilèges, le descripteur de sécurité et la mémoire, tout lu à chaque fois, car sur une seule entrée cela coûte environ soixante millisecondes alors que sur la machine entière cela coûte une seconde. Les champs réellement vides sont omis sauf si vous passez --full. Un champ que personne n'a pu lire est affiché dans tous les cas, car l'omettre ressemblerait à une réponse.

`stop`, `start` et `restart`

Chacune construit un plan et l'exécute. --dry-run affiche le plan et ne change rien, --dependents y met les services qui cesseraient de fonctionner comme des étapes à part entière, et --timeout dit combien de temps une étape peut durer sans progrès. Les pilotes sont refusés plutôt que tentés, car arrêter un pilote du noyau n'est souvent pas réversible sans redémarrage.

`kill` - pour un service qui ne s'arrête pas

Elle demande au service de s'arrêter et termine le processus qui le porte seulement si cela ne marche pas, de sorte qu'une entrée qui s'arrête d'elle-même n'est jamais terminée. Terminer un processus emporte avec lui tout autre service qui y vit, qu'il se soit arrêté avant ou non, et l'aperçu les nomme et nomme le processus par son numéro. --force saute l'étape polie et l'aperçu montre alors une étape au lieu de deux. --restart remet tout en route ensuite.

Windows écrit cette idée autrement. --force sur Stop-Service veut dire « même si quelque chose en dépend », ce que fait ici --dependents. C'est pourquoi c'est une commande à part entière et non une option de stop.

`start-type` - un réglage, pas un mouvement

Elle dit ce que le gestionnaire fera d'une entrée au prochain démarrage, et sans --stop elle ne déplace rien : une entrée qui tourne continue de tourner, une entrée arrêtée reste arrêtée, et le plan le dit. disabled mérite qu'on s'y arrête, car il empêche le gestionnaire de démarrer l'entrée tout court, y compris à la demande pour quelque chose d'autre qui en a besoin. delayed est automatique, démarré un peu après les autres entrées automatiques - le mot que start:delayed interroge dans une requête - et Windows le refuse pour une entrée appartenant à un groupe d'ordre de chargement, ce que le plan dit avant que quoi que ce soit n'arrive. Chacune des quatre écrit si l'entrée démarre tard, comme le fait sc.exe. --stop, à côté de disabled seulement, arrête l'entrée dans le même plan une fois le réglage écrit.

`snapshot create` et `snapshot diff`

create lit toujours les signatures et les hachages, car un instantané est conservé et comparé plus tard, et un instantané sans eux comparé à un autre avec eux serait traité comme si la machine avait changé. diff dit ce qui a changé en passant du premier fichier au second, ou d'un fichier à cette machine avec --live. La page des instantanés donne le format et le raisonnement.

`history` - qui l'a changé, d'après le journal Système

Les changements de type de démarrage et les installations tirés du journal Système, les plus récents d'abord, avec le compte que Windows a enregistré. La première ligne dit jusqu'où remonte le journal et s'il a été effacé, car un historique n'est aussi long que le journal. Avec un nom, ce sont les changements de type de démarrage de ce service - les installations ne sont listées que sans nom, car Windows enregistre une installation sous le nom affiché et jamais sous le nom du service. Un compte est nommé là où cette machine peut le nommer d'elle-même et affiché sous forme de SID sinon, et les types de démarrage viennent dans les mots que Windows a écrits.

`tool` - des réponses toutes faites aux problèmes courants

Les mêmes outils que la fenêtre montre sur son onglet Tools. bws tool les liste et bws tool fix liste les réparations rapides : printer, sound, indexing et search, chacune le redémarrage d'un service Windows avec ce qui en dépend, choisies parce que les pages de dépannage de Microsoft elles-mêmes le suggèrent. bws tool fix printer est exactement bws restart Spooler --dependents - le même plan, la même sortie et les mêmes codes de sortie - et comme toute commande ici qui change quelque chose, il ne demande pas d'abord, donc --dry-run est le moyen de regarder avant l'exécution.

`license` - ce qu'il y a dans le fichier téléchargé

Elle ne lit rien du tout - ni gestionnaire de services, ni disque, ni réseau - et répond depuis un registre compilé dans l'exécutable. --components transforme la mention en chaque composant avec sa version, sa licence et son origine. Le même ensemble que porte la nomenclature publiée à côté du téléchargement, parce que les deux sont produites depuis un seul registre, et c'est la raison pour laquelle cela vaut la peine : le programme est un fichier autonome, il n'y a donc rien à côté qu'un scanner puisse lire.

Exemples

Les plans ci-dessous ont été vérifiés avec --dry-run contre le programme que décrit cette page. Une commande qui change quelque chose ne demande pas d'abord, donc --dry-run est le moyen de regarder avant l'exécution. Spooler représente n'importe quel service - mettez à sa place le nom du vôtre.

Chercher et lire

bws list                                       chaque service et pilote de cette machine
bws list --query "start:auto !status:running"  ce qui devrait tourner et ne tourne pas
bws list --query "status:running" --memory     ce que consomme le processus de chaque entrée en marche
bws show Spooler                               tout ce qu'on sait d'une entrée
bws show Spooler --full                        aussi les champs réellement vides

Regarder d'abord, changer ensuite

bws restart Spooler --dry-run                le plan, et rien d'autre
bws restart Spooler --dependents             le redémarrer avec ce qui en dépend
bws stop Spooler --dependents --timeout 120  autoriser deux minutes par étape sans progrès
bws start-type WSearch delayed --dry-run     le démarrer un peu après les autres entrées automatiques
bws start-type Spooler disabled --stop       le désactiver et l'arrêter en un seul plan

Un service qui ne s'arrête pas

bws kill Spooler --dry-run          le processus, et chaque service qui y vit
bws kill Spooler --restart          terminer le processus seulement si un arrêt échoue, puis tout remettre en route
bws kill Spooler --force --dry-run  une étape au lieu de deux : le processus terminé aussitôt

Instantanés et dérive

bws snapshot create before.json --note "before the patch"  figer la machine, avec une note conservée dedans
bws snapshot diff before.json after.json                   deux fichiers - deux jours, ou deux machines
bws snapshot diff before.json --live                       le fichier contre cette machine telle qu'elle est maintenant
bws snapshot diff before.json --live --exit-code           pareil, se terminant par 5 si la configuration a dérivé

Qui l'a changé

bws history          chaque changement de type de démarrage et installation que contient le journal Système
bws history Spooler  les changements de type de démarrage d'un service
bws history --json   la même chose sous forme de document, avec le journal et les changements

Réparations rapides

bws tool                      les outils qui existent
bws tool fix                  les réparations rapides, et le service derrière chacune
bws tool fix sound --dry-run  le plan de redémarrage des deux services audio
bws tool fix printer          redémarrer le spouleur d'impression avec ce qui en dépend

Ce qu'il y a dans le fichier

bws license --components  chaque composant, sa version, sa licence et son origine
bws --version             la version de cet exécutable

Dans un script PowerShell

# les entrées qui devraient tourner et ne tournent pas, sous forme d'objets
bws list --query "start:auto !status:running" --json | ConvertFrom-Json | Select-Object serviceName, displayName, status

# les fichiers non signés, dans un tableur
bws list --query "signed:no" --json | ConvertFrom-Json | Select-Object serviceName, binaryPath | Export-Csv unsigned.csv -NoTypeInformation

# ce dont un service a besoin
(bws show Spooler --json | ConvertFrom-Json).dependsOn

# une vérification nocturne qui se branche sur le code de sortie
bws snapshot diff C:\baselines\web01.json --live --exit-code > $null
switch ($LASTEXITCODE) {
  0 { 'no configuration drift' }
  5 { 'the configuration drifted' }
  default { "no clean answer, exit code $LASTEXITCODE" }
}

Dans cmd et un fichier batch

rem une seconde commande seulement si la première ne s'est pas terminée proprement
bws restart Spooler || echo the restart did not end cleanly

rem dans un fichier batch avec l'expansion différée activée, le ! a besoin d'un accent circonflexe
bws list --query "start:auto ^!status:running"

Options

18 au total. La troisième colonne donne les commandes auxquelles chacune appartient - une option passée à une commande qui n'en a pas l'usage est une erreur avec cette liste dedans, plutôt qu'un indicateur ignoré en silence.

Option	Ce qu'elle fait	Où elle agit
`--query`	Affiner la liste avec le langage de requête.	`list`
`--signatures`	Lire qui a signé chaque exécutable et si Windows lui fait confiance. Plusieurs secondes sur toute une machine, donc désactivé sauf demande - et une requête sur les signatures l'active d'elle-même.	`list`
`--memory`	Lire ce que consomme le processus de chaque entrée en marche. Désactivé par défaut parce que c'est une mesure et non un réglage : elle est différente une seconde plus tard.	`list`
`--required-by`	Lire quelles entrées cessent de fonctionner si l'une est arrêtée, demandé directement à Windows plutôt que déduit de ce que chacun déclare. Un appel par entrée, donc désactivé sauf demande. `show` et `snapshot create` le lisent à chaque fois.	`list`
`--follow-network`	Laisser l'outil sortir de cette machine, quoi que ce soit - un chemin de lancement situé sur le partage de quelqu'un d'autre, et un certificat que cette machine n'a pas déjà. Désactivé par défaut par sécurité : un partage injoignable coûte vingt et une secondes et s'authentifie comme celui qui a lancé l'outil, et récupérer un certificat est une connexion à un tiers au milieu d'un simple listage. Sans lui, une signature est vérifiée contre ce qui est ici, et un résultat qui pourrait venir d'un défaut de recherche est signalé comme non lu plutôt que comme un verdict.	`list`, `show`, `snapshot create`
`--force`	Sur `kill`, terminer le processus tout de suite sans demander poliment - l'aperçu montre alors une étape au lieu de deux. Sur `snapshot create`, remplacer un instantané déjà présent - un fichier qui n'est pas un instantané n'est jamais remplacé.	`snapshot create`, `kill`
`--restart`	Sur `kill`, remettre l'entrée en route une fois le processus disparu, avec tout ce qui le partageait.	`kill`
`--stop`	Sur `start-type`, et seulement à côté de `disabled`, arrêter l'entrée dans le même plan une fois le réglage écrit. Un type de démarrage change le prochain démarrage et rien maintenant, donc sans cette option une entrée en marche réglée sur désactivé continue de tourner.	`start-type`
`--full`	Sur `show`, afficher aussi les champs réellement vides. Un champ que personne n'a pu lire est affiché dans tous les cas.	`show`
`--json`	Le même document, lisible par une machine, sur la sortie standard.	`list`, `show`, `stop`, `start`, `restart`, `start-type`, `snapshot create`, `snapshot diff`, `kill`, `history`, `tool fix NAME`
`--note`	Ce pour quoi l'instantané a été pris, conservé dans le fichier.	`snapshot create`
`--exit-code`	Se terminer par le code 5 quand la configuration diffère - une entrée ajoutée ou supprimée, ou une entrée configurée autrement. L'état d'exécution seul ne compte pas. Désactivé par défaut, pour qu'un script qui veut seulement les différences imprimées ne soit pas pris de court d'en trouver.	`snapshot diff`
`--live`	Comparer le fichier à cette machine telle qu'elle est maintenant, plutôt qu'à un second fichier.	`snapshot diff`
`--timing`	Combien de temps a pris chaque partie de la lecture, sur l'erreur standard.	`list`, `show`, `stop`, `start`, `restart`, `start-type`, `snapshot create`, `snapshot diff`, `kill`, `history`, `tool fix NAME`
`--dry-run`	Afficher le plan et ne rien changer. C'est le même plan qu'exécute une vraie exécution - il n'y a pas de second chemin de code pour la vraie chose.	`stop`, `start`, `restart`, `start-type`, `kill`, `tool fix NAME`
`--dependents`	Mettre dans le plan les services qui cesseraient de fonctionner, comme des étapes à part entière.	`stop`, `restart`, `kill`
`--timeout`	Combien de temps une étape peut durer sans progrès avant d'être abandonnée, recompté à chaque fois que le service signale un progrès. Soixante secondes sauf indication contraire. Un service qui continue de signaler un progrès est surveillé aussi longtemps qu'il le faut. Le délai écoulé est la fin de la surveillance et non un échec, et le rapport dit où l'entrée a été laissée.	`stop`, `start`, `restart`, `kill`, `tool fix NAME`
`--components`	Sur `license`, transformer la mention en chaque composant de cet exécutable avec sa version, sa licence et son origine. Le même ensemble que porte la nomenclature publiée à côté du téléchargement, parce que les deux sont produites depuis un seul registre.	`license`

Codes de sortie

6 fins, et chacune est une chose différente à faire pour un script. Les données vont sur la sortie standard et tout le reste sur l'erreur standard, de sorte que bws list --json | jq fonctionne et qu'un avertissement n'atterrit jamais dans votre JSON.

Tout document JSON est de l'ASCII pur : une lettre hors de l'ASCII est écrite comme une séquence d'échappement de six caractères que tout lecteur JSON retransforme en lettre, de sorte que bws list --json > file.json est de l'UTF-8 valide et que | ConvertFrom-Json le lit correctement quelle que soit la page de codes de la console. Dans le texte qu'une personne lit, un caractère qui déplacerait le terminal au lieu de s'imprimer - une tabulation, un saut de ligne, une séquence d'échappement, un forçage de direction - est affiché sous la forme de son point de code, <U+001B>.

-- termine les options, de sorte qu'un service dont le nom commence par un tiret peut quand même être nommé : bws show -- -odd. Les lignes de commande que l'outil vous remet sont écrites pour PowerShell : un nom contenant une espace va entre guillemets doubles, que cmd lit de la même façon, et un nom que PowerShell développerait à l'intérieur, comme MSSQL$SQLEXPRESS, va entre guillemets simples.

Code	Signification
`0`	Terminé, et tout est arrivé là où cela devait aller.
`1`	L'outil a échoué - il n'a pas pu faire ce qui lui était demandé, pour une raison qui tient à l'outil et non au plan.
`2`	La ligne de commande était erronée. Une commande mal orthographiée se voit proposer celle que vous vouliez probablement.
`3`	Le plan était bon, il s'est exécuté, et quelque chose dedans n'est pas arrivé là où cela devait aller - le gestionnaire a refusé, ou la session n'y avait pas droit.
`4`	Quelqu'un a arrêté l'exécution à la main. Non nul même si chaque étape était arrivée, de sorte qu'un script enveloppant ne traite pas une exécution interrompue comme propre.
`5`	Une comparaison s'est exécutée et a trouvé la configuration dérivée - une entrée ajoutée ou supprimée, ou une entrée configurée autrement. L'état d'exécution seul n'est pas une dérive. Seulement avec `--exit-code`, car trouver une dérive est ce pour quoi cet outil existe, et la trouver n'est pas un échec.

Ctrl+C a trois niveaux, chacun disant ce que coûte le suivant. Le premier cesse d'avancer et remet quand même en place ce qui a été pris, le deuxième laisse les choses en l'état et imprime quand même le rapport, le troisième termine le processus. Une exécution arrêtée à la main se termine par 4 même si chaque étape était arrivée.

Fermer la fenêtre de la console compte comme le premier Ctrl+C. Windows donne cinq secondes à un programme après cela, et pendant ce temps celui-ci cesse d'avancer et remet en place ce qu'il avait arrêté. Se déconnecter et éteindre le terminent sans aucun avertissement auquel il pourrait réagir, et une session distante interrompue peut le faire aussi.

Dans une tâche planifiée

La forme pour laquelle cet outil a été conçu : figer la machine quand elle est réputée saine, puis demander chaque nuit si elle l'est encore.

# le jour où la machine entre en service
bws snapshot create C:\baselines\web01.json --note "after the build"

# chaque nuit, depuis une tâche planifiée
bws snapshot diff C:\baselines\web01.json --live --exit-code --json > C:\logs\drift.json
#   0 - aucune dérive de configuration
#   5 - la configuration a dérivé, et drift.json dit en quoi
#   3 - elle a tourné et n'a pas pu tout lire, la réponse est donc partielle

La fenêtre est l'autre moitié du même moteur : BetterWindowsServices-win-x64.zip la contient, et la page de téléchargement dit ce qu'est chaque archive.

L'argument de la fenêtre

BetterWindowsServices.exe prend un argument destiné à une personne : --catalogue ouvre une feuille de développeur montrant chaque composant de la fenêtre dans chaque état, et ne lit rien sur votre machine. Un second, --carry, est la façon dont une fenêtre transmet ce qu'elle montrait à la copie d'elle-même qu'elle relance en administrateur. Personne ne le tape, et tout ce qu'il contient que cette fenêtre n'aurait pas pu écrire est refusé.