Referência

Referência da linha de comando

Cada comando, cada opção e cada código de saída do bws, versão 0.5.0. O bws --help é a fonte autorizada e é mais longo - esta página é a mesma superfície, organizada para ser lida.

Os comandos

Onze comandos. O snapshot é um substantivo e recebe uma palavra depois dele. O tool também é, e sozinho lista as ferramentas.

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

A um comando digitado errado é oferecido o que você provavelmente quis dizer, e a execução termina com o código 2 em vez de fazer algo parecido com o que você pediu.

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

O que cada comando faz

`list` e `show`

O list é a máquina inteira, restringida por --query. O show é uma entrada com tudo o que se sabe sobre ela - a assinatura, os privilégios, o descritor de segurança e a memória, tudo lido a cada vez, porque em uma só entrada isso custa cerca de sessenta milissegundos, enquanto na máquina inteira custa um segundo. Campos realmente vazios são omitidos, a menos que você passe --full. Um campo que ninguém conseguiu ler é impresso de qualquer jeito, porque omiti-lo pareceria uma resposta.

`stop`, `start` e `restart`

Cada um constrói um plano e o executa. --dry-run imprime o plano e não muda nada, --dependents coloca nele os serviços que deixariam de funcionar como etapas próprias, e --timeout diz quanto tempo uma etapa pode ficar sem progresso. Drivers são recusados em vez de tentados, porque parar um driver de kernel muitas vezes não é reversível sem reiniciar.

`kill` - para um serviço que não para

Ele pede ao serviço que pare e encerra o processo por trás dele somente se isso não funcionar, de modo que uma entrada que para sozinha nunca é encerrada. Encerrar um processo leva consigo todos os outros serviços que vivem nele, tenham parado antes ou não, e a pré-visualização os nomeia e nomeia o processo pelo número. --force pula a etapa educada e a pré-visualização mostra então uma etapa em vez de duas. --restart traz tudo de volta depois.

O Windows escreve esta ideia de forma diferente. --force no Stop-Service significa "mesmo que algo dependa dele", que é o que o --dependents faz aqui. É por isso que este é um comando próprio e não uma opção do stop.

`start-type` - uma configuração, não um movimento

Diz o que o gerenciador fará com uma entrada na próxima inicialização, e sem --stop não move nada: uma entrada que está em execução continua em execução, uma parada continua parada, e o plano diz isso. disabled é o que merece uma pausa, porque impede o gerenciador de iniciar a entrada, inclusive sob demanda para outra coisa que precise dela. delayed é automático, iniciado um pouco depois das outras entradas automáticas - a palavra que start:delayed pergunta em uma consulta - e o Windows o recusa para uma entrada em um grupo de ordem de carga, o que o plano diz antes de qualquer coisa acontecer. Cada um dos quatro grava se a entrada inicia tarde, como o sc.exe faz. --stop, só ao lado de disabled, para a entrada no mesmo plano depois que a configuração é gravada.

`snapshot create` e `snapshot diff`

O create sempre lê assinaturas e hashes, porque um instantâneo é guardado e comparado depois, e um sem eles comparado com um que os tem seria tratado como se a máquina tivesse mudado. O diff diz o que mudou indo do primeiro arquivo para o segundo, ou de um arquivo para esta máquina com --live. A página de instantâneos traz o formato e o raciocínio.

`history` - quem mudou, pelo log do Sistema

Mudanças de tipo de inicialização e instalações do log do Sistema, as mais recentes primeiro, com a conta que o Windows registrou. A primeira linha diz até onde o log alcança e se foi limpo, porque um histórico é tão longo quanto o log. Com um nome, são as mudanças de tipo de inicialização daquele serviço - instalações só são listadas sem nome, porque o Windows registra uma instalação sob o nome de exibição e nunca sob o nome do serviço. Uma conta é nomeada onde esta máquina consegue nomeá-la por conta própria e mostrada como SID caso contrário, e os tipos de inicialização vêm nas palavras que o Windows escreveu.

`tool` - respostas prontas para problemas comuns

As mesmas ferramentas que a janela mostra na aba Tools. O bws tool as lista e o bws tool fix lista as correções rápidas: printer, sound, indexing e search, cada uma uma reinicialização de um serviço do Windows junto com o que depende dele, escolhidas porque as próprias páginas de solução de problemas da Microsoft sugerem isso. O bws tool fix printer é exatamente bws restart Spooler --dependents - o mesmo plano, a mesma saída e os mesmos códigos de saída - e, como todo comando aqui que muda algo, não pergunta antes, então --dry-run é o jeito de olhar antes de executar.

`license` - o que há dentro do arquivo que você baixou

Não lê nada - nem gerenciador de serviços, nem disco, nem rede - e responde a partir de um registro compilado no executável. --components transforma o aviso em cada componente com sua versão, sua licença e sua origem. O mesmo conjunto que a lista de materiais publicada ao lado do download traz, porque as duas são geradas de um único registro, e o motivo pelo qual vale a pena: o programa é um arquivo autônomo, então não há nada ao lado dele para um scanner ler.

Exemplos

Os planos abaixo foram conferidos com --dry-run contra o programa que esta página descreve. Um comando que muda algo não pergunta antes, então --dry-run é o jeito de olhar antes de executar. Spooler representa qualquer serviço - coloque no lugar dele o nome do seu.

Encontrar e ler

bws list                                       cada serviço e driver desta máquina
bws list --query "start:auto !status:running"  o que deveria estar no ar e não está
bws list --query "status:running" --memory     o que o processo de cada entrada em execução usa
bws show Spooler                               tudo o que se sabe sobre uma entrada
bws show Spooler --full                        também os campos realmente vazios

Olhar primeiro, mudar depois

bws restart Spooler --dry-run                o plano, e nada mais
bws restart Spooler --dependents             reiniciá-lo junto com o que depende dele
bws stop Spooler --dependents --timeout 120  permitir dois minutos por etapa sem progresso
bws start-type WSearch delayed --dry-run     iniciá-lo um pouco depois das outras entradas automáticas
bws start-type Spooler disabled --stop       desabilitá-lo e pará-lo em um só plano

Um serviço que não para

bws kill Spooler --dry-run          o processo, e cada serviço que vive nele
bws kill Spooler --restart          encerrar o processo só se uma parada falhar, depois trazer tudo de volta
bws kill Spooler --force --dry-run  uma etapa em vez de duas: o processo encerrado na hora

Instantâneos e deriva

bws snapshot create before.json --note "before the patch"  congelar a máquina, com uma nota guardada dentro
bws snapshot diff before.json after.json                   dois arquivos - dois dias, ou duas máquinas
bws snapshot diff before.json --live                       o arquivo contra esta máquina como está agora
bws snapshot diff before.json --live --exit-code           o mesmo, terminando com 5 se a configuração se desviou

Quem mudou

bws history          cada mudança de tipo de inicialização e instalação que o log do Sistema guarda
bws history Spooler  as mudanças de tipo de inicialização de um serviço
bws history --json   o mesmo como documento, com log e mudanças

Correções rápidas

bws tool                      as ferramentas que existem
bws tool fix                  as correções rápidas, e o serviço por trás de cada uma
bws tool fix sound --dry-run  o plano para reiniciar os dois serviços de áudio
bws tool fix printer          reiniciar o Spooler de Impressão com o que depende dele

O que há dentro do arquivo

bws license --components  cada componente, sua versão, sua licença e sua origem
bws --version             a versão deste executável

Em um script do PowerShell

# as entradas que deveriam estar no ar e não estão, como objetos
bws list --query "start:auto !status:running" --json | ConvertFrom-Json | Select-Object serviceName, displayName, status

# os arquivos sem assinatura, para uma planilha
bws list --query "signed:no" --json | ConvertFrom-Json | Select-Object serviceName, binaryPath | Export-Csv unsigned.csv -NoTypeInformation

# de que um serviço precisa
(bws show Spooler --json | ConvertFrom-Json).dependsOn

# uma verificação noturna que se ramifica pelo código de saída
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" }
}

No cmd e em um arquivo em lote

rem um segundo comando só quando o primeiro não terminou limpo
bws restart Spooler || echo the restart did not end cleanly

rem em um arquivo em lote com expansão atrasada ligada, o ! precisa de um acento circunflexo
bws list --query "start:auto ^!status:running"

Opções

18 no total. A terceira coluna traz os comandos a que cada uma pertence - uma opção passada a um comando que não tem uso para ela é um erro com essa lista dentro, em vez de uma flag ignorada em silêncio.

Opção	O que faz	Onde atua
`--query`	Restringir a listagem com a linguagem de consulta.	`list`
`--signatures`	Ler quem assinou cada executável e se o Windows confia nele. Vários segundos em uma máquina inteira, então fica desligado a menos que seja pedido - e uma consulta sobre assinaturas o liga sozinha.	`list`
`--memory`	Ler o que o processo de cada entrada em execução está usando. Desligado por padrão porque é uma medição e não uma configuração: um segundo depois ela é diferente.	`list`
`--required-by`	Ler quais entradas deixam de funcionar se uma for parada, perguntado diretamente ao Windows em vez de deduzido do que cada uma declara. Uma chamada por entrada, então fica desligado a menos que seja pedido. `show` e `snapshot create` o leem toda vez.	`list`
`--follow-network`	Deixar a ferramenta sair desta máquina, de qualquer modo - um caminho de lançamento que vive no compartilhamento de outra pessoa, e um certificado que esta máquina ainda não tem. Desligado por padrão por segurança: um compartilhamento inalcançável custa vinte e um segundos e se autentica como quem executou, e buscar um certificado é uma conexão com um terceiro no meio de uma listagem comum. Sem ele, uma assinatura é verificada contra o que há aqui, e um resultado que pode ter sido causado por não olhar é informado como não lido e não como um veredito.	`list`, `show`, `snapshot create`
`--force`	No `kill`, encerrar o processo na hora sem pedir com educação - a pré-visualização mostra então uma etapa em vez de duas. No `snapshot create`, substituir um instantâneo que já existe - um arquivo que não é um instantâneo nunca é substituído.	`snapshot create`, `kill`
`--restart`	No `kill`, trazer a entrada de volta depois que o processo some, junto com tudo o que o dividia.	`kill`
`--stop`	No `start-type`, e só ao lado de `disabled`, parar a entrada no mesmo plano depois que a configuração é gravada. Um tipo de inicialização muda a próxima inicialização e nada agora, então sem ele uma entrada em execução configurada como desabilitada continua rodando.	`start-type`
`--full`	No `show`, imprimir também os campos realmente vazios. Um campo que ninguém conseguiu ler é impresso de qualquer jeito.	`show`
`--json`	O mesmo documento, legível por máquina, na saída padrão.	`list`, `show`, `stop`, `start`, `restart`, `start-type`, `snapshot create`, `snapshot diff`, `kill`, `history`, `tool fix NAME`
`--note`	Para que o instantâneo foi feito, guardado dentro do arquivo.	`snapshot create`
`--exit-code`	Terminar com o código 5 quando a configuração difere - uma entrada adicionada ou removida, ou uma configurada de outro jeito. O estado de execução sozinho não conta. Desligado por padrão, para que um script que só quer as diferenças impressas não tropece em encontrar algumas.	`snapshot diff`
`--live`	Comparar o arquivo com esta máquina como está agora, em vez de com um segundo arquivo.	`snapshot diff`
`--timing`	Quanto tempo levou cada parte da leitura, no erro padrão.	`list`, `show`, `stop`, `start`, `restart`, `start-type`, `snapshot create`, `snapshot diff`, `kill`, `history`, `tool fix NAME`
`--dry-run`	Imprimir o plano e não mudar nada. É o mesmo plano que uma execução roda - não existe um segundo caminho de código para a execução de verdade.	`stop`, `start`, `restart`, `start-type`, `kill`, `tool fix NAME`
`--dependents`	Colocar no plano, como etapas próprias, os serviços que deixariam de funcionar.	`stop`, `restart`, `kill`
`--timeout`	Quanto tempo uma etapa pode ficar sem progresso antes de ser abandonada, contado de novo toda vez que o serviço informa progresso. Sessenta segundos, a menos que você diga outra coisa. Um serviço que continua informando progresso é observado pelo tempo que for preciso. Esgotar o prazo é o fim da observação e não uma falha, e o relatório diz onde a entrada foi deixada.	`stop`, `start`, `restart`, `kill`, `tool fix NAME`
`--components`	No `license`, transformar o aviso em cada componente dentro deste executável com sua versão, sua licença e sua origem. O mesmo conjunto que a lista de materiais publicada ao lado do download traz, porque as duas são geradas de um único registro.	`license`

Códigos de saída

6 desfechos, e cada um é uma coisa diferente para um script fazer. Os dados vão para a saída padrão e todo o resto para o erro padrão, de modo que bws list --json | jq funciona e um aviso nunca cai no seu JSON.

Todo documento JSON é ASCII puro: uma letra fora dele é escrita como uma sequência de escape de seis caracteres que todo leitor de JSON converte de volta na letra, de modo que bws list --json > file.json é UTF-8 válido e | ConvertFrom-Json o lê direito seja qual for a página de código do console. No texto que uma pessoa lê, um caractere que moveria o terminal em vez de ser impresso - uma tabulação, uma quebra de linha, uma sequência de escape, uma substituição de direção - é mostrado como seu ponto de código, <U+001B>.

-- encerra as opções, de modo que um serviço cujo nome começa com um hífen ainda pode ser nomeado: bws show -- -odd. As linhas de comando que a ferramenta entrega a você são escritas para o PowerShell: um nome com espaço vai entre aspas duplas, que o cmd lê do mesmo jeito, e um nome que o PowerShell expandiria dentro delas, como MSSQL$SQLEXPRESS, vai entre aspas simples.

Código	Significado
`0`	Feito, e tudo chegou aonde ia.
`1`	A ferramenta falhou - não conseguiu fazer o que foi pedido, por um motivo que é da ferramenta e não do plano.
`2`	A linha de comando estava errada. A um comando digitado errado é oferecido o que você provavelmente quis dizer.
`3`	O plano era bom, foi executado, e algo nele não chegou aonde ia - o gerenciador recusou, ou a sessão não tinha direitos sobre aquilo.
`4`	Alguém parou a execução à mão. Diferente de zero mesmo que cada etapa tenha chegado, para que um script em volta não trate uma execução interrompida como limpa.
`5`	Uma comparação rodou e encontrou a configuração desviada - uma entrada adicionada ou removida, ou uma configurada de outro jeito. O estado de execução sozinho não é deriva. Somente com `--exit-code`, porque encontrar deriva é para o que esta ferramenta serve, e encontrá-la não é uma falha.

O Ctrl+C tem três níveis, cada um dizendo o que o próximo custa. O primeiro para de avançar e ainda recoloca o que foi tirado, o segundo deixa as coisas como estão e ainda imprime o relatório, o terceiro encerra o processo. Uma execução parada à mão termina com 4 mesmo que cada etapa tenha chegado.

Fechar a janela do console conta como o primeiro Ctrl+C. O Windows dá cinco segundos a um programa depois disso, e neles este para de avançar e recoloca o que tinha derrubado. Fazer logoff e desligar o encerram sem nenhum aviso a que ele possa reagir, e uma sessão remota interrompida também pode.

Em uma tarefa agendada

A forma para a qual esta ferramenta foi construída: congelar a máquina quando se sabe que está boa, depois perguntar toda noite se ainda está.

# o dia em que a máquina entra em serviço
bws snapshot create C:\baselines\web01.json --note "after the build"

# toda noite, a partir de uma tarefa agendada
bws snapshot diff C:\baselines\web01.json --live --exit-code --json > C:\logs\drift.json
#   0 - sem deriva de configuração
#   5 - a configuração se desviou, e drift.json diz o quê
#   3 - rodou e não conseguiu ler tudo, então a resposta é parcial

A janela é a outra metade do mesmo motor: BetterWindowsServices-win-x64.zip a contém, e a página de download diz o que é cada arquivo.

O argumento da janela

O BetterWindowsServices.exe aceita um argumento pensado para uma pessoa: --catalogue abre uma folha de desenvolvedor mostrando cada componente da janela em cada estado, e não lê nada da sua máquina. Um segundo, --carry, é como uma janela entrega o que estava mostrando à cópia de si mesma que reinicia como administrador. Ninguém o digita, e tudo nele que aquela janela não poderia ter escrito é recusado.